Skip to main content
USWDS + Tailwind

Help shape v2! Take a short survey to make this tool better for everyone.

Input mask

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

Example

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
For example, 123 45 6789
For example, 123-456-7890
For example, 12345-6789
For example, A1B 2C3
Twig 
<div class="space-y-12">


  <div class="max-w-xs">
    <label for="ssn" class="block">Social Security Number</label>
    <div id="input-hint" class="text-gray-50">For example, 123 45 6789</div>
    <div x-input-mask class="mt-2 relative">
      <div aria-hidden="true" class="absolute inset-0 p-2 pointer-events-none border inline-flex whitespace-pre">
        <span x-input-mask:input-placeholder class="invisible"></span>
        <span x-input-mask:mask-placeholder class="text-gray-50"></span>
      </div>
      <input x-input-mask:input x-mask="999 99 9999" id="ssn" placeholder="___ __ ____" pattern="^(?!(000|666|9))\d{3} (?!00)\d{2} (?!0000)\d{4}$" aria-describedby="input-hint" class="p-2 w-full h-10 border border-gray-60 focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v data-[invalid]:ring-4 data-[invalid]:ring-red-60v data-[invalid]:border-transparent data-[invalid]:outline-offset-4"/>
    </div>
  </div>


  <div class="max-w-xs">
    <label for="phone" class="block">US Telephone Number</label>
    <div id="input-hint-phone" class="text-gray-50">For example, 123-456-7890</div>
    <div x-input-mask class="mt-2 relative">
      <div aria-hidden="true" class="absolute inset-0 p-2 pointer-events-none border inline-flex whitespace-pre">
        <span x-input-mask:input-placeholder class="invisible"></span>
        <span x-input-mask:mask-placeholder class="text-gray-50"></span>
      </div>
      <input x-input-mask:input x-mask="999-999-9999" id="phone" placeholder="___-___-____" pattern="\d{3}-\d{3}-\d{4}" aria-describedby="input-hint-phone" class="p-2 w-full h-10 border border-gray-60 focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v data-[invalid]:ring-4 data-[invalid]:ring-red-60v data-[invalid]:border-transparent data-[invalid]:outline-offset-4"/>
    </div>
  </div>




  <div class="max-w-xs">
    <label for="zip" class="block">ZIP Code</label>
    <div id="input-hint-zip" class="text-gray-50">For example, 12345-6789</div>
    <div x-input-mask class="mt-2 relative">
      <div aria-hidden="true" class="absolute inset-0 p-2 pointer-events-none border inline-flex whitespace-pre">
        <span x-input-mask:input-placeholder class="invisible"></span>
        <span x-input-mask:mask-placeholder class="text-gray-50"></span>
      </div>
      <input x-input-mask:input x-mask="99999-9999" placeholder="_____-____" pattern="^[0-9]{5}(?:-[0-9]{4})?$" id="zip" aria-describedby="input-hint-zip" class="p-2 w-full h-10 border border-gray-60 focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v data-[invalid]:ring-4 data-[invalid]:ring-red-60v data-[invalid]:border-transparent data-[invalid]:outline-offset-4"/>
    </div>
  </div>


  <div class="max-w-xs">
    <label for="alpha" class="block">Alphanumeric</label>
    <div id="input-hint-alpha" class="text-gray-50">For example, A1B 2C3</div>
    <div x-input-mask class="mt-2 relative">
      <div aria-hidden="true" class="absolute inset-0 p-2 pointer-events-none border inline-flex whitespace-pre">
        <span x-input-mask:input-placeholder class="invisible"></span>
        <span x-input-mask:mask-placeholder class="text-gray-50"></span>
      </div>
      <input x-input-mask:input x-mask="a9a 9a9" placeholder="___ ___" pattern="\w\d\w \d\w\d" id="alpha" aria-describedby="input-hint-alpha" class="p-2 w-full h-10 border border-gray-60 focus:outline focus:outline-offset-0 focus:outline-4 focus:outline-blue-40v data-[invalid]:ring-4 data-[invalid]:ring-red-60v data-[invalid]:border-transparent data-[invalid]:outline-offset-4"/>
    </div>
  </div>


</div>

Component API

Root

  • x-input-mask

    Custom Alpine directive that marks the Input Mask Root.

Input

  • x-input-mask:input

    Custom Alpine directive that marks the Input Mask.

  • x-mask

    Type: string

    This attribute defines the values that the input will accept. 9 allows any number, a allows any letter, * allows any character.

  • placeholder

    Type: string

    The displayed “empty” values of the input. Used to show the Input Mask Mask Placeholder value.

  • pattern

    Type: RegExp

    Native form validation attribute.

    Take care to ensure this value validates according to your x-mask attribute. A mismatch may lead to a confusing user experience where users are unable to submit a form.

Input Display

Matches the value entered in the input. Match the width of the value entered in the input.

  • x-input-mask:input-placeholder

    Custom Alpine directive that marks the Input Mask Input Placeholder.

Mask Display

Displays the updated mask value as the user types.

  • x-input-mask:mask-placeholder

    Custom Alpine directive that marks the Input Mask Mask Placeholder.

Progressive Enhancement

Because this component relies on JavaScript, use the native placeholder attribute to define the “mask” value.

Once JavaScript loads, the placeholder attribute will be removed and used as the initial value of the Input Mask Mask Placeholder. If JavaScript doesn’t load, users will see the native placeholder.

Accessibility

Be sure to show an example of the proper expected formatting. While a placeholder can sometimes be a useful affordance, when used alone, it’s not reliable enough to ensure users understand the expected format.

This can be achieved by creating an “input hint” and linking that value to the input via the aria-describedby attribute, as demonstrated in the examples above.