Form

A form groups related form elements that allow users to input information or configure options.

Version 11.1.1

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('address-heading')}>
      <Heading
        as="h3"
        variant="heading30"
        id={seed('address-heading')}
        marginBottom='space0'
      >
        Create new address
      </Heading>
      <FormControl>
        <Label htmlFor={seed('address-type')}>Address type</Label>
        <Select id={seed('address-type')} name="address-type">
          <Option value="1">Option 1</Option>
          <Option value="2">Option 2</Option>
        </Select>
      </FormControl>
      <FormControl>
        <Label htmlFor={seed('friendly-name')}>Friendly name</Label>
        <Input
          type="text"
          id={seed('friendly-name')}
          name="friendly-name"
          placeholder="Add friendly name"
        />
      </FormControl>
      <FormControl>
        <RadioGroup
          legend="Address implementation"
          name="address-implementation"
        >
          <Radio
            value="conversations"
            helpText="Supports both inbound and outbound SMS and attachments."
          >
            Conversations
          </Radio>
          <Radio
            value="legacy"
            helpText="Supports inbound SMS."
          >
            Legacy
          </Radio>
        </RadioGroup>
      </FormControl>
      <FormActions>
        <Button variant="primary">Submit</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Guidelines

About Form

Use the Form component to arrange a layout of form elements with preset spacing. The Form component renders an HTML form element and comes with default behavior from the browser (learn more about HTML form elements). Form elements are displayed vertically by default, but also support horizontal and 2-column layouts.

Common form components include Buttons, Comboboxes, Checkboxes, Date Picker, File Picker, Form Pill Groups, Help Text, Inputs, Label, Radio Group, Selects, Switch, Textarea, and Time Picker.

Designing a good form requires making decisions about composition, sequence, form elements, copy, and feedback.

Forms often have a header, with a Heading and Paragraph that explains the purpose of the form or form section. The header can also include additional contextual components like Alerts or Callouts for expressing errors or other important information.
Forms can include form actions, often with a primary Button ordered first, then a secondary Button second.
More complex forms should be split into sections, known as fieldsets. Form sections are separated with a Separator. Sections often have their own header, with a Heading, known as a legend, and can also include a Paragraph to explain the section.

Accessibility

Order

Order forms sequentially, following the natural flow of the user's language preference. Typically top to bottom, and left to right for Latin-based languages.
Only use a single Form per page.
Don’t use CSS to control element order. Form 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.

Content

Provide accessible and clear Labels and Help Text.
- Labels should clearly describe the value being requested.
- Labels should be short and succinct, generally 1-3 words.
- Help Text is optional. Use it to describe what makes the form field successful and help users avoid errors.
- Avoid placeholder text. It is not broadly supported by assistive technologies, does not display in older browsers, and disappears from the field when a user enters text.
Use fieldsets and legends.
- When you need to group related form elements, use a form section, which renders a HTML fieldset. To add clarity to the section, use a form section Heading, which renders a HTML legend, to clearly describe the group. It should be concise and descriptive.
- You can have nested form sections if applicable.
- Embed multiple fieldsets and legends for more complex forms.
Use Help Text for form validation errors. For successful submissions, use a Toast

Composition

Don’t make the user repeat information. For example, asking for users to input a shipping address and billing address if the address is the same information.
Mark all required form elements as required.
Consider breaking long forms into smaller sections or pages, as they can place more cognitive load on the user.
Follow best practices for accessibility for each component used within the Form.
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.

Keyboard interaction

There are no special keyboard interactions for the Form component. The user should be able to tab through the form elements in the natural tab order.

Examples

Sample form

This example combines all of the separate features of the Form component into one. It shows how all the features work together harmoniously through a composition.

(information)

Accessibility insight

Make sure to connect the Label to the Input. This is done with the htmlFor prop on the label, and the id prop on the input. Those two need to match.

If the input has any associated help text, the input 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 input.

Single column

