Forms and validation

You can use forms and forms elements to get input from your users or to allow them to configure options.

Anatomy of a form element

1. Label
2. Input value (alternatively, placeholder or default value)
3. Hint

Labels

Labels allow you to clarify the input you expect from users. Be concise in how you label your form elements.

Placeholders

Placeholders allow you to give an example of the input you expect from users. It can be helpful to clarify what kind or format of input you're expecting (for example, YYYY-MM-DD). Be aware that users won't see the placeholder text as soon as they start to input data; thus, it shouldn't contain information necessary to users.

Hints

Hints allow you to provide additional in-context help and guidance to users to fill a form element correctly. Alternatively, you can use them to explain why you require specific user inputs. Keep hint texts concise and as short as possible. Contrary to placeholders, hints will always be visible and thus may contain information necessary to users (for example, special characters required for a password).

Default values

Any form element can have a default value, making forms less hassle for users. However, repeatedly providing the wrong or inappropriate default values may lead to users needing clarification. When in doubt, don't provide any default values and leave it up to the users to decide.

Required form elements

The corresponding label of a form element will show an asterisk to indicate that the user is required to use the input.

Building a form

Forms group multiple related form elements together. The following guidelines ensure that users can rely on a consistent experience when filling out forms across multiple pages or apps.

Spacing

Spacing communicates the relationship and hierarchy between individual form elements. Use the following guideline to ensure sufficient spacing between form elements:

• Vertical spacing between groups of form elements is 32px.
• Vertical spacing between form elements is 16px.
• Vertical spacing between checkboxes and radios is 8px.
• Vertical spacing between labels and form elements is 4px.

The maximum recommended width for single-column forms is 480px.

Make sure to use our spacing tokens when applying spacings.

Columns

We don't advise using a multi-column layout in forms as it might interrupt the vertical momentum of moving down the form. It's best to keep users in the flow of a single-column layout where each row represents a form element.

If you still decide to go for a multi-column layout in your forms, to optimize your layout, use the following spacing guidelines to ensure sufficient spacing between columns of form elements:

• Horizontal spacing between form elements is 8px.

Sizing form elements

The width of form elements should always reflect the expected length of the input. To ensure visual clarity in a single-column layout, or if the expected input is unknown, form elements may also fill the width of their parent.

Buttons in forms

You can use buttons in forms to submit, discard a form, or move forward in a multi-step form process.

Alignment

Buttons in forms are left-aligned. Right-align buttons in forms if:

• They're part of a wizard-like or multi-step form.
• They're inside of a modal or overlay.

Spacing

Vertical spacing between form elements and buttons is 32px. Make sure to use our spacing tokens when applying spacings.

Emphasis

Use an accent emphasis button for the main action. For any other action, use minimal emphasis buttons. See the button component documentation for more information about the different emphasis variants.

The order of the buttons depends on their alignment:

• If the buttons are left-aligned, the main action is placed first.
• If the buttons are right-aligned, the main action is placed last.

Validation and errors

From time to time, users make mistakes when filling out forms. Validating input and showing errors to help users correct mistakes is essential to good form design.

Showing errors in form elements

Form elements have an error state and can show an error message that explains what's causing validation to fail. When writing for error messages, remember that they're crucial for users to understand and resolve errors. If written thoughtfully, they can reduce frustration and stress.

In forms, errors caused by validation need to be resolved before users can successfully submit the form and continue.

Types of validation

You should always valiadate groups of form elements on submission. This way, users can fill in forms without interruption and focus on providing the required information. In specific scenarios, however, it can be advantageous for individual form elements to be validated as soon as their input changes. For example, to provide immediate feedback to users.

Immediate

Immediate form validation should only happen when users finish providing input, and focus is removed from the form element. You can make an exception if the input of a form element is already in an invalid state, and giving feedback to the users while they're typing lets them know whether they've resolved the issue.

On submit

We recommend validating the user's input client-side. However, if the data is validated server-side and the response takes time, disable the form's elements and put the submit button into a loading state to prevent multiple submissions while users wait for a response.

The first invalid form element should be focused and scrolled into the viewport if a form validation fails. Otherwise, in long forms, users might not notice an error. After users have submitted a form and its validation fails the first time, ensure to provide immediate validation for form elements.

Never block users from submitting a form by disabling the submit button. Sometimes, users unknowingly miss providing information for one or more required form elements, and a disabled submit button, without knowing what's causing the behavior, can lead to a frustrating experience. Instead, let users submit the form, then show that input is incomplete or missing.