Components

Validation

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

Enter a code

Code requirements

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

Code

<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">
        <h3 class="usa-alert__heading">Code requirements</h3>
        <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>

<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">
        <h3 class="usa-alert__heading">Code requirements</h3>
        <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.

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