Single-column layouts are easier to read. To learn more, check out some research on form readability. Horizontal layouts can create problems for people who rely on the structural layout of the page. Read more on single column vs. multi-column layouts.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('address-heading')}>
      <Heading
        as="h3"
        variant="heading30"
        id={seed('address-heading')}
        marginBottom='space0'
      >
        Create new address
      </Heading>
      <FormControl>
        <Label htmlFor={seed('address-type')}>Address type</Label>
        <Select id={seed('address-type')} name="address-type">
          <Option value="1">Option 1</Option>
          <Option value="2">Option 2</Option>
        </Select>
      </FormControl>
      <FormControl>
        <Label htmlFor={seed('friendly-name')}>Friendly name</Label>
        <Input
          type="text"
          id={seed('friendly-name')}
          name="friendly-name"
          placeholder="Add friendly name"
        />
      </FormControl>
      <FormControl>
        <RadioGroup
          legend="Address implementation"
          name="address-implementation"
        >
          <Radio
            value="conversations"
            helpText="Supports both inbound and outbound SMS and attachments."
          >
            Conversations
          </Radio>
          <Radio
            value="legacy"
            helpText="Supports inbound SMS."
          >
            Legacy
          </Radio>
        </RadioGroup>
      </FormControl>
      <FormActions>
        <Button variant="primary">Submit</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

2 column

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 inputs are organized linearly or as a coherent entity, like dates, first and last name, or, ZIP, city, and state or credit card details fields. Read more on single column vs. multi-column layouts.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('date-time-heading')}>
      <Heading as="h3" variant="heading30" id={seed('date-time-heading')} marginBottom='space0'>
        Custom date/time range
      </Heading>
      <Paragraph marginBottom="space0">
        All dates/times in UTC. Usage data available up to 7 days.
      </Paragraph>
      <FormControlTwoColumn>
        <FormControl>
          <Label htmlFor={seed('start-date')}>
            Start date
          </Label>
          <DatePicker id={seed('start-date')}/>
        </FormControl>
        <FormControl>
          <Label htmlFor={seed('end-date')}>
            End date
          </Label>
          <DatePicker id={seed('end-date')}/>
        </FormControl>
      </FormControlTwoColumn>
      <FormControlTwoColumn>
        <FormControl>
          <Label htmlFor={seed('start-time')}>
            Start time
          </Label>
          <TimePicker id={seed('start-time')}/>
        </FormControl>
        <FormControl>
          <Label htmlFor={seed('end-time')}>
            End time
          </Label>
          <TimePicker id={seed('end-time')}/>
        </FormControl>
      </FormControlTwoColumn>
      <FormActions>
        <Button variant="primary">Apply</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Horizontal layouts

Use a horizontal layout when options can be placed next to each other in a logical order and the labels for each element are shorter than 3 words.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('access-profile-heading')}>
      <Heading
        as="h3"
        variant="heading30"
        id={seed('access-profile-heading')}
        marginBottom='space0'
      >
        Choose Network Access Profile
      </Heading>
      <Paragraph marginBottom="space0">
        Network Access Profile specifies what networks your SIM's would connect to and how you will be billed.
      </Paragraph>
      <FormControl>
        <CheckboxGroup
          legend="Select number type"
          name="number-type"
          orientation="horizontal"
        >
          <Checkbox checked value="local">Local</Checkbox>
          <Checkbox value="mobile">Mobile</Checkbox>
          <Checkbox value="toll-free">Toll-free</Checkbox>
        </CheckboxGroup>
      </FormControl>
      <FormControl>
        <RadioGroup
          legend="Select payment method"
          name="payment-method"
          orientation="horizontal"
        >
          <Radio value="cc">Credit card</Radio>
          <Radio value="pp">PayPal</Radio>
          <Radio value="dd">Direct deposit</Radio>
        </RadioGroup>
      </FormControl>
      <FormActions>
        <Button variant="primary">Save</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Sections

Use sections to group related content or steps within a Form. A section is separated using a Separator, with $space-90 above and below it.

Section headings and descriptions are optional.

If a form element doesn’t belong to a form sections, make sure there's at least $space-130 between the form element and surrounding sections.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('alarm-heading')}>
      <Heading
        as="h3"
        variant="heading30"
        id={seed('alarm-heading')}
        marginBottom='space0'
      >
        Create alarm
      </Heading>
      <Paragraph marginBottom="space0">
        Use alarms to get alerted to important events happening with your account.
      </Paragraph>
      <FormSection>
        <FormSectionHeading>
          Step 1
        </FormSectionHeading>
        <FormSectionDescription>
          Name your alarm and select the error code you’d like to set an alarm. Use the historical trend graph for reference.
        </FormSectionDescription>
        <FormControl>
          <Label htmlFor={seed('alarm-name')}>Alarm name</Label>
          <Input
            type="text"
            id={seed('alarm-name')}
            aria-describedby={seed('alarm-help-text')}
          />
          <HelpText id={seed('alarm-help-text')}>
            Consider a recognizable name related to its use case.
          </HelpText>
        </FormControl>
        <FormControl>
          <Label htmlFor={seed('error-code')}>Select error code</Label>
          <Input
            id={seed('error-code')}
            type="text"
            value="11200 - HTTP retrieval failure"
            insertAfter={
              <SearchIcon color="colorTextIcon" decorative/>
            }
          />
        </FormControl>
      </FormSection>
      <Separator orientation="horizontal"/>
      <FormSection>
        <FormSectionHeading>
          Step 2
        </FormSectionHeading>
        <FormSectionDescription>
          Determine when the alarm should be activated.
        </FormSectionDescription>
        <FormControl>
          <Label htmlFor={seed('num-errors')}>
            Number of errors
          </Label>
          <Input
            type="text"
            id={seed('num-errors')}
            value="20"
          />
        </FormControl>
        <FormControl>
          <Label htmlFor={seed('time-period')}>
            Time period
          </Label>
          <Select id={seed('time-period')}>
            <Option value="minute">Every minute</Option>
            <Option value="hour">Every hour</Option>
            <Option value="day">Every day</Option>
          </Select>
        </FormControl>
      </FormSection>
      <FormActions>
        <Button variant="primary">Save</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Form actions

A Form can include form actions if placed within a page or page section. Using form actions helps keep the form elements left-aligned for better scannability of the content and its related actions. Don't prevent form submission by disabling the submit button. Use error messages to explain what information is missing or incorrect.

const FormActionsExample = () => {
  return (
    <FormActions>
      <Button variant="primary">Submit</Button>
      <Button variant="secondary">Cancel</Button>
    </FormActions>
  );
}

render(
  <FormActionsExample />
)

Validation

Use validation and error messaging to indicate when a form submission fails or requires additional information to be shown.

Validate form fields on form submission. Validating a form field when the user leaves the current field (on blur) can be helpful to check for syntax errors. However, this can be frustrating to users who tab through controls to navigate a page, and to screen reader users, who might not be able to detect that an error occurred on blur.

Don't prevent form submission by disabling the submit button. Assistive technologies cannot detect disabled buttons. Use error messages to explain what information is missing or incorrect.

Errors

Use Help Text to show inline error messaging that informs users that they cannot continue. Provide guidance on next steps and how to remedy the situation.

If there are multiple errors, use Help Text to show inline error messages and a Callout to show an error summary. Place the Callout below the form title or section title, if applicable, and above the form elements.

If the Form lives within a Modal or Side Modal and has a form action to submit or save the information, we suggest closing the Modal on submit, then display a Toast that indicates the action was successful or experienced a system error.

Error messaging for required fields should explain how to resolve the error and not reiterate that the field is required. The required field indicator is sufficient. For additional guidance on how to compose error messages, refer to the error state pattern.

Ideally, Help Text should have enough information to help users prevent errors. If Help Text is already on a form field, change it to variant=“error” and add error copy before the original help text copy.

const statesList = [
  {value: 'AK', name: 'Alaska'},
  {value: 'AL', name: 'Alabama'},
  {value: 'AZ', name: 'Arizona'},
  {value: 'CA', name: 'California'},
  {value: 'CO', name: 'Colorado'},
  {value: 'CT', name: 'Connecticut'},
  {value: 'ID', name: 'Idaho'},
  {value: 'IL', name: 'Illinois'},
  {value: 'IN', name: 'Indiana'},
  {value: 'KS', name: 'Kansas'},
  {value: 'KY', name: 'Kentucky'},
  {value: 'LA', name: 'Louisiana'},
  {value: 'MN', name: 'Minnesota'},
  {value: 'MO', name: 'Missouri'},
  {value: 'MS', name: 'Mississippi'},
  {value: 'MT', name: 'Montana'},
];

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('settings-heading')}>
      <Heading
        id={seed('settings-heading')}
        variant="heading30"
        marginBottom="space0"
      >
        Settings
      </Heading>
      <Callout variant="error">
        <CalloutHeading as="h4">
          These fields are missing values:
        </CalloutHeading>
        <CalloutList as="ul">
          <CalloutListItem>Street address</CalloutListItem>
          <CalloutListItem>Zip code</CalloutListItem>
          <CalloutListItem>Email address</CalloutListItem>
        </CalloutList>
      </Callout>
      <FormControl>
        <Label htmlFor={seed('street-address')} required>
          Street address
        </Label>
        <Input
          id={seed('street-address')}
          type="text"
          hasError
          required
          aria-describedby={seed('street-address-error')}
        />
        <HelpText variant="error" id={seed('street-address-error')}>
          Enter a street address.
        </HelpText>
      </FormControl>
      <FormControlTwoColumn>
        <FormControl>
          <Label htmlFor={seed('state')}>State</Label>
          <Select id={seed('state')}>
            {statesList.map(({value, name}) => (
              <Option value={value} key={value}>
                {name}
              </Option>
            ))}
          </Select>
        </FormControl>
        <FormControl>
          <Label htmlFor={seed('zip')} required>
            Zip code
          </Label>
          <Input id={seed('zip')} aria-describedby={seed('zip-error')} type="text" hasError required />
          <HelpText variant="error" id={seed('zip-error')}>
            Enter a zip code.
          </HelpText>
        </FormControl>
      </FormControlTwoColumn>
      <FormControl>
        <Label htmlFor={seed('email')} required>
          Email address
        </Label>
        <Input
          id={seed('email')}
          aria-describedby={seed('email-error')}
          type="email"
          hasError
          required
          value="email@xyz.yxz"
        />
        <HelpText variant="error" id={seed('email-error')}>
          Enter an email address.
        </HelpText>
      </FormControl>
      <FormActions>
        <Button variant="primary">Save</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Fixed width vs. full width

Forms can be set to any width needed for the desired form composition. When no max width is set, the form will be set to 100% of the parent container.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('address-heading')}>
      <Heading
        as="h3"
        variant="heading30"
        id={seed('address-heading')}
        marginBottom='space0'
      >
        Create new address
      </Heading>
      <FormControl>
        <Label htmlFor={seed('address-type')}>Address type</Label>
        <Select id={seed('address-type')} name="address-type">
          <Option value="1">Option 1</Option>
          <Option value="2">Option 2</Option>
        </Select>
      </FormControl>
      <FormControl>
        <Label htmlFor={seed('friendly-name')}>Friendly name</Label>
        <Input
          type="text"
          id={seed('friendly-name')}
          name="friendly-name"
          placeholder="Add friendly name"
        />
      </FormControl>
      <FormControl>
        <RadioGroup
          legend="Address implementation"
          name="address-implementation"
        >
          <Radio
            value="conversations"
            helpText="Supports both inbound and outbound SMS and attachments."
          >
            Conversations
          </Radio>
          <Radio
            value="legacy"
            helpText="Supports inbound SMS."
          >
            Legacy
          </Radio>
        </RadioGroup>
      </FormControl>
      <FormActions>
        <Button variant="primary">Submit</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

For fixed-width needs, you can use field length to help hint at the length of content required.

const FormExample = () => {
  const seed = useUIDSeed();
  return (
    <Form aria-labelledby={seed('address-heading')} maxWidth="size30">
      <Heading
        as="h3"
        variant="heading30"
        id={seed('address-heading')}
        marginBottom='space0'
      >
        Create new address
      </Heading>
      <FormControl>
        <Label htmlFor={seed('address-type')}>Address type</Label>
        <Select id={seed('address-type')} name="address-type">
          <Option value="1">Option 1</Option>
          <Option value="2">Option 2</Option>
        </Select>
      </FormControl>
      <FormControl>
        <Label htmlFor={seed('friendly-name')}>Friendly name</Label>
        <Input
          type="text"
          id={seed('friendly-name')}
          name="friendly-name"
          placeholder="Add friendly name"
        />
      </FormControl>
      <FormControl>
        <RadioGroup
          legend="Address implementation"
          name="address-implementation"
        >
          <Radio
            value="conversations"
            helpText="Supports both inbound and outbound SMS and attachments."
          >
            Conversations
          </Radio>
          <Radio
            value="legacy"
            helpText="Supports inbound SMS."
          >
            Legacy
          </Radio>
        </RadioGroup>
      </FormControl>
      <FormActions>
        <Button variant="primary">Submit</Button>
        <Button variant="secondary">Cancel</Button>
      </FormActions>
    </Form>
  );
}

render(
  <FormExample />
)

Composition notes

Form layout

The Form component ensures there is adequate spacing between form elements so users know which label belongs to which input. Typically, 50-75% of the height of a form element helps create this adequate spacing, so we’ve chosen to use $space-80 between all form elements.

Single column vs. multiple columns

For most forms, use a single-column layout. Multiple columns disrupt a user's vertical momentum, and can cause users to interpret the fields inconsistently. For a form with a horizontal layout, the user would need to scan in Z-patterns, which can inhibit comprehension and completion of the form. But if a form is in a single column, the path to completion is clearer, as it’s a straight line down the page.

Group related information in logical sections to aid in scanning and completion of a form. The flow from one set of questions to the next will better resemble a conversation. Grouping related fields together also helps users make sense of the information that they must fill in.

Composing a form

Amount of form elements

The process of completing forms should be as simple and easy as possible. Take the time to evaluate every question you add to your forms and strive for succinctness. Be vigilant about removing everything that isn’t necessary.

Before adding more form elements, ask yourself:

Do you really need to ask this question?
Is it information that you can get automatically?
Is there a better time or place to get an answer from our users?

Form order

Kathryn Whitenton, Website Form Usability: Top 10 Recommendations (Nielsen Norman Group)
Katie Sherwin, Placeholders in Form Fields are Harmful (Nielsen Norman Group, 2014)
Andrew Coyle, Design Better Forms (UX Collective, 2016)
Adam Silver, Form Design: From zero to hero all in one blog post (2019)
Luke Wroblewski, Web Form Design: Filling in the blanks (2008)

Form

Guidelines

About Form

Accessibility

Order

Content

Composition

Keyboard interaction

Examples

Sample form

Accessibility insight

Single column

2 column

Horizontal layouts

Sections

Form actions

Validation

Errors

Fixed width vs. full width

Composition notes

Form layout

Single column vs. multiple columns

Group related information

Composing a form

Amount of form elements

Form order

Order the form layout logically

Organization: when to break into sections or new pages

Field length

Optional vs. mandatory

When to use Forms

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Do

Don't

Related Paste patterns and page templates

References