Skip to content

Introduction

Form components are used to collect information and guide users. Here you’ll find general rules for using them that apply to all components. Structure, sequence, and messaging are essential to creating a good user experience.

Form Components

Placement and Order

When placing form components on a page, there are two basic rules:

  1. Always left-align components.
  2. Stack components vertically rather than placing them side by side.
✅ Always left-Align components and stack vertically
❌ Avoid putting components next to each other and avoid centering them

Required & Optional Input

It’s best practice to only mark the optional components. No special indicator exists for required ones, thus all components are assumed to be required, unless they are explicitly marked as “Optional”.

✅ Mark Optional Components

Labels and Grouping

Grouping related components together helps users quickly understand the structure and flow of the form. Well-defined groupings reduce cognitive load, making the form easier to process and interact with.

✅ Group similar inputs to ease the user

Your Details

Your address

Additionally, always pair components with clear and descriptive labels to ensure users understand what is expected of them.

Form Submission

All data entered through form components should be submitted via a button. If the user navigates away from the page before submitting, the input is lost. This rule does not apply to the toggle component, which takes effect immediately.

✅ Include a button with a clear call to action to submit data

Input-level Validation

Input-level validation happens while the user interacts with the individual components. All form components support this for incorrect data. Validation is performed when the user moves focus away from the component they’re interacting with. The user must enter valid input to clear the error state.

<Form>
<TextInput
label="Email"
attributes={{ defaultValue: "john@gmailcom" }}
feedback={{
message: "Please enter a valid email address",
type: "error",
}}
/>
</Form>;
Open in StoryBook

Page-level Validation

Page-level validation happens once the user submits the entered input though a button. If there’s an error with the entered data, the error summary component appears on top of the page, providing an overview of errors that have occurred.

<Form>
<ErrorSummary
errors={[
{
id: "error-summary",
fieldName: "Email",
message: "Please enter a valid email address",
},
]}
/>
</Form>;
Open in StoryBook

Disabled States

Some components support disabled states, but they should be used sparingly. Always provide a clear explanation of why the component is disabled and how it can be enabled. A common acceptable use case for disabled components is when a component is in a read-only state.

You need to confirm your email before you can change it
<Form>
<TextInput
label="Email"
attributes={{ defaultValue: "john@gmailcom" }}
feedback={{
message: "Please enter a valid email address",
type: "error",
}}
/>
</Form>;
Open in StoryBook

Accessibility Considerations

We have made a number of considerations to ensure accessible forms (perceivable, operable, understandable, and robust). These considerations are documented throughout form usage guidelines, please follow them carefully. This section highlights a few key areas of note.

  • We recommend against using disabled states, as they offer low contrast making them difficult to percieve, and it may not be understandable why a form field or button is disabled.
  • Form validation states are conveyed with both colour, iconography. and text. This improves perceivability for people with colour blindness, for example, who may find it difficult to distinguish colour.
  • On submit an error summary component provides keyboard users a means to quickly navigate to the form field with an error, improving operability.
  • Form inputs and their labels are connected and clickable, providing a large touch target area for people with limited dexterity, or other reasons, that make it difficult to click a small target area.