InputMask
InputMask is an Input that formats digits as the user types. In mask, 0 stands for a digit
and any other character is a literal. onChange receives the formatted string, not an event, debounced by 250 ms.Forms
When to use
Use when
- The value is a fixed-format number: phone, tax ID, postal code, a typed date.
- You want the formatted string (
(11) 91234-5678) as the value.
Avoid when
- The value is free text or contains letters — use
Input; the mask keeps digits only. - The value is money — use
InputCurrency. - The user picks a date — use
InputDate.
Usage
<InputMask aria-label="Phone" mask="(00) 00000-0000" onChange={setPhone} />
<InputMask aria-label="Postal code" mask="00000-000" onChange={setPostalCode} />
<InputMask aria-label="Date" mask="00/00/0000" onChange={setDate} />Non-digits are stripped and the result is cut at the mask length. A new value prop is re-formatted, so a
Form reset() or setValue() updates the field. Sizes, states and clearable work as on Input.
In a Form
<Form
handleSubmit={onSubmit}
fields={{
phone: {
label: 'Phone',
component: InputMask,
inputProps: { mask: '(00) 00000-0000', clearable: true },
validation: z.string().length(15, 'Enter the full number'),
},
}}
/>Accessibility
InputMaskrenders no label: useFieldor passaria-label.- Show the expected format in the
placeholderor the hint; the mask does not announce it.
Properties
Name
Type
Default
Description
clearablebooleannoneShows a clear button ("×" icon) when there is a value. Requires `reset`
to work outside a `Form`.
clearLabelstring'Limpar'Accessible name of the clear button (`clearable`) — it shows only an icon.
iconanynoneReact element rendered inside the input (usually an `<Icon />`).
When set, the input automatically makes room to avoid collision
with the typed text.
@example ```tsx
<Input icon={<Icon icon={search} />} iconPosition="left" />
```
iconPosition"right""left"'right'Side on which the icon (`icon` or the clear button) is rendered.
mask *stringnoneMask pattern — `0` accepts a digit, any other character is a
literal (kept between the digits). Examples:
- `(00) 00000-0000` → phone
- `000.000.000-00` → CPF
- `00/00/0000` → date
onChange((value: string) => void)noneCallback fired (debounced at 250 ms) with the already formatted string.
reset(() => void)noneCallback invoked when the user clicks the clear button (`clearable`).
Inside a `Form`, it is injected automatically; in standalone use, it
must clear the controlled state.
size"expansive""medium""compact""micro"'medium'Size token of the input.
valuestringnonevariant"default""success""error"'default'Visual variant of the input — reflects the validation state.