Form Layout

Use the Form Layout component to arrange a layout of form elements with preset spacing. Refer to our form pattern for additional guidance on types of forms and common form fields.

The different parts of the Form Layout component are:

1. Form: renders an HTML form element and comes with default behavior from the browser (learn more about HTML form elements).
2. FormControl: Contains form fields, which are the UI components where users enter information.
3. FormControlTwoColumn: A group of two FormControls arranged horizontally.
4. FormSection: A group of FormControls that renders an HTML fieldset.
5. FormSectionHeading and FormSectionDescription: Use FormSectionHeading and FormSectionDescription to render a HTML legend which clearly describes the FormSection.
6. FormActions: A group of buttons often with a primary Button ordered first, followed by a secondary Button.

• Connect each form field to its associated Label with the htmlFor prop on the label, and the id prop on the input. Those two need to match.
• If the form field has any associated Help Text, the field should also use the aria-describedby prop that equals the id of the help text. This ensures screen readers know the Help Text ties directly to the field.
• Only use a single Form per page unless absolutely necessary. If using multiple Forms on a single page, take extra caution to ensure each form field's attributes are unique."
• Don’t use CSS to control element order. Form Layout elements should be displayed in the same order in the HTML as they appear on screen, as screen readers announce form elements in the order they appear in the HTML. The order in which form elements are presented on a webpage should be logical and meaningful. Reference: WCAG
• Don't ask for the same information twice in the same session. Reference: WCAG
• Provide accessible error identification and messaging. Reference: WCAG
• Group related fields using fieldsets and legends with FormSection and FormSectionHeading, which render an HTML fieldset and legend. Reference: WebAIM
• Use a single column layout, as it can be more difficult for users with limited vision to scan from right to left if a multi-column layout is used.

We recommend using single-column layouts for forms because they are easier to read. To learn more, check out this research on form readability.

Use more than 1 column only when it is clearer than a single column and prevents users from inputting incorrect information. Reserve 2-column layouts for when form fields are organized as a coherent entity, like date ranges; first and last name; ZIP, city, and state; or credit card details.

Use a horizontal form field layout for Checkbox and Radio Groups when options can be placed next to each other in a logical order and the labels for each option are shorter than 3 words.

Complex forms should be split into sections, using FormSection which renders an HTML fieldset. When using multiple FormSections, place a Separator between them.

Optionally, each section can include a:

• Heading, known as a legend
• Paragraph to explain the section.

Use the maxWidth prop and a size token to set a max width on the form. When no max width is set, the form will be set to 100% of the parent container.

Ensure that field lengths provide both:

• Meaningful affordances that help people answer questions
• Enough room for inputs across multiple languages.

Designing a good form requires making decisions about composition, sequence, form elements, content, and feedback. Use the form pattern for further guidance on form order and organization.

Keep forms left-aligned to improve scannability and help users quickly understand the required information. This also makes it easier for keyboard users to tab through fields.

• Confirmation
• Create
• Error state
• Form pattern
• Notifications and Feedback
• Privacy
• Settings
• Wizard