Masked Input

ProNew

An input that formats as you type with a pattern such as (999) 999-9999: it keeps the caret in the right place, handles paste and Backspace over punctuation, returns the raw value, and reports when the mask is complete.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/masked-input

Usage

Mask tokens: 9 digit, a letter, * letter or digit; any other character is shown as it is, and \ escapes a token. A mask formats; it does not validate that a date exists or a card number passes the Luhn check, so validate the raw value too.

Exports

Export	Description
`MaskedInput`	The input.
`MASKS`	Ready masks: US phone, date, time, card, ZIP, ZIP+4, SSN, UK postcode, IBAN.
`applyMask(text, mask, uppercase?)`	`{ masked, raw, complete }`.
`unmask(text, mask)`, `maskPlaceholder(mask)`, `parseMask(mask)`	Helpers.

Props

Prop	Type	Default	Description
`mask`	`string`	-	The pattern.
`value`	`string`	-	The raw value.
`onValueChange`	`(raw, { masked, raw, complete }) => void`	-
`uppercase`	`boolean`	`false`	Upper-case letters.
`showMaskPlaceholder`	`boolean`	`true`	`(___) ___-____` as the placeholder.

All other props go to the input (id, name, autoComplete, aria-describedby, ...).

Accessibility

A normal text input with its own label: add a visible Label and a hint about the format, because a placeholder is not a label and disappears once typing starts.
inputmode="numeric" is set when the mask is digits only, so touch keyboards show the number pad; autocomplete is passed through (cc-number, tel, postal-code).
Punctuation is added as you type but never read as part of the value; Backspace after punctuation deletes the digit before it, and the caret stays where the edit happened, including after a paste.
The mask changes the text the screen reader reads back as you type ("(555) 123"). Keep the hint ("US phone number") in aria-describedby instead of relying on the pattern.

Testing

The component ships with a Testing Library test (masked-input.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/masked-input

Usage

Exports

Export	Description
`MaskedInput`	The input.
`MASKS`	Ready masks: US phone, date, time, card, ZIP, ZIP+4, SSN, UK postcode, IBAN.
`applyMask(text, mask, uppercase?)`	`{ masked, raw, complete }`.
`unmask(text, mask)`, `maskPlaceholder(mask)`, `parseMask(mask)`	Helpers.

Props

Prop	Type	Default	Description
`mask`	`string`	-	The pattern.
`value`	`string`	-	The raw value.
`onValueChange`	`(raw, { masked, raw, complete }) => void`	-
`uppercase`	`boolean`	`false`	Upper-case letters.
`showMaskPlaceholder`	`boolean`	`true`	`(___) ___-____` as the placeholder.

All other props go to the input (id, name, autoComplete, aria-describedby, ...).

Accessibility

A normal text input with its own label: add a visible Label and a hint about the format, because a placeholder is not a label and disappears once typing starts.
inputmode="numeric" is set when the mask is digits only, so touch keyboards show the number pad; autocomplete is passed through (cc-number, tel, postal-code).
Punctuation is added as you type but never read as part of the value; Backspace after punctuation deletes the digit before it, and the caret stays where the edit happened, including after a paste.
The mask changes the text the screen reader reads back as you type ("(555) 123"). Keep the hint ("US phone number") in aria-describedby instead of relying on the pattern.

Testing

The component ships with a Testing Library test (masked-input.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.