Form

Refer to the U.S. Web Design System for usage guidance

Accessibility considerations for all form elements

Do not disable form elements

Disabling form elements is discouraged as a design crutch. Thus most of our form components do not support a disabled property. If you feel that you have a unique design problem that requires a disabled field you may lobby the accessibility Community of Practice and the Design System Council but know that, thus far, exceptions to this rule are rarely granted.

Do not disable buttons

Normally, with regular form controls, it is best to fully remove anything the user can’t interact with or which serves no purpose. However, disabling a “button” to act as a guide to the level of form completion (i.e. you are not able to proceed to the next step until the form contains enough data) is a common anti-pattern.

Disabled buttons don’t explain what’s wrong

When buttons are inactive, some users– particularly those with cognitive disabilities- may not know how to activate them. Disabled buttons don’t explain what’s wrong. They communicate that something is off, but very often that is not enough information. As a result, users are left wondering what’s actually missing, and consequently are locked out entirely. For example, if someone were to type in a short acronym like “VA” to search and the button doesn’t become accessible, they may think the search field is broken.

In addition, disabled buttons can be unintentionally read out and accessed by mobile screen readers using touch controls.

What to do instead

While it is technically possible, we strongly discourage disabling buttons. Here are recommendations on how to handle specific interactions:

• Lack of required fields. When a user attempts to submit a form without entering all required form fields:
  • Announce the error and shift focus to the first unfilled required form field.
  • Properly indicate required form elements (the right thing will happen for you when you use the required property on form fields in the Design System).
• No longer valid options. If certain options in a form are no longer valid then there are two options:
  1. Replace the form elements that can no longer be changed with text representing the current value instead of the current value within a disabled input.
  2. Hide the form elements that are no longer valid.

Is it ever valid to disable a button?

Post-form submission or post-action it can be appropriate to disable the submit or action button as the system is in-between states and loading or taking action. This behavior is often seen on buttons that make a purchase or reservation to prevent the user from accidentally triggering the action multiple times.

How to group form controls

• Group each set of thematically related controls in a fieldset element. Use the legend element as a heading within each one. The fieldset and legend elements make it easier for screen reader users to navigate the form.
• Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.
• Embed multiple fieldsets and legends for more complex forms if the form is not broken in separate chapters.
• Keep your form inputs and labels arranged vertically along the same Y axis. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.

Error handling

View va-text-input with error in Storybook

• In all cases, only show error validation messages or stylings after a user has interacted with a particular field.
• The form field and its corresponding <label> are wrapped in a container which provides a thick border and padding to visual indicate an error message to users who might have difficulty perceiving contrast. It also changes the border of the input to red as a secondary indicator.
• An error message is placed between the label and the form field.
• The form field receives an aria-describedby attribute that references the id of the error message.
• Prepending <span class="sr-only">Error</span> to error messages alerts screen screen readers clearly that an error exists.

Review the help users to recover from errors pattern

Hint text

When a detailed form input label is not enough to convey the meaning or purpose of the input, we have three options for including additional context:

1. Beneath the label (default)
2. Inline within the label
3. Additional info

Default hint text

View Label with hint text in Storybook

This should be used in the case where the needed clarification is a little longer, but less than two sentences. These should ideally not wrap more than twice for a total of three lines.

Inline within the label

View Label with inline hint text in Storybook

This should be used in the case where the needed clarification is very short.

With Additional info

View Label with additional info hint text in Storybook

Using the additional info component should only be done in cases where the needed clarification is long, complex, requiring more than two sentences or multiple paragraphs, or special formatting (bullet points, links, etc.).

We want to avoid this variation when possible. Use of this component for this purpose is a last resort when attempts at reducing the content have failed. If a field needs a lot of explanation, it should ideally be moved to a distinct page with explanation on the page itself.