Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Form

Use: Deployed
Form controls allow users to enter information.

Forms system documentation

The current forms library is considered a legacy product and is in maintenance mode. A new forms library is under development.

View documentation for the current forms library for VA.gov on the platform website.

Accessibility considerations for all form elements

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

Error Error message
Error Error message
Error Error message
<div class="usa-input-error">
  <label class="usa-input-error-label" for="text-input-161">Label</label>
  <span class="usa-input-error-message" role="alert" id="text-input-161-error-message">
  <span class="sr-only">Error</span> Error message</span>
  <input type="text" aria-describedby="text-input-161-error-message" id="text-input-161" placeholder="Placeholder" name="Name" maxlength="255" />
</div>

<div class="usa-input-error">
  <label class="usa-input-error-label" for="number-input-155">Please pick a number</label>
  <span class="usa-input-error-message" role="alert" id="number-input-155-error-message"><span class="sr-only">Error</span> Error message</span>
  <input type="number" min="1" max="10" aria-describedby="number-input-155-error-message" id="number-input-155" name="Name" placeholder="Numbers are between 1 and 10" />
</div>

<div class="usa-input-error">
  <label id="textarea-160-label" class="usa-input-error-label" for="textarea-160">Label</label>
  <span class="usa-input-error-message" role="alert" id="textarea-160-error-message">
    <span class="sr-only">Error</span>
    Error message
  </span>
  <textarea class="" aria-describedby="textarea-160-error-message" aria-labelledby="textarea-160-label" id="textarea-160" placeholder="Placeholder" name="Name" maxlength="255"></textarea>
</div>

In all cases, only show error validation messages or stylings after a user has interacted with a particular field.

In general, when there is an error on a form, a few things must happen.

  • The form field and its corresponding <label> are wrapped in a container with a class name of usa-input-error. This will provide 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.

The HTML for a typical error is:

<span class="usa-input-error-message undefined" role="alert" id="file-input-149-error-message">
  <span class="sr-only">Error</span>
  Error message
</span>

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 information:

Inline with the label

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

Example

As subtext beneath the label

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

Example

Edit this page in GitHub (Permissions required)
Last updated: Aug 25, 2022