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.
<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 ofusa-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 theid
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.
<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
Guidance
- Radio buttons typically appear inside of
<fieldset>
s. The class name ofusa-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
<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
<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 ofusa-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
<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.