PinInput
Enter pins and verification codes with automatic focus advance and clipboard support.
Anatomy#
Usage#
Use PinInput for verification codes, OTPs, or numeric PINs. It renders one single-character input
per slot.
Values and completion#
length sets the number of slots (default 5). value and defaultValue accept a joined string
('123456') or an array with one character per slot, and are filtered by validationType and
truncated to length. onValueChange always receives an array of length entries with '' for
empty slots; use .join('') for the string. onComplete receives the joined string once every slot
is filled. Set name to submit the joined value through a hidden input, and form to associate
the control with a <form> outside its ancestors. A native form reset restores defaultValue.
Validation type and mask#
validationType controls which characters a slot accepts: 'number' (digits), 'alpha' (letters),
'alphanumeric', or 'text' (any non-whitespace character, the default). It also picks the default
inputMode; set inputMode to override it. Use mask to render the slots as password inputs and
conceal the entered characters.
OTP autofill#
Use otp to set autocomplete="one-time-code", so mobile devices can fill codes from SMS messages.
The hidden input, rendered when name is set, also accepts pasted or autofilled full codes and
distributes them across the slots.
Normalization and invalid input#
Use normalizeValue to transform proposed values after validationType filtering, and
onValueInvalid to observe refused characters, with a reason of
'patternMismatch' or 'tooLong'. normalizeValue runs on string
value and defaultValue and on typed, pasted, or autofilled text; it must be idempotent.
Auto-submit#
Use autoSubmit to call requestSubmit() on the owning form right after onComplete, which runs
native validation and fires a submit event. The form comes from form, the inputs, or the closest
ancestor <form>; nothing happens without one.
Placeholder#
Use placeholder to show a character hint in empty slots that are not focused:
Separators#
Use groupSize to insert separators between groups of slots. Pass true to split the slots in
half, a number for fixed-size groups, or an array of consecutive group sizes. Use separatorRender
to replace the default • separator.
Keyboard interaction#
| Key | Description |
|---|---|
| ← | Moves focus to the previous input (in RTL, the next). |
| → | Moves focus to the next input (in RTL, the previous). |
| Ctrl/Cmd + arrow | Moves focus to the first input (previous) or the first empty input (next). |
| ↖ / ↑ | Moves focus to the first input. |
| ↘ / ↓ | Moves focus to the first empty input (the last when all are filled). |
| ⌫ | Clears the focused slot, or the previous slot when it is empty, and moves back. |
| Ctrl/Cmd + ⌫ | Clears all inputs and moves to the first. |
| ⌦ | Clears the focused slot. |
Backspace and Delete have no effect when the control is read-only. Pasted text fills the slots from the focused one.
Examples#
One-Time Password verification#
Use otp and groupSize for a standard 6-digit SMS verification code.
Form integration and validation#
Place PinInput inside form.Field with a validation schema so submission requires every slot to be filled.
Masked PIN for security#
Use mask to hide the entered characters for sensitive passcodes and PINs.
Alphanumeric recovery key#
Use validationType="alphanumeric" to accept letters and digits in backup keys and recovery codes.
Custom separator#
Pass separatorRender to replace the divider between slot groups. It receives the index of the slot it follows.
API Reference#
Attributes#
data-completedata-disableddata-filleddata-focuseddata-invaliddata-readonlydata-requiredProps#
Props for the PinInput component. Renders a <div> element by default.