Input Mask

formUSWDS-derivedinteractive

Formatted input overlay showing the expected pattern (phone, SSN, zip+4).

Variants

Phone Input Mask

Phone number

<flex-input-mask data-mask="(___) ___-____">
  <label class="flex-label" for="phone">Phone number</label>
  <div class="flex-input-mask__wrapper">
    <input class="flex-input flex-input-mask__input" id="phone" name="phone" type="text" inputmode="tel" placeholder="(___) ___-____"/>
    <span class="flex-input-mask__overlay" aria-hidden="true">(___) ___-____</span>
  </div>
</flex-input-mask>

SSNInput Mask

Social Security number

<flex-input-mask data-mask="___-__-____">
  <label class="flex-label" for="ssn">Social Security number</label>
  <div class="flex-input-mask__wrapper">
    <input class="flex-input flex-input-mask__input" id="ssn" name="ssn" type="text" inputmode="numeric" placeholder="___-__-____"/>
    <span class="flex-input-mask__overlay" aria-hidden="true">___-__-____</span>
  </div>
</flex-input-mask>

Zip Input Mask

ZIP code + 4

<flex-input-mask data-mask="_____-____">
  <label class="flex-label" for="zip">ZIP code + 4</label>
  <div class="flex-input-mask__wrapper">
    <input class="flex-input flex-input-mask__input" id="zip" name="zip" type="text" inputmode="numeric" placeholder="_____-____"/>
    <span class="flex-input-mask__overlay" aria-hidden="true">_____-____</span>
  </div>
</flex-input-mask>

Contract

Class mapping

USWDS	Flex	Notes
`usa-input-masking`	`<flex-input-mask> (custom element)`	Container element with data-mask attribute
`usa-masked`	`.flex-input-mask__input`	Input element with transparent background
`usa-input-masking__content (overlay)`	`.flex-input-mask__overlay`	Overlay showing remaining mask characters

Verified properties

background-colorfont-sizefont-family

Intentional differences

background-color: ours = transparent, USWDS = transparent

Both use transparent background on the input so the overlay shows through

position: ours = relative, USWDS = static

We use position: relative + z-index to stack the input above the overlay span; USWDS uses a different overlay approach

Behavior promises

✓ Typing digits formats according to phone mask
✓ Typing digits formats according to SSN mask
✓ Overlay updates to show remaining mask characters
✓ Non-digit keys are rejected for numeric masks
✓ Pasting a value formats correctly
✓ Accessibility audit passes

Source CSS

Base styles: Form Control Base

/* flex-input-mask — USWDS Input Mask conformance
   Formatted input overlay showing the expected pattern.
   Extends: Form Control Base (base-classes.css#form-control) for input */

flex-input-mask {
  display: block;
}

.flex-input-mask__wrapper {
  position: relative;
  display: inline-block;
  inline-size: 100%;
  max-inline-size: var(--flex-control-max-width);
}

.flex-input-mask__input {
  /* Transparent background so overlay shows through */
  background-color: transparent;
  position: relative;
  z-index: 1;
}

.flex-input-mask__overlay {
  position: absolute;
  inset-block-start: 0;
  inset-inline-start: 0;
  /* Match the input's padding so mask characters align with typed text */
  padding: var(--flex-control-padding);
  margin-block-start: var(--flex-control-margin-top);
  font-size: var(--flex-text-uswds);
  line-height: 1.3;
  block-size: var(--flex-control-height);
  display: flex;
  align-items: center;
  color: var(--flex-color-text-muted);
  pointer-events: none;
  white-space: pre;
  z-index: 0;
}