Components

Validation

Stating validation requirements up front, with live feedback, means users won’t be left guessing.

Testing has revealed some issues with this component. Learn more in the known issues section on this page.

Default

Enter a code

Code requirements

  • Use at least one uppercase character
  • Use at least one number 

<h3 class="site-preview-heading">Default</h3>
<form class="usa-form">
  <fieldset class="usa-fieldset">
    <legend class="usa-legend usa-legend--large">Enter a code</legend>
    <div class="usa-alert usa-alert--info usa-alert--validation">
      <div class="usa-alert__body">
        <h4 class="usa-alert__heading">Code requirements</h4>
        <ul class="usa-checklist" id="validate-code">
          <li class="usa-checklist__item" data-validator="uppercase">
            Use at least one uppercase character
          </li>
          <li class="usa-checklist__item" data-validator="numerical">
            Use at least one number
          </li>
        </ul>
      </div>
    </div>
    <label class="usa-label" for="code">Code</label>
    <input
      class="usa-input"
      id="code"
      name="code"
      data-validate-uppercase="[A-Z]"
      data-validate-numerical="\d"
      data-validation-element="validate-code"
    />
    <input class="usa-button" type="submit" value="Submit code" />
  </fieldset>
</form>

Guidance

When to use the validation component

Provide helpful validation feedback. Use the validation component to give immediate feedback on which validation requirements have been successfully met, and which are not completed yet.

Using the validation component

  • Validate on the server side as well. The validation component is intended primarily for usability, not as a robust security solution, since all the validation logic occurs on the client side. The validation should be “mirrored” on the server-side for security purposes.
  • Connect the input element to your validation checklist. Set the value of your input’s data-validation-element to the id of its related .usa-checklist. For example, if the .usa-checklist element has an id of validate-code, use data-validation-element="validate-code".
  • Customize the validation attributes. For each type of validation you’d like to provide feedback on:
    1. Come up with a custom name for your validator, e.g. uppercase. This name shouldn’t have any spaces in it.
    2. On the appropriate list item in .usa-checklist, set the data-validator attribute to the name of your custom validator, e.g. data-validator="uppercase". This is the list item that will appear “checked” when the validator’s condition is met.
    3. On the input element, add an attribute called data-validate-[validator name], where [validator name] is the custom name you created in step 1. Define this attribute with a regular expression (described on RegexOne) that represents whether the validator’s condition is met. For example, if your custom validator is called uppercase, use data-validate-uppercase="[A-Z]".

    For reference, you can find the complete implementation of this configuration in the “Component code” accordion panel at the top of this page.

Validation settings

This component has no settings.

Validation variants

This component has no variants.

Known issues

All known issues for validation are tracked in GitHub . Notable usability issues are tracked below:

  • Screen reader and screen magnification users did not notice when the validation status changed. More information on GitHub: uswds#5642
  • Some users are confused about the purpose of the validation component. The component does not match user expectations of how their information should be validated in a form input. More information on GitHub: uswds#5750

Help fix these issues or add details on GitHub. Don't have an account? Please join our community to share feedback and contribute to USWDS.

Package

  • Package usage: @forward "usa-validation";
  • Dependencies: usa-form, usa-fieldset, usa-legend, usa-alert, usa-checklist, usa-label, usa-input, usa-button

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-05-31 3.8.1
  • Accessibility
  • JavaScript
 No

Fixed a bug which caused non-interactive checklist items to receive focus on tab. Now, only the interactive input will receive focus. More information: uswds#5835

2024-03-13 N/A
  • Guidance
 No

Added known issues section. More information: uswds-site#2402

2024-03-11 3.8.0
  • JavaScript
  • Markup
 No

Added textarea support to the validation component. More information: uswds#5233

2022-12-21 N/A
  • Guidance
 No

Clarified implementation guidance and removed the # from the example data-validation-element value. More information: uswds-site#1851

2022-10-19 3.2.0
  • Accessibility
  • Guidance
  • JavaScript
  • Markup
 No

Improved status updates about the completion of validation requirements for users of assistive technologies. Component JavaScript generates the appropriate elements and ARIA attributes that help improve the experience of receiving status updates. More information: uswds#4914

2022-04-28 N/A
  • Guidance
 No

Updated package name to usa-validation. More information: uswds-site#1538

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-06-07 N/A
  • Guidance
 No

Updated package name to validation. More information: uswds-site#1219