/// Inputs

MaskInput

An Input that formats typing against a fixed mask (phone, card, date), owning the raw characters and displaying the masked string.

import { MaskInput } from "@protocore/pds";

View as Markdown

Basics

Pass a mask string — # is a digit, A a letter, * alphanumeric, and every other character is a literal shown in place. The component inserts literals as you type.

Raw + masked value

onValueChange(raw, masked) reports both the significant characters and their formatted rendering. Store raw; show masked. The control is controllable by its raw value.

raw: — · masked: —

Formats

The same component covers card numbers, dates, and license plates — it is just a different mask.

Card

Expiry

License plate

When to use it

Use MaskInput for fixed-shape values that read better with separators — phone numbers, card numbers, dates, postal codes. For free numeric entry with steppers use NumberInput; for a one-time code use PinInput / OTPInput; for calendar-backed dates use DateInput. A mask formats input — it does not guarantee the value is real; validate on submit.

Usage

Persist the `raw` value; render the `masked` one.
Give it an `aria-label` or wrap it in a `Field`.
Match the mask to the real format your backend expects.

Don't

Don't treat a full mask as validation — a well-formed phone number can still be wrong.
Don't use a mask for open-ended text — it drops non-matching characters.
Don't mask secret one-time codes — use PinInput/OTPInput.

Accessibility

Renders a standard text input, so it inherits the Input focus ring and `aria-invalid`.
`inputMode` is inferred (`numeric` for digit-only masks) to surface the right mobile keypad.
Non-matching characters are ignored rather than silently accepted, keeping the display honest.

`MaskInput` props

Prop	Type	Default	Description
`className`	`string`	—
`defaultValue`	`string`	—	Initial raw value when uncontrolled.
`invalid`	`boolean`	—	Mark the field invalid — danger border plus `aria-invalid`.
`mask` *	`string`	—	The format mask — `#` digit, `A` letter, `*` alphanumeric; other chars are literals.
`onValueChange`	`((raw: string, masked: string) => void)`	—	Fires with the next raw value and its masked rendering.
`size`	`enum`	`md`	Control height: `sm` (32) · `md` (36, default) · `lg` (40).
`style`	`CSSProperties`	—
`value`	`string`	—	Controlled raw value (significant characters only). Pair with `onValueChange`.