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.

Label Error message

Please pick a number Error message

Label 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.

select label 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 Radio Button errorMessage

option 1

option 2

option 3 label

<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

Checkbox 1 Error message

If you don’t find your school in the search results, then check the box to enter in your school information manually. Checkbox 2 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 This is an error message

Checkbox label

<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 message Upload some files

<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.