Form

Forms are used to submit information, such as initiate a process, sign into an account, request information, or buy a product. They can be on a page, modal, or a drawer. Features include text inputs, text areas, dropdowns, radio buttons, checkboxes, buttons, and message bars.

Status

Vanilla
PublishedElement can be used in production
Angular
Angular
In progressElement design and development in progress
React
React
In backlogElement is in backlog
Documentation
PublishedElement can be used in production

Contents

What's new

Form is a new pattern. In v1, form elements were found under components like Inputs and Select. It is now considered a pattern that has an established, recognizable behavior. It is not a standalone component, but instead is enabled through common component combinations.

Live demo

This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.

You are now entering a live demo of the component.

<form data-dds="form" class="dds__form dds__container">
  <fieldset class="dds__form__section">
    <legend>Personal information</legend>
    <div class="dds__row">
      <div class="dds__col--1 dds__col--sm-3">
        <div class="dds__input-text__container">
          <label id="text-input-label-712795795" for="text-input-control-name-712795795">First name</label>
          <div class="dds__input-text__wrapper">
            <input
              type="text"
              class="dds__input-text"
              name="text-input-control-name-712795795"
              id="text-input-control-712795795"
              required=""
              aria-labelledby="text-input-label-712795795 text-input-helper-712795795"
            />

            <small id="text-input-helper-712795795" class="dds__input-text__helper"></small>
            <div id="text-input-error-712795795" class="dds__invalid-feedback">Enter a first name to continue</div>
          </div>
        </div>

        <div class="dds__input-text__container">
          <label id="text-input-label-864394824" for="text-input-control-name-864394824">Last name</label>
          <div class="dds__input-text__wrapper">
            <input
              type="text"
              class="dds__input-text"
              name="text-input-control-name-864394824"
              id="text-input-control-864394824"
              required=""
              aria-labelledby="text-input-label-864394824 text-input-helper-864394824"
            />

            <small id="text-input-helper-864394824" class="dds__input-text__helper"></small>
            <div id="text-input-error-864394824" class="dds__invalid-feedback">Enter a last name to continue</div>
          </div>
        </div>
      </div>
    </div>
  </fieldset>
  <button class="dds__button" type="submit">Submit</button>
</form>

Vanilla

View the form demo and code in Vanilla.
Visit Storybook

Layout

Forms are generally laid out in a single column with top-to-bottom content. Components included in the form, like text inputs and radio buttons, are large by default. Keep component sizes consistent throughout the pattern.

Vertical spacing

Form components can use as much vertical space as necessary, although overly long forms can cause frustration for the user and affect completion. Vertical spacing is expressed between form components through row padding and section padding. Row padding is the natural space between components, similar to a line wrap. Section padding is a larger space applied between sections of grouped components, such as address text inputs in a shipping section. Section padding is 150% of the row padding.

Horizontal spacing

Horizontal spacing is relative to breakpoint ranges (see the grid foundations page for more information). Note that XS-sized forms should stack components in a single column. Form components may only be positioned in the same row in S-sized forms or larger. Align form layouts to column width, with gutter spacing used between form components.

Density

DensitySection paddingRow padding
Compact24 pixels16 pixels
Default36 pixels24 pixels
Comfy48 pixels32 pixels

Display

Because form length affects cognitive load, the recommended display style changes as the fields increase.

DisplayUse case
Single-page formBest for shorter forms with few input fields.
Multi-page formIf a longer form cannot be avoided, display it as a multi-page form with section titles and step indicators on each page.

Button placement

The submission button is the final section used to complete the form and send information. Primary buttons should be used for submission. If there are multiple buttons, such as an option to save for later or navigate back, the non-submission buttons should be secondary. In a horizontal layout, the primary button should be on the left. In a stacked layout, the primary button should be on top. See button component guidance for more information.

A medium-sized button with small text inputs.

Visual indicator

All fields must be marked as required or optional at the field-level. It is not enough to display text such as “All fields are required” in the form’s introduction text without a field-level indicator. This is because users may forget the instructions by the time they reach the field input, get interrupted while filling the form, or not read the instructions at all. One exception to this rule is when the information being requested is critical and sufficiently common, such as with single-field forms and sign in patterns. It can be assumed in these instances that all fields are required.

Required fields

The recommended method for required fields is to include a red asterisk (Red 700) next to the field label. This should be paired with an explanation in the form’s introduction text that all fields marked with an asterisk are required. Alternatively, required fields can display “(required)” next to the field label instead of asterisks. Note that this alternate method increases text length, thereby making it harder for users to skim the form.

Optional fields

Fields that are not required should display “(optional)” next to their field label. Forms should be limited to fields that are necessary for the action being triggered, as lengthy forms can create a heavy cognitive load and reduce submission rates. Consider if an optional field needs to be added to a form.

Form validation

To prevent loss of information, forms must validate their success or failure after users press the submission button. Error text in the event of a failure should be specific, highly visible, and offer the user a path to resolution. Upon successful submission of a form, give users immediate feedback in the form of a “Success” message bar, modal, or “Thank you” page in the case of an e-commerce confirmation.

Error notification

If a form submission is not successful, users should be immediately alerted to the problem or error in the form of a message bar or modal. While long forms are to be avoided whenever possible, message bars on long forms should include an anchor link to the error field to aid in quick comprehension. Common user errors include empty fields, invalid inputs, and inputs that exceed the character count.

Inline error

If the error is caused by the user’s actions, there must also be an inline message consisting of a field-level error text and an icon. To aid screen reader and assisted device users, the error text must be adjacent to the error and clearly describe how to fix it. The error text, icon, and input must change color (Red 700). However, to be accessible for all users, color cannot be the sole indicator of an error.

Error text in an inline message. Note that inline error messages or helper text will cause the content below it to shift down.

Usage

Forms are useful for a variety of data collection scenarios. Form design should take into consideration the amount and kind of information needed, as well as the best process for collection. Limit form length, as each additional field (even optional fields) adds to cognitive load and reduces the likelihood of successful submission. In cases where a longer form is unavoidable, use progressive disclosure by grouping similar fields into separate sections and pages. Communicate to users where they are in the workflow with a progress tracker and reassure them their information will not be lost if they do not finish the form in one sitting.

E-commerce

E-commerce experiences present consumers with products and encourage them to make a purchase. Forms are used to collect information necessary to complete a purchase, such as providing a street address and phone number for shipping, or a credit card number for billing purposes. Every additional step a user is required to fill out adds friction to the experience, so consider what information is strictly necessary and what can be collected at another time.

Application of settings

Settings allow users to configure the appearance or actions in an application to better suit their needs. Forms are used to gather and apply information related to accounts, users, and notification preferences.

Support

Forms can be used for streamlining support communication, such as collecting requirements for a ticket or gathering feedback, and change requests.

Productivity applications

Productivity applications help users complete complex tasks they would have otherwise done manually. For instance, a user building an order status report in a dashboard or analytics product could use a form to define the scope and parameters of the customer orders in the report. Forms may also be used to save time in workflows, like hiring, by grouping similar information into sections or separate pages. This might include applicant name and email address under “Personal information” and a list of previous jobs under “Work history”. By communicating the number of steps or pages in the workflow and the ability to stop and save progress, users can complete longer forms even in the case of interruption or a heavy cognitive load.

Accessibility

An error should not be indicated by color alone
Identify an error with appropriate text and optionally an icon. This helps users who cannot see color, or who are using assistive technology.
WCAG 2.1: 1.4.1 Use of Color

Direct focus with the error message bar
When a form submission is unsuccessful, field-level indicators are not enough for some users to perceive that an error has occurred. Screen reader users, for example, will need a text explanation of which fields were missing or incorrect.
WCAG 2.1: 3.3.1 Error Identification, 3.3.3 Error Suggestion

Mark fields that require input
All fields should be marked as required or optional. Many screen reader users are blind and rely on critical information to be read out. Marking fields with HTML5 <input required> ensures that these users will always hear them announced as required.
WCAG 2.1: 3.3.2 Labels or Instructions

Content guidelines

Fields
Limit the number of fields to only what is necessary. Well-designed forms are not overwhelming in presentation.

Grouping
Group related form components under section titles to give users context. For example, street address and state can be grouped under “Shipping.”

Capitalization
Use sentence case for labels, default values, detected values, and autocompleted text, excepting product names and proper nouns.

Punctuation
Field label text does not require punctuation, however helper text typically does. Avoid using colons at the end of label text.

Clear label text
Field label text should clearly state the required input in one to three words. Label text is different from helper text, so avoid using them for the same purposes.