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.

Patterns

Form Feedback

Error messages let users know when they have made a mistake on a form field.

Error messages

Error messages let users know when they have made a mistake on a form field.

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

Errors on text inputs

For all text inputs, the error message is placed between the label and the input.

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>

Guidance

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>

Error on select boxes

Select boxes a pattern similar to text inputs. The guidance is similar as well.

This is the error message
<div class="usa-input-error">
  <label class="usa-input-error-label" for="select-159">select label</label>
  <span class="usa-input-error-message" id="select-159-error-message" role="alert">This is the error message</span>
  <select aria-describedby="select-159-error-message" id="select-159" name="Attribute name">
    <option value=""></option>
    <option value="first option">first option</option>
    <option value="second option">second option</option>
    <option value="third option">third option</option>
  </select>
</div>

Guidance

Error messages are generally the same. The error message is slightly different in that it does not include the screen reader-only “Error” text.

<span class="usa-input-error-message" id="select-159-error-message" role="alert">This is the error message</span>

Errors on radio buttons

Radio Buttons Error Radio Button errorMessage
<fieldset class="fieldset-input usa-input-error">
  <legend class="legend-label usa-input-error-label">Radio Buttons</legend>
  <span class="usa-input-error-message" role="alert" id="defaultId-error-message">
    <span class="sr-only">Error</span> Radio Button errorMessage</span>
  <div class="form-radio-buttons">
    <div class="radio-button">
      <input type="radio" autocomplete="false" id="defaultId-0" name="defaultName" value="option 1" />
      <label name="defaultName-0-label" for="defaultId-0">option 1</label>
    </div>
  </div>
  <div class="form-radio-buttons">
    <div class="radio-button">
      <input type="radio" autocomplete="false" checked="" id="defaultId-1" name="defaultName" value="option 2" />
      <label name="defaultName-1-label" for="defaultId-1">option 2</label>
    </div>
  </div>
  <div class="form-expanding-group">
    <div class="form-radio-buttons">
      <div class="radio-button">
        <input type="radio" autocomplete="false" id="defaultId-2" name="defaultName" value="expanding option 3" />
        <label name="defaultName-2-label" for="defaultId-2">option 3 label</label>
      </div>
    </div>
  </div>
</fieldset>

Guidance

  • Radio buttons typically appear inside of <fieldset>s. The class name of usa-input-error may be placed on the <fieldset> that contains all of the radio buttons.
  • The error message is placed just below the <legend>

Errors on checkboxes

Unlike other form elements, error messages for checkboxes appear below

Error message below checkbox

Error Error message
If you don’t find your school in the search results, then check the box to enter in your school information manually. Error Error message
<div class="form-checkbox usa-input-error">
  <input type="checkbox" autocomplete="false" aria-describedby="checkbox-140-error-message" id="checkbox-140" />
  <label class="usa-input-error-label" name="undefined-label" for="checkbox-140">Checkbox 1
  </label>
  <span class="usa-input-error-message" role="alert" id="checkbox-140-error-message">
    <span class="sr-only">Error</span>
    Error message
  </span>
</div>

<div class="form-checkbox usa-input-error">
  <span class="label-above-checkbox">If you don’t find your school in the search results, then check the box to enter in your school information manually.</span>
  <input type="checkbox" autocomplete="false" aria-describedby="checkbox-141-error-message" id="checkbox-141" />
  <label class="usa-input-error-label" name="undefined-label" for="checkbox-141">Checkbox 2</label>
  <span class="usa-input-error-message" role="alert" id="checkbox-141-error-message">
    <span class="sr-only">Error</span>
    Error message
  </span>
</div>

Error message with a checkbox group

Checkbox group Error: This is an error message
<fieldset class="fieldset-input usa-input-error">
  <legend class="legend-label usa-input-error-label">Checkbox group</legend>
  <span class="usa-input-error-message" role="alert" id="default-error-message">
    <span class="sr-only">Error:</span> This is an error message
  </span>
  <div class="form-expanding-group">
    <div class="form-checkbox-buttons">
      <input type="checkbox" autocomplete="false" id="default-0" value="value" />
      <label name="undefined-0-label" for="default-0">Checkbox label</label>
    </div>
  </div>
  <div class="form-expanding-group">
    <div class="form-checkbox-buttons">
      <input type="checkbox" autocomplete="false" id="default-1" value="value" />
      <label name="undefined-1-label" for="default-1">Checkbox label</label>
    </div>
  </div>
</fieldset>
Guidance
  • Checkbox groups typically appear inside of <fieldset>s. The class name of usa-input-error may be placed on the <fieldset> that contains all of the checkboxes.
  • The error message is placed just below the <legend>

Error message on file input

Error Error message
<div class="usa-input-error">
  <label class="usa-input-error-label" for="file-input-149"></label>
  <span class="usa-input-error-message undefined" role="alert" id="file-input-149-error-message">
    <span class="sr-only">Error</span>
    Error message
  </span>
  <label role="button" tabindex="0" for="file-input-149" class="usa-button usa-button-secondary">Upload some files</label>
  <input type="file" multiple="" style="display:none;" accept="String" id="file-input-149" name="Name" />
</div>

Guidance

The guidance for file inputs is the same as the text inputs.