An input mask is a string expression that constrains input to support valid input values.
Social Security Number Input Mask
US Telephone Number Input Mask
9 Digit US ZIP Code Input Mask
Alphanumeric Input Mask
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.
- Wait to validate. Only show error validation messages or stylings after a user has interacted with a particular field.
- Include a label. Make sure each form control includes a
forattribute related to the
inputelement it labels.
- Use helpful hint text. Make sure any hint text helps users understand what they need to input.
- Customization. As you customize, make sure you follow accessibility guidelines for form templates and the accessibility guidelines for form controls.
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
( 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.
Meaningful code and guidance updates are listed in the following table:
Fixed a bug that caused the hover state to adopt disabled styling. More information: uswds#5378
Improved legibility in forced colors mode. More information: uswds#5378
Improved consistency and visibility of disabled styles.
Form elements with the
Improved consistency of disabled styles in forced colors mode. More information: uswds#5295
Component released. More information: uswds#4884