Form

Overview

A Form is a group of elements used to collect information from a user. It can include a combination of text, fields, select lists, data inputs, buttons, and more.

Sample pattern

Style

Visual elements

There are a variety of form elements available for use depending on what information needs to be collected from or displayed to a user.

• Title and body text - Title and body text styles explaining why a user should fill out a form.
• Text label - Small text describing what a user needs to input into a form element.
• Popover - Small card with helpful content that appears near a popover icon when triggered.
• Form field or Select list - Text box or dropdown allowing a user to input text or make a selection.
• Data inputs - Alternate components allowing a user to input other kinds of information.
• Buttons - Actions used to submit or clear a form.
• Privacy link - Text linking to privacy documentation (included when a form is used on marketing websites).

Learn more

Visit the Popover component page to learn more about how to use a popover.

Variants

There are two form variants available for use.

• Container - Form elements are contained in a card and the title and body text sizes are slightly smaller.
• Floating - Form elements float in a group and the title and body text sizes are slightly larger.

Theme

Light theme

Dark theme

Coming soon

More details and specs surrounding dark theme are coming soon.

Orientation

Default

In the Default orientation, form elements are organized vertically and the text labels are positioned on top. All form elements and groups are aligned to the left edge and some elements span the width of the form, like a field.

Warning

Do not write text labels with more than a few words as they might break to two lines or make the form hard to scan.

Horizontal

In the Horizontal orientation, form elements are still organized vertically, but the text labels are positioned to the left. Form elements without a text label, like the button group or privacy link, should be aligned to the left edge of other form elements with text labels.

Helpful tip

Form variants in the Horizontal orientaton span more grid columns, so only use them if there is ample space or enough padding near content.

Warning

Do not write text labels with more than a few words as they might break to two lines or make the form hard to scan.

Text label alignment

In the Horizontal orientation, text labels should be left justified making it easy for a user to scan.

Usage

A form is best used to guide a user through a task while gathering information from them.

Container variant

When the Container variant is positioned on the grid, it may span between four and eight columns, and be oriented on the left, center, or right side of the page.

Helpful tip

When the Container variant is positioned near content, there should be at least one grid column of padding in between.

Floating variant

When the Floating variant is positioned on the grid, it may span between four and eight columns, and be oriented on the left, center, or right side of the page.

Helpful tip

When the Floating variant is positioned near content, there should be at least one grid column of padding in between.

Form content

A user will have a better experience with submitting a form if the elements are easy for them to identify and move between.

• Text label - Use to identify form elements that are required or recommended.
• Popover - Use to display helpful information near form elements that may need more explanation beyond text labels.
• Form field or Select list - Use to write text or make a selection from a list.
• Placeholder text - Use within a form field or select list as an example of how to correctly provide an input.
• Helper text - Use underneath a form element as an example of how to correctly provide an input.

Required fields

If a user is required to input information when submitting a form, indicate exactly where by adding a required asterisk (*) to the right of a text label. If all inputs are required, do not add an asterisk next to every text label. Instead, add text below the title stating All fields are required. If all inputs are optional, the text should state All fields are optional instead.

Data inputs

Data inputs provide additional ways for a user to submit information. Each data input has a specific use case and different data input groups can be used in the same form.

Using data inputs

A variety of data inputs can be used in the same form to allow a user to submit more information.

Data input name	Usage
Radio button	Use when only one option can be chosen from a list of no more than five options.
Checkbox	Use when either several or no options can be chosen from a list of no more than five options.
Select list	Use to select one or more options from a list of more than five options.
Switch	Use to toggle between two different states.

Arranging data inputs

Radio buttons and checkboxes can be stacked horizontally or vertically depending on the amount of characters and space.

• If there are fewer than three options, arrange data inputs horizontally.
• If there are more than three options, arrange data inputs vertically.

Popover

If a form element requires more explanation beyond text labels, use a popover to help a user better understand what they need to input. The content in a popover can include text or links to help documents or other websites. When adding a popover to a form, a small icon should be added next to a text label which acts as a trigger to display the popover.

Learn more

Visit the Popover component page to learn more about how to use a popover.

Warning

Avoid using a popover for critical information, a user will have a hard time finding what they need if they have to trigger something first.

Placement

A form can span various grid columns when used on a page. To preserve readability, it should span at least four grid columns but not exceed eight grid columns (or 750px).

Behavior

Disabled state

In some cases, a form element can be disabled if a user needs to make an input somewhere else first. In this example, a user is required to select their department first and then optionally select their job role afterwards. A user can still submit a form successfully if they skip an optional form element.

Warning

Do not disable form elements that require input as a user might skip over them leading to errors when the form is submitted.

Error states

When a user submits a form that results in errors, it is important to explain what the errors are and how to resolve them. There are two error states that can be displayed depending on how a user moves through the form.

Error validation on loss of focus

An error will be displayed after a user moves the focus away from a required form element. This can also happen when a user inputs something with an invalid format or leaves a required form element blank or incomplete. The error text and icons will disappear when the errors are resolved and the focus is moved away once again.

Error validation on submission

Errors will be displayed if a user tries to submit a completed form with invalid information or not filled out completely. When this happens, a Danger severity alert is displayed stating there are errors that need to be resolved. The alert is positioned below the title and body text, and has the same width as the widest form element. The alert will disappear when the errors are resolved and the form is submitted again.

Interaction states

See more

Visit the Button and Link component pages to see available interaction states.

Link

Hover

Form fields and select lists share the same hover state.

Focus

When the focus is moved to a form field with placeholder text, the text will disappear and a blinking cursor will be visible.

Active

Form fields and select lists share the same active state.

Tab order

When the Tab key is pressed repeatedly, the focus highlights each form element in order, from top to bottom or left to right.

Accessibility

Key	Action
Tab	Moves the focus to the next form element.
Shift + Tab	Moves the focus to the previous form element.
Space	Opens/closes a popover, opens/closes a select list, or selects/toggles a data input.
Enter	Opens/closes a popover or submits/clears the form.

Responsive design

The Default variant mostly remains the same on large and small screens, but the Horizontal variant will switch to the Default variant as screens get smaller.

Desktop

Tablet

As screens get smaller, the Horizontal variant will switch to the Default variant to reduce crowding.

Mobile

Best practices

Form elements aligned to the right

Do not align the button group and privacy link to the right edge of other form elements.

Two Primary buttons

Do not include two Primary buttons, use a combination of Primary and Link buttons instead in that order.

Learn more

Visit the Button component page to learn more about how to use buttons.

Too many required fields

If all inputs are required, do not add an asterisk next to every text label. Instead, add text below the title stating All fields are required. If all inputs are optional, the text should state All fields are optional instead.

12 columns

The Container and Floating variants in both orientations should only span a maxium of 8 grid columns.

Learn more

Visit the Grid foundation page to learn more about how to use the grid.

Rearranging data inputs and button groups

Do not change the stacking order of data inputs and button groups, except in rare cases.

Spacing

A form banner uses space tokens to define spacing values between elements.

Default

Horizontal