---
title: Input mask (React) - USWDS + Tailwind
description: Guide people toward a valid format as they type with an input mask
  for constrained text fields.
---

# Input mask

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

## Examples

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

| Prop | Type | Description |
| - | - | - |
| `placeholder` | `string (required)` | Defines the mask format. |
| `charset` | `string` | Defines accepted characters for placeholder positions. |
| `defaultValue` | `string` | Initial uncontrolled value. |
| `value` | `string` | Controlled value. |
| `onValueChange` | `({ value: string }) => void` | Receives 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.

| Attribute | Value | Purpose |
| - | - | - |
| `data-invalid` | `Present when invalid` | Style the error state. |