Skip to content
Gusto’s condensed “G” logoWorkbench

Form pattern

Forms are at the core of Gusto’s products. Use these guidelines to create forms that are predictable, easy to use and cohesive across the platform.

Anatomy of a form in Gusto’s platform
Anatomy of a form

  • Spacing in forms follow a consistent pattern of 12px between unique elements and 8px between grouped elements (like radios and checkboxes).

  • There are subtle differences between elements with a description (0px between title and description, 4px between the description and form element) elements with just a label (4px between the label and form element)


Example of spacing between form elements
Horizontal and vertical spacing between elements within a form

The default styles for Input, Textarea, Select, Autocomplete components are: salt-300 as the background color, salt-1000 text, and a 2px salt-700 bottom border.

Please use your full name. You may use initials for your middle name(s)

 (optional)

Please enter the state in which you currently reside. If you have lived in this state less than one year, please select the last state which you lived

Add details and requirments for the job

Default text field, select, and textarea examples

The focus state styles for Input, Textarea, Select, Autocomplete components are: kale-100 as the background color, salt-1000 text, and a 2px kale-500 bottom border.

Example a focused text fieldExample a focused textareaExample a focused select
Focus state on a text field, textarea, and select

The error state styles for Input and Textarea components are: error-100 as the background color, salt-1000 text, and a 2px error-500 bottom border. Error message text should always appear below the field and be set to error-500

Please use your full name. You may use initials for your middle name(s)

Add details and requirments for the job

Error state on a text field, and textarea

Success message text should always appear below the field and be set to kale-500. This state should only be used for async form behavior (e.g. requiring validation from a third party service before the form is submitted)

Learn more about disabled states on our Accessibility page.

Since most form fields in Gusto’s platform are required, only optional fields should be denoted. This pattern reduces the amount of information presented to users, making forms easier to complete.

 (optional)

Please enter the state in which you currently reside. If you have lived in this state less than one year, please select the last state which you lived

Example of an optional text field

A checkbox can also have an indeterminate state when its value cannot be expressed with a binary true or false value. This state is most often used on groups of checkboxes that contain "children" elements, which can have different values.

Example of an Indeterminate checkbox

Forms are easiest when building with Formik. To use our components with Formik wrappers, make sure to import from @gusto/workbench-formik. These components work exactly the same as their @gusto/workbench counterparts, but with the added benefit of having state management handled by Formik.

Learn more about implementing forms »

  • A label is required for every form element. While visible labels are always recommended, in use cases where it needs to be hidden, e.g., Search inputs, use aria-label or the visuallyHidden CSS utility.
  • Place label above the field
  • Use optional to mark fields optional
  • Add description text under the label and above the field
  • Show error/success messages below the related form field
  • Limit the use of placeholder text and never use it as a replacement for labels. If placeholder text is used, make sure non-vital information is used due to its many accessibility concerns such as low contrast and inconsistent readout on screen readers.
  • Make sure tab order follows visual structure of the form
  • Don’t place form elements side-by-side except for cases where the format is required, like date inputs
  • Don’t call out required fields since optional fields are already marked
  • Don’t use placeholder text in place of a label
  • Don’t create custom error formatting placements

Use validation text to confirm that the input meets key criteria for that specific field—the input may have been checked against a database (like tying a routing number to a bank) or validated for certain characteristics (like making sure that a password has a certain number of characters). Here are some do’s and don’ts:

  • Use validation text as feedback on a single field; if you need to provide feedback on more than one field, use a different component
  • Use validation text to confirm the user’s entry for field types including:
  • Credit card numbers
  • Bank account numbers
  • Don’t use for dropdown or autocomplete fields
  • Don’t use validation text to explain the consequences of a choice
  • Don’t use to confirm very common, obviously formats for fields (e.g. dollars and cents)