Form

Form layout refers to the arrangement of input fields, labels, and other elements on a page where user input is required. The goal is to make it easy and intuitive for users to enter data into the form accurately and efficiently.

Interactive Playground

The Interactive Playground allows you to experiment with various avatar styles and features. Once you get the results you want, copy the HTML or React code provided and paste it into your application.

<form
class="neo-form"
aria-label="Playground form"
>
<div
data-testid="NeoInputWrapper-root"
class="neo-form-control"
>
<div
data-testid="NeoInputWrapper-group-root"
class="neo-input-group"
>
<label for=":R1:">
Name
</label>
<div class="neo-input-editable__wrapper">
<input
class="neo-input"
id=":R1:"
placeholder="Type your name here."
tabindex="0"
type="text"
>
<button
aria-label="clear input"
class="neo-input-edit__icon neo-icon-end"
type="button"
>
</button>
</div>
</div>
</div>
<div
data-testid="NeoInputWrapper-root"
class="neo-form-control"
>
<div
data-testid="NeoInputWrapper-group-root"
class="neo-input-group"
>
<label for=":R2:">
Email
</label>
<div class="neo-input-editable__wrapper">
<input
class="neo-input"
id=":R2:"
placeholder="Type your email here."
tabindex="0"
type="email"
>
<button
aria-label="clear input"
class="neo-input-edit__icon neo-icon-end"
type="button"
>
</button>
</div>
</div>
</div>
<button
class="neo-btn neo-btn--default neo-btn-primary neo-btn-primary--default"
data-badge
id="btn-submit"
>
Submit
</button>
<button
class="neo-btn neo-btn--default neo-btn-secondary neo-btn-secondary--default"
data-badge
id="btnCancel"
>
Cancel
</button>
</form>
<Form
aria-label="Playground form"
>
<TextInput
clearable
label="Name"
placeholder="Type your name here."
type="text"
/>
<TextInput
clearable
label="Email"
placeholder="Type your email here."
type="email"
/>
<Button
id="btn-submit"
variant="primary"
>
Submit
</Button>
<Button
id="btnCancel"
variant="secondary"
>
Cancel
</Button>
</Form>

Anatomy

This example shows a layout that includes labels, text input fields, buttons, and other elements of the form.

Image showing the different parts that make up a Form
  • Section Header:

    The title of this form. It tells the user what this section is about and the sort of information that may be required.
  • Required Field:

    A field label that ends with an asterisk * signifies that this field must be filled in by the user before they can proceed to the next screen.
  • Error Text Field:

    When the system detects a problem with the data entered, the border around the field will turn red.
  • Error Helper Text:

    When the system detects a problem with the data entered, an error message is placed beneath the field with the problem. The error text should indicate what the problem is and, where possible, how to fix it.
  • Optional Field:

    A field label that does not end with an asterisk is optional. The user can leave this field blank if they choose.
  • Checkbox:

    A checkbox can be used to allow the user to opt-in to a feature of the program (e.g. subscription, provide feedback, etc.). In this case, it is optional. Checkboxes can also be used to verify that a user has read the legal text, or otherwise understands what is about to happen(e.g. data collection).
  • Action Buttons:

    Once all of the required information has been entered into the form, the user can select Submit to pass the information to the system for processing. Cancel will clear the data from the form and return the user to the previous screen.

Behavior

Effective form layout reduces user confusion and errors, improving the user experience and performance.

Alignment

Alignment refers to the arrangement of input fields and labels on a form so that they are visually consistent and easy to read. Proper form alignment is important to create clear and intuitive visual designs that guide users through a process.

Align forms and input components to the left side of the page layout keeping all inputs the same width. Fields should be stacked vertically where possible, but related items (e.g. Start Date, End Date) can be stacked horizontally.

Image showing how different elements inside a form are vertically aligned.

Spacing and Arrangement

Vertical forms should maintain consistent padding between each element and the actionable buttons.

Image showing how elements inside a form are vertically spaced.

Forms with two or more fields placed horizontally have 16 px padding between each element.

Image showing how elements inside a form are horizontally spaced.

When two form fields are related, such as a zip code and country, they are stacked horizontally and the padding between each element is 8 px.

Image showing how two horizontally stacked fields have a padding of 8 pixels.
An image showing a form with fields vertically stacked.

DO: Stack form fields vertically. Use horizontal layouts only when items are closely associated with each other, or when there is limited space.

An image showing a form with fields horizontally stacked.

DON'T: Do not stack form fields horizontally. Use horizontal layouts only when items are closely associated with each other, or when space is limited.

Button Placement

Buttons in a form are sorted by importance from right to left, with the most important button (primary) on the right. The recommended placement for action buttons is the right edge of a form.

Pages with a stepper also include the actionable buttons positioned on the right.

Image showing buttons placed on the bottom right edge of the stepper component.

Breadcrumbs can also include actionable buttons. In this case, the primary button is positioned to the right.

Image showing buttons placed on the right side of the breadcrumbs component.

Exceptions to this are single-page forms, flags, and section messages where buttons are left aligned with the primary button on the left.

Image showing the primary button on the left inside a single page form.

Required vs Optional

A field that is Required forces users to enter a value before submitting the form. Optional fields can be left blank without blocking the submission of the form.

An image showing a form with field labels with asteriks.

DO: Mark all required fields with a red asterisk.

An image showing a form with required fields without an asterisk.

DON'T: Do not display required fields without the asterisk. Required fields need an asterisk, while optional fields do not.

Validation Feedback

Text input feedback is the response given to users when they enter data that is invalid. Providing clear feedback is important for accessibility, and for a better user experience.

An image showing an input field with a validation error just below it.

DO: Specify errors inline where possible.

An image showing an error displayed at the top of the form.

DON'T: Do not display errors only at the page-level if they can be included inline.

Password Input

Password requirements should always be visible and clear to the user.

An image showing password requirements being met just below input field.

DO: Indicate successfully completed requirements for new password input.

An image showing a vague error displayed below the input field.

DON'T: Do not use the helper text to indicate an error without providing enough information to fix the problem.

An image showing all password requirements just below input field.

DO: List all password requirements in detail.

An image showing password requirements in helper text below the input field.

DON'T: Do not use the helper text to show password requirements.

Responsive Layouts

Forms should be designed to with a single column. Horizontal stacking should only occur when space is limited, or when there are 2 or more fields that are related (e.g. city and zip code). When adding a form to a page, be sure to follow the Layout guidelines for responsive breakpoints, margins and gutters.

Image showing a form with fields arranged in a 2 column layout.

On narrower screens where there isn’t enough space, stack forms vertically.

Image showing a narrow form with fields arranged in a single column layout.

Read-only

Read-only text fields are often used to display information or data that is important for the user to see, but that cannot be edited or changed at this time. Some examples of read-only text include displaying user account information, order details, or confirmation messages.

An image showing 2 input fields in read-only mode.

DO: In read-only mode, display fields as read-only. A disabled field type should only be used when data cannot be entered on an active form.

An image showing input fields in disabled mode.

DON'T: Do not use disabled fields for read only views.

Components