Loading…

OTP Input

beta

A one-time-code field drawn as a row of animated slots, with a caret that slides between them and success and error verdicts — paste, SMS autofill, masking and grouping included.

Forms
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add otp-input

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { OtpInput } from "@/components/ui/otp-input";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
In Form
Options
Status
Status States

API

Generated from the component's own types, so a prop cannot appear here without existing.

<OtpInput>

Prop	Type	Default
`allow` Characters accepted; anything else typed or pasted is dropped.	`OtpInputAllow`	`"numeric"`
`defaultValue` Initial value when uncontrolled.	`string`	`""`
`entrance` How a character arrives in its slot: `flip` turns it in, `roll` rolls it up from below.	`"flip" \| "roll"`	`"flip"`
`groups` Slot counts per group, e.g. `[3, 3]`. A separator is drawn between groups.	`number[]`	—
`length` Number of characters in the code.	`number`	`6`
`mask` Paints each filled slot with a dot, or the given character, instead of its value.	`boolean \| string`	`false`
`onComplete` Called once each time the last slot is filled.	`(value: string) => void`	—
`onValueChange` Called with the sanitised code whenever it changes.	`(value: string) => void`	—
`separator` Drawn between groups. Decorative.	`ReactNode`	—
`slotClassName` Classes for each painted slot.	`string`	—
`slotSize`	`"sm" \| "md" \| "lg" \| "xl"`	`"md"`
`status` The verdict on the code. "success" traces a ring around each slot in turn; "error" rings them red, shakes the row once and sets aria-invalid.	`OtpInputStatus`	`"idle"`
`statusMessage` Announced politely while `status` is "success" or "error" — "Code verified", "That code is wrong". Visible error text belongs in FormMessage.	`string`	—
`value` Controlled value.	`string`	—

Plus every attribute of <input> except value, defaultValue, onChange, type, maxLength, size, children.

Accessibility

One real text input with autocomplete="one-time-code" and a numeric inputmode sits over the slots, so paste, SMS autofill, password managers and screen readers all meet a single labelled field holding the code; the painted slots and the caret are aria-hidden. Every prop except className lands on that input, so FormField's id, aria-describedby and aria-invalid wire up through FormControl. It is named "One-time code" only when given no aria-label, aria-labelledby or id. Arrow keys, Home and End move between slots; typing over a filled slot replaces it. `status="error"` sets aria-invalid (an explicit aria-invalid wins), and `statusMessage`, when given, is announced through a polite live region once there is a verdict; colour is never the only signal, since the error also shakes the row and the message says what happened. The slots stay left-to-right in RTL, as codes are read. Slot, character, caret and verdict motion is decoration and stops under reduced motion, leaving the caret visible and the verdict rings drawn.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

allow

Characters accepted; anything else typed or pasted is dropped.

OtpInputAllow

"numeric"

defaultValue

Initial value when uncontrolled.

string

""

entrance

How a character arrives in its slot: flip turns it in, roll rolls it up from below.

"flip" | "roll"

"flip"

groups

Slot counts per group, e.g. [3, 3]. A separator is drawn between groups.

number[]

—

length

Number of characters in the code.

number

6

mask

Paints each filled slot with a dot, or the given character, instead of its value.

boolean | string

false

onComplete

Called once each time the last slot is filled.

(value: string) => void

—

onValueChange

Called with the sanitised code whenever it changes.

(value: string) => void

—

separator

Drawn between groups. Decorative.

ReactNode

—

slotClassName

Classes for each painted slot.

string

—

slotSize

"sm" | "md" | "lg" | "xl"

"md"

status

The verdict on the code. "success" traces a ring around each slot in turn; "error" rings them red, shakes the row once and sets aria-invalid.

OtpInputStatus

"idle"

statusMessage

Announced politely while status is "success" or "error" — "Code verified", "That code is wrong". Visible error text belongs in FormMessage.

string

—

value

Controlled value.

string

—