Skip to main content
USWDS + Tailwind

Input mask

Guide people toward a valid format as they type with an input mask for constrained text fields.

Examples

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
input-mask-demo.tsx
import { InputMask } from '@uswds-tailwind/react'


export default function InputMaskDemo() {
  return (
    <div className="space-y-12">
      <div className="max-w-xs">
        <InputMask.Root placeholder="___ __ ____">
          <InputMask.Label htmlFor="mask-ssn">Social Security Number</InputMask.Label>
          <div id="hint-ssn" className="text-gray-50">For example, 123 45 6789</div>
          <InputMask.Control>
            <InputMask.Placeholder />
            <InputMask.Input id="mask-ssn" inputMode="numeric" autoComplete="off" aria-describedby="hint-ssn" />
          </InputMask.Control>
        </InputMask.Root>
      </div>


      <div className="max-w-xs">
        <InputMask.Root placeholder="___-___-____">
          <InputMask.Label htmlFor="mask-phone">US Telephone Number</InputMask.Label>
          <div id="hint-phone" className="text-gray-50">For example, 123-456-7890</div>
          <InputMask.Control>
            <InputMask.Placeholder />
            <InputMask.Input id="mask-phone" inputMode="tel" autoComplete="tel" aria-describedby="hint-phone" />
          </InputMask.Control>
        </InputMask.Root>
      </div>


      <div className="max-w-xs">
        <InputMask.Root placeholder="_____-____">
          <InputMask.Label htmlFor="mask-zip">ZIP Code</InputMask.Label>
          <div id="hint-zip" className="text-gray-50">For example, 12345-6789</div>
          <InputMask.Control>
            <InputMask.Placeholder />
            <InputMask.Input id="mask-zip" inputMode="numeric" autoComplete="postal-code" aria-describedby="hint-zip" />
          </InputMask.Control>
        </InputMask.Root>
      </div>


      <div className="max-w-xs">
        <InputMask.Root placeholder="___ ___" charset="A#A #A#">
          <InputMask.Label htmlFor="mask-alpha">Alphanumeric</InputMask.Label>
          <div id="hint-alpha" className="text-gray-50">For example, A1B 2C3</div>
          <InputMask.Control>
            <InputMask.Placeholder />
            <InputMask.Input id="mask-alpha" autoComplete="off" aria-describedby="hint-alpha" />
          </InputMask.Control>
        </InputMask.Root>
      </div>
    </div>
  )
}

Component API

Put Label, Control, Placeholder, and Input inside Root to guide entry in a fixed format.

Root<div>

Owns the mask and input value.

PropTypeDescription
placeholderstring (required)Defines the mask format.
charsetstringDefines accepted characters for placeholder positions.
defaultValuestringInitial uncontrolled value.
valuestringControlled value.
onValueChange({ value: string }) => voidReceives value changes.
ids{ root?: string; content?: string; input?: string }Overrides generated part IDs. Use Root IDs when a label or external control needs a stable input or trigger target.

Label<label>

Native label. Set htmlFor to the input ID explicitly, or use Field.Label with an enclosing Field.Root.

Control<div>

Aligns the placeholder guide and input.

Placeholder<span>

Displays the unentered mask characters.

Input<input>

Receives the typed value. Field.Root can supply validation state; the mask itself does not validate completeness.

AttributeValuePurpose
data-invalidPresent when invalidStyle the error state.