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

Using the validation component

• 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.
• Input fields which have custom validation logic can automatically provide helpful feedback to users if they are assigned a data-validation-element attribute set to a CSS selector that uniquely identifies a .usa-checklist, e.g. data-validation-element="#validate-code".
• For each kind of validation you’d like to provide feedback on:
  1. Come up with a name for the validator, e.g. uppercase. It shouldn’t have any spaces in it.
  2. On one of the list elements in the .usa-checklist, set the data-validator attribute to the name of the 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 field, add a field called data-validate-validator name and set its value to a regular expression (described on RegexOne) that represents whether the validator’s condition is met, e.g. data-validate-uppercase="[A-Z]".

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-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	3.0.0	Assets JavaScript Styles	Breaking	Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656