Input Mask

InputMask guides users through structured values such as phone numbers, dates, card numbers, account codes, and serial numbers while preserving a normal accessible text input.

Basic usageCopy Anchor Link

The mask uses tokens for editable positions and literal characters for separators.

import { InputMask } from '@mosmox/ui';

<InputMask label="Phone number" mask="+1 (999) 999-9999" inputMode="tel" />
<InputMask label="Date" mask="99/99/9999" inputMode="numeric" />

Preset masksCopy Anchor Link

Use preset when the format is common. Presets provide the mask, recommended mobile keyboard, and a useful placeholder.

<InputMask label="Phone" preset="phone" />
<InputMask label="International phone" preset="internationalPhone" />
<InputMask label="Date" preset="date" />
<InputMask label="Credit card" preset="creditCard" />
<InputMask label="Expiration" preset="expiry" />
<InputMask label="IBAN" preset="iban" />

Available presets are listed below. They set the mask, input mode, and placeholder; you can still override these values with explicit props.

Import inputMaskPresets when you need to inspect or reuse the definitions in your own form controls. A custom preset object supports mask, inputMode, placeholder, guide, maskPlaceholder, and formatChars; explicit component props take precedence over the corresponding preset values.

Built-in tokens are:

• 9 — a digit;
• A — a letter;
• * — an alphanumeric character;
• # — a hexadecimal character.

The * token accepts letters and digits, while # accepts hexadecimal characters (0-9, a-f, A-F). Token matching is case-sensitive according to the supplied regular expression.

Literal characters such as +, spaces, parentheses, slashes, and dashes are inserted automatically.

Controlled values and raw valuesCopy Anchor Link

Use value and onChange for controlled forms. The callback receives both the formatted value and the raw token value.

const [phone, setPhone] = useState('');

<InputMask
  mask="+1 (999) 999-9999"
  value={phone}
  onChange={(formatted, raw) => {
    setPhone(formatted);
    console.log(raw); // only the digits
  }}
/>

Use defaultValue for uncontrolled input. onComplete fires once all token positions are valid.

Guide and placeholder modesCopy Anchor Link

Set showMask or guide to display placeholders for unfilled positions. maskPlaceholder customizes the placeholder character.

<InputMask mask="9999 9999" showMask maskPlaceholder="_" />
<InputMask mask="AA-9999" guide maskPlaceholder="•" />

Without guide mode, the field stays compact and only renders the part already entered.

Custom tokensCopy Anchor Link

formatChars extends or replaces token definitions for domain-specific formats.

<InputMask
  label="Serial number"
  mask="SS-999-XX"
  formatChars={{
    S: /[A-Z]/,
    X: /[0-9A-F]/,
  }}
/>

Custom token keys are any single-character mask symbols not used as literals.

Validation, errors, and statesCopy Anchor Link

required reports a required error after blur when no token value exists. Pass error for application validation. onValidityChange reports whether all mask positions are complete.

<InputMask
  label="Expiration"
  mask="99/99"
  required
  onValidityChange={(valid) => setValid(valid)}
  error={serverError}
  helperText="MM/YY"
/>

disabled prevents editing. readOnly keeps the formatted value visible without allowing changes. clearable adds a clear action.

The component preserves the caret while inserting, selecting, pasting, and deleting masked characters. Backspace and Delete remove token values without trapping the cursor on literal separators.

Sizes and browser integrationCopy Anchor Link

size accepts xs (extra small), sm (small), and default; variant accepts outline and filled. The component follows the same control tokens and slot model as Input, including leadingIcon, prefix, suffix, trailingIcon, loading, clearable, fullWidth, and description. Forward name, id, autoComplete, and inputMode for form integration and mobile keyboard selection. To make a trailing icon actionable, provide onTrailingIconClick and an accessible trailingIconLabel.

<InputMask
  name="postalCode"
  autoComplete="postal-code"
  inputMode="numeric"
  size="xs"
  mask="99999"
/>

<InputMask
  label="Phone"
  preset="phone"
  trailingIcon={<span aria-hidden="true">✓</span>}
  trailingIconLabel="Verify phone"
  onTrailingIconClick={() => alert('Phone verified')}
/>

Use a custom preset object when a reusable format needs a local definition:

const employeeCode = {
  mask: 'AA-999-XX',
  inputMode: 'text' as const,
  placeholder: 'AB-123-FF',
};

<InputMask label="Employee code" preset={employeeCode} />

AccessibilityCopy Anchor Link

The component renders a native text input, associates label with the input, exposes aria-invalid for errors, and supports normal browser editing, selection, paste, and keyboard behavior. Provide aria-label when no visible label is present.

APICopy Anchor Link

All other standard text-input attributes from InputHTMLAttributes<HTMLInputElement> are forwarded to the native input, except size, value, defaultValue, onChange, and placeholder, which use the mask-specific API above.