Form

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.

Form component samples
Form component blueprint

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).

Coming soon
A documentation page for the Popover component is coming soon.

Form component visual elements

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.
Form component variants

Light theme

Form component, light theme

Dark theme

Coming soon
More details and specs surrounding dark theme are coming soon.

Form component, dark theme

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.

Form components (Container and Floating), default orientaton

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.

Form component (Container), horizontal orientaton
Form component (Floating), horizontal orientaton

Text label alignment

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

Form component text label alignment

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.

Form (Container), default orientaton
Form (Container), horizontal orientaton

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 (Floating), default orientaton
Form (Floating), horizontal orientaton

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.
Form component content

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.

Form component required fields

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.

Form component data inputs

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.
Form component arranging data inputs

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.

Coming soon
A documentation page for the Popover component is coming soon.

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.

Form component popover

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).

Form component placement, default orientaton
Form component placement, horizontal orientaton

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.

Form component disabled state

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.

Form component, error validation on loss of focus

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.

Form component, error validation on submission

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

Link

Form component interaction state, link

Hover

Form fields and select lists share the same hover state.

Form component interaction state, hover

Focus

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

Form component interaction state, focus

Active

Form fields and select lists share the same active state.

Form component interaction state, active

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.

Form component tab order
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.

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

Form component (Default) responsive design, desktop
Form component (Horizontal) responsive design, desktop

Tablet

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

Form component responsive design, tablet

Mobile

Form component responsive design, mobile

Form elements aligned to the right

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

Form component, best practice 1

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.

Form component, best practice 2

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.

Form component, best practice 3

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.

Form component, best practice 4

Rearranging data inputs and button groups

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

Form component, best practice 5

A Form uses PatternFly 4 spacers to define spacing values between elements.

Default

Form component spacing, default

Horizontal

Form component spacing, horizontal

To give feedback about anything on this page or to request a new Component, contact us.

To learn more about how to use foundational elements, visit the Foundations section.