UnflowUI
ComponentsHooks

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

ParamTypeDefaultDescription
lengthnumber6Number of cells
valuestring—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
disabledboolean—Ignores typing, changes and pastes in the cells

Return value

FieldTypeDescription
refsRefObject<(HTMLInputElement | null)[]>Assign each cell input to refs.current[index]
hiddenRefRefObject<HTMLInputElement | null>Ref for the hidden input that holds the joined code
cellsstring[]One character (or '') per cell
handleKeyDown(e, index, pattern?) => voidonKeyDown for each cell
handleChange(e, index, pattern?) => voidonChange for each cell. Covers mobile keyboards, IME and autofill that bypass keydown
handlePaste(e, pattern?) => voidonPaste for the element wrapping the cells
handleBlur(e) => voidonBlur 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

KeyBehavior
Accepted characterFills the cell and moves to the next
Other printable characterIgnored
BackspaceClears the cell, or the previous cell (and moves there) if this one is empty
DeleteClears the cell
ArrowLeft / ArrowRightPrevious / next cell
EnterSubmits 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 through handleChange.