Components

Input mask

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

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

Social Security Number Input Mask

For example, 123 45 6789

US Telephone Number Input Mask

For example, 123-456-7890

9 Digit US ZIP Code Input Mask

For example, 12345-6789

Alphanumeric Input Mask

For example, A1B 2C3

<h3 class="site-preview-heading">Social Security Number Input Mask</h3>

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

<h3 class="site-preview-heading">US Telephone Number Input Mask</h3>

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

<h3 class="site-preview-heading">9 Digit US ZIP Code Input Mask</h3>

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

<h3 class="site-preview-heading">Alphanumeric Input Mask</h3>

<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 to allow for a valid input mask. 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

Using the input mask component

The examples in the Preview section, above, are common input masks, but you can adapt the code to meet the needs of your project. In order to extend the functionality of the input mask, you must include a placeholder attribute as the visible input mask, using the underscore _ to represent a character the user should enter. You may use punctuation literals like [space], -, /, or ( to help format your mask, but these literals will not be included in the final submitted value. You also need a related pattern attribute on the input element, its value epxressed as a regular expression that describes the intended format of the input data. Additionally, if the expected input is numeric, make sure to add the inputmode="numeric" attribute and setting so the numeric keypad is displayed. For example, an input with an input mask of three groups of three numerals, separated with spaces might have the following properties:

placeholder="___ ___ ___"
pattern="\d\d\d \d\d\d \d\d\d"
inputmode="numeric"

The input mask and alphanumeric characters

Input mask examples include an alphanumeric version which can be customized to meet your needs. To implement an alphanumeric input mask, you will need to add the attribute data-charset to the input tag. Similar to the pattern attribute, include a number sign # for each number and an A for each required letter. We recommend changing inputmode to text so the full keyboard is available to your user.

If your input mask calls for a pattern such as 1A2 B3C, you would implement that by adding the following attributes and character formatting to your input element:

placeholder="___ ___"
pattern="\w\d\w \d\w\d"
data-charset="A#A #A#"

Input mask settings

This component has no settings.

Input mask variants

This component has no variants.

Known issues

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

  • Recovering from an error is difficult due to lack of feedback. More information on GitHub: uswds#5481

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-input-mask";

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
  • JavaScript
 No

Fixed a bug that caused input mask to break when it is not a direct child of a form. Nested input masks will now initialize and work properly. More information: uswds#5518

2024-03-13 N/A
  • Guidance
 No

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

2023-08-23 3.6.0
  • Styles
 No

Fixed a bug that caused the hover state to adopt disabled styling. More information: uswds#5378

2023-08-23 3.6.0
  • Accessibility
  • Styles
 No

Improved legibility in forced colors mode. More information: uswds#5378

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency and visibility of disabled styles. Form elements with the disabled or aria-disabled attribute now get consistent styling and have proper color contrast. More information: uswds#5063

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Improved consistency of disabled styles in forced colors mode. More information: uswds#5295

2022-11-14 3.3.0
  • Guidance
  • JavaScript
  • Markup
  • Styles
 No

Component released. More information: uswds#4884