Skip to main content

Input mask

An input mask is a string expression that constrains input to support valid input values.


Social Security Number

Component Preview

For example, 123 45 6789

Component Code

<form class="usa-form">
  <label class="usa-label" for="ssn">Social Security Number</label>
  <div class="usa-hint" id="ssnHint">For example, 123 45 6789</div>
  <input
    id="ssn"
    inputmode="numeric"
    name="ssn"
    placeholder="___ __ ____"
    pattern="^(?!(000|666|9))\d{3} (?!00)\d{2} (?!0000)\d{4}$"
    class="usa-input usa-masked"
    aria-describedby="ssnHint"
  />
</form>

US Telephone Number

Component Preview

For example, 123-456-7890

Component Code

<form class="usa-form">
  <label class="usa-label" for="tel">US Telephone Number</label>
  <div class="usa-hint" id="telHint">For example, 123-456-7890</div>
  <input
    id="tel"
    type="tel"
    inputmode="numeric"
    name="tel"
    placeholder="___-___-____"
    pattern="\d{3}-\d{3}-\d{4}"
    class="usa-input usa-masked"
    aria-describedby="telHint"
  />
</form>

9 Digit US ZIP Code

Component Preview

For example, 12345-6789

Component Code

<form class="usa-form">
  <label class="usa-label" for="zip">ZIP Code</label>
  <div class="usa-hint" id="zipHint">For example, 12345-6789</div>
  <input
    id="zip"
    inputmode="numeric"
    name="zip"
    placeholder="_____-____"
    pattern="^[0-9]{5}(?:-[0-9]{4})?$"
    class="usa-input usa-masked"
    aria-describedby="zipHint"
  />
</form>

Alphanumeric

Component Preview

For example, A1B 2C3

Component Code

<form class="usa-form">
  <label class="usa-label" for="alphanumeric">Alphanumeric</label>
  <div class="usa-hint" id="alphanumericHint">For example, A1B 2C3</div>
  <input
    id="alphanumeric"
    inputmode="text"
    name="alphanumeric"
    placeholder="___ ___"
    pattern="\w\d\w \d\w\d"
    class="usa-input usa-masked"
    aria-describedby="alphanumericHint"
    data-charset="A#A #A#"
  />
</form>


Guidance

When to use the input mask component

Common input patterns.
In fields with a specific expected format like Social Security Number or ZIP code, an input mask allows you to constrain and shape the information being entered into that format, without impairing the user's ability to copy/paste or correct mistyping.

When to consider something else

When the input requires a free-form field.
When there isn't a common input pattern to use, input masking is not appropriate.
When the pattern is too complicated.
A pattern like email, with many possible scenarios for input, is not a good candidate for masking. Allow the user to enter their email address (or other complicated data) and have your validation library confirm before form submission.

Usability guidance

Wait to validate.
Only show error validation messages or stylings after a user has interacted with a particular field.

Accessibility guidance

Include a label.
Make sure each form control includes a label with a for attribute related to the id of the input element it labels.
Use helpful hint text.
Make sure any hint text helps users understand what they need to input.
Follow accessibility guidelines for form controls.
As you customize, make sure you follow accessibility guidelines for form templates and form controls.

Using the input mask component

Include a placeholder attribute.
Use the placeholder attribute as the visible input mask, using the underscore _ to represent a character the user should enter.
Include a pattern attribute.
Use the pattern attribute to define a regular expression that describes the intended format of the input data.
Set the appropriate inputmode.
For numeric inputs, add inputmode="numeric" to display the numeric keypad. For alphanumeric inputs, use inputmode="text".
For alphanumeric masks, use data-charset.
Add the data-charset attribute with # for numbers and A for letters.

USWDS Documentation

For more guidance, view the USWDS Input Mask Component Documentation.

Looking for U.S. government information and services?
Visit USA.gov