useVerificationCode
The cell logic behind VerificationCode, with one input per character backed by a single hidden form field.
Overview
useVerificationCode drives a one-time code field made of single-character cells. Typing fills a cell and moves to the next, Backspace clears and moves back, the arrow keys move between cells, and a paste spreads the code across the cells from the focused one. All cells write to one hidden <input>, so the joined code is what a <form> submits and what native validation checks. The hidden input stays the source of truth through useNativeFieldSync, so form resets and form library writes show up in the cells.
It is built for VerificationCode, and most apps should use that. Use the hook directly only when you need a different layout, for example a separator between groups of cells that the component can't render.
Import
import { useVerificationCode } from '@unflowio/ui/hooks/useVerificationCode';Parameters
| Param | Type | Default | Description |
|---|---|---|---|
length | number | 6 | Number of cells |
value | string | — | Controlled code. Without it, the cells read the hidden input's value |
onBlur | (e: FocusEvent<HTMLInputElement>) => void | — | Called when focus leaves the field, not when it moves between cells |
disabled | boolean | — | Ignores typing, changes and pastes in the cells |
Return value
| Field | Type | Description |
|---|---|---|
refs | RefObject<(HTMLInputElement | null)[]> | Assign each cell input to refs.current[index] |
hiddenRef | RefObject<HTMLInputElement | null> | Ref for the hidden input that holds the joined code |
cells | string[] | One character (or '') per cell |
handleKeyDown | (e, index, pattern?) => void | onKeyDown for each cell |
handleChange | (e, index, pattern?) => void | onChange for each cell. Covers mobile keyboards, IME and autofill that bypass keydown |
handlePaste | (e, pattern?) => void | onPaste for the element wrapping the cells |
handleBlur | (e) => void | onBlur for each cell |
The pattern argument
pattern is a regex for one accepted character, e.g. '[0-9]', and all three handlers read it the same way: a typed key is kept when it matches, and a change or paste keeps only its matching characters. Without it, letters and digits are accepted.
Usage
import { useVerificationCode } from '@unflowio/ui/hooks/useVerificationCode';
const DIGIT = '[0-9]';
export function PinField({ name, length = 6 }: { name: string; length?: number }) {
const { refs, hiddenRef, cells, handleKeyDown, handleChange, handlePaste, handleBlur } =
useVerificationCode({ length });
return (
<div role="group" aria-label="Verification code" onPaste={(e) => handlePaste(e, DIGIT)}>
<input ref={hiddenRef} name={name} required pattern={`.{${length}}`} tabIndex={-1} aria-hidden="true" className="sr-only" />
{cells.map((cell, index) => (
<input
key={index}
ref={(el) => {
refs.current[index] = el;
}}
value={cell}
maxLength={1}
inputMode="numeric"
autoComplete={index === 0 ? 'one-time-code' : 'off'}
aria-label={`Digit ${index + 1} of ${length}`}
onKeyDown={(e) => handleKeyDown(e, index, DIGIT)}
onChange={(e) => handleChange(e, index, DIGIT)}
onBlur={handleBlur}
/>
))}
</div>
);
}Keyboard behavior
| Key | Behavior |
|---|---|
| Accepted character | Fills the cell and moves to the next |
| Other printable character | Ignored |
Backspace | Clears the cell, or the previous cell (and moves there) if this one is empty |
Delete | Clears the cell |
ArrowLeft / ArrowRight | Previous / next cell |
Enter | Submits the surrounding form |
A paste or an autofilled code fills the cells from the focused one with its matching characters, stops at the last cell, and moves focus to the cell after them.
Accessibility
- Wrap the cells in an element with
role="group"and a label, and give each cell its own name (e.g. "Digit 2 of 6"). - Hide the backing input from assistive technology (
aria-hidden,tabIndex={-1}) so it isn't a separate stop. autoComplete="one-time-code"on the first cell lets mobile browsers offer codes received by SMS. The autofilled code arrives throughhandleChange.