Skip to content
Change the site theme
Figma
(information)

Form

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


Guidelines

Guidelines page anchor

About Form

About Form page anchor

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(link takes you to an external page)). 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.

Order

Order page anchor
  • Order forms logically, in sequential order, 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.
  • Provide accessible and clear labels, placeholder text, and help text.
    • Labels should clearly describe the value being requested.
    • Don't use placeholder text as a replacement for labels. It can be used to provide an example to users, but will disappear from the field when a user enters text. It's also not broadly supported by assistive technologies and won't display in older browsers.
    • Labels should not run onto two lines.
  • 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.
  • Provide clear and timely feedback for form inputs using validation, inline Help Text messaging, or Toasts.
  • Don’t make the user repeat information, e.g. 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.

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.

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.

It is recommended to use a single-column layout in Forms because it is easier to read. To learn more, check out some research on form readability(link takes you to an external page). 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.

Layouts with more than 1 column should only be used when it would be clearer and prevent 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.

Forms support horizontal alignment of components, however, this layout should follow these guidelines:

  • Options are placed next to each other, in logical order.
  • If the label is longer than 3 words/20 characters, consider using a vertically-stacked layout.
  • If the form element’s content is too long, use a single-column, vertical layout.

Use sections to group related content or steps within a form for users to input. A section is separated using a Separator, with $space-90 above and below it. Sections can also include a section heading and description, if applicable. If a form element doesn’t belong to any of the sections, make sure there’s enough spacing between to signal that the form element is separate doesn’t belong to the section, with at least $space-130.

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 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. An error message can give more information than a disabled button can to help users figure out which fields are invalid.

Use inline error messaging to inform users when they cannot continue completing a form, then provide guidance on next steps and ways to remedy the situation.

To provide further clarity, doubling on the use of Callouts and inline error messages helps users quickly notice, find, and remedy errors. If there are multiple errors, summarize them in a logical order (e.g. for forms that are missing several required fields from the user). Callouts should be placed below the Form title or section title, if applicable, and above the form elements.

If your 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.

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.

Fixed width vs. full width

Fixed width vs. full width page anchor

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.

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

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

Single column vs. multiple columns page anchor

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 page anchor

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.

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?
Order the form layout logically
Order the form layout logically page anchor

When ordering your form, use logical sequencing. Questions should be asked logically from a user’s perspective, not the application or database’s logic. For example, it’s unusual to ask for someone’s address before their name.

Organization: when to break into sections or new pages
Organization: when to break into sections or new pages page anchor

Once you’ve determined how many form fields to include in a form, you’ll need to decide how to best break the form into sections. If a form naturally breaks down into a few short topics, a single page is likely to be a good way to organize the form. When a form becomes long and has a large number of questions that are only related by a few topics, multiple pages may be a better way to organize the form.

Where possible, ensure that field lengths provide meaningful affordances that help people answer questions effectively. Otherwise, use a consistent length that provides enough room for correct answers.

Make required and optional fields distinguishable. Try to avoid optional input fields in forms.

  • If most of the inputs on a form are required, indicate the few that are optional.
  • If most of the inputs on a form are optional, indicate the few that are required.
  • When indicating what form fields are either required or optional, text is the most clear. However, the required symbol is relatively well understood to mean required. If you do use the required symbol to indicate required fields, include a legend or form key that explains what it indicates.

Use a Form when users are expected to enter more than a single form component to collect user input.

Do

Use single column layouts as much as possible.

Don't

Don’t rely on 2-column or multi-column form layouts, as they disrupt a user's vertical momentum, and can cause users to interpret the fields inconsistently.

Do

Only include the necessary number of form fields. Strive for succinctness in each question asked.

Don't

Don’t add gratuitous optional form fields.

Do

Group related form elements. Consider breaking forms into sections when it makes sense for the content.

Don't

Don’t separate related form elements. Don’t create long forms that are unorganized.

Do

Write legend text to describe a group and their intended relationship together.

Don't

Don't leave sections without a legend. Don't use the legend and label text in a way that is intended to be read as a sentence.

Do

Use fieldsets when breaking a form into sections.

Don't

Don’t use typography components such as Heading when breaking forms into sections.

Do

Enable the form submission action, even when the form is empty or has an error.

Don't

Don't disable the submit button.

Do

Include a visible label on every form element.

Don't

Don't use placeholder or prefix/suffix text as a replacement for a label.

Do

Only use a single form per page.

Don't

Don’t use multiple forms per page.

Do

Implement the best field length needed for the design.

Don't

Don’t implement a full-width form for every design, especially within a page. Long line lengths, with characters greater than 80 characters per line, are difficult to read.

yarn add @twilio-paste/form - or - yarn add @twilio-paste/core
import {
Form,
FormSection,
FormSectionHeading,
FormControl
} from '@twilio-paste/core/form;
import {Input} from '@twilio-paste/core/input;
import {Label} from '@twilio-paste/core/label;
const SampleForm = () => (
<Form maxWidth="size30">
<FormSection>
<FormSectionHeading variant="heading30">
Personal information
</FormSectionHeading>
<FormControl>
<Label htmlFor="first-name">First name</Label>
<Input id="first-name" />
</FormControl>
<FormControl>
<Label htmlFor="last-name">Last name</Label>
<Input id="last-name" />
</FormControl>
</FormSection>
</CheckboxGroup>
);

Accepts all valid attributes for HTML form elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form
maxWidth?ResponsiveValue<MaxWidthOptions>The maximum width of the Form.
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM'

Accepts all valid attributes for HTML div elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Control
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_CONTROL'

Accepts all valid attributes for HTML div elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Actions
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_ACTIONS'

FormControlTwoColumn props

FormControlTwoColumn props page anchor

Accepts all valid attributes for HTML div elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Control Two Column
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_CONTROL_TWO_COLUMN'

Accepts all valid attributes for HTML fieldset elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Section
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_SECTION'

FormSectionDescription props

FormSectionDescription props page anchor

Accepts all valid attributes for HTML div elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Section Heading
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_SECTION_DESCRIPTION'

FormSectionHeading props

FormSectionHeading props page anchor

Accepts all valid attributes for HTML heading elements.

PropTypeDescriptionDefault
childrenReact.ReactNodeThe contents of the Form Section Description
variant?'heading10', 'heading20', 'heading30', 'heading40', 'heading50', 'heading60'The heading variant to render'heading40'
element?stringOverrides the default element name to apply unique styles with the Customization Provider.'FORM_SECTION_HEADING'

Form is available in the Paste Components Figma library. It has 3 base components: Form element group, Form section, and Form section header, with a ⚙️emoji in its layer name to indicate there are nested configurable properties available.

In code, it’s easy to add more than one form element to a form when you need it. To accomplish this in Figma, you can show and hide the number of form elements you need in the form component itself.

To customize the layout of a single form element in Figma, expand the Form until you reach a “⚙️Form element group” layer within a “⚙️Form section.” From there, you can select the type of form element component you need (e.g. an “Input” or a “Select”) and change the number of columns displayed within a form element group (up to 2 columns). If you need a custom form element, you can create your own local component and use Figma’s component swapping feature to utilize your custom component.

The Form component allows you to show or hide Form actions.

To customize the number of sections, expand the Form until you reach the “Form content↓” layer. From there, you can show/hide the “⚙️ Form section” layers until you reach the desired number of sections for your form.

To customize a Form section’s header, expand the “Form content↓” layer until you reach a “⚙️ Form section header”, which includes a Heading and Paragraph to add more detail to your Form’s sections.

Here is a properties table for Form:

PropertyVariantsDescriptionDefault
Actions"Yes", "No"Allows for displaying up to two buttonsYes

Here is a properties table for Form’s nested component, Form section:

PropertyVariantsDescriptionDefault
Header"Yes", "No"Allows for displaying a section heading and description.Yes

Here is a properties table for Form’s nested component, Form element group:

PropertyVariantsDescriptionDefault
Columns1,2Allows for up a 2-column horizontal layout of the form element components.1

Further reading on Forms best practices.

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

Black lives matter.