OTP Field
FreeTake a short one-time code in separate slots, such as six digits sent by email or an authenticator app.
npx wunderui-cli add otp-fieldPlayground
Enter the 4-digit code we sent to your email.
Enter the 4-digit code we sent to your email.
Enter the 4-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Installation
npx wunderui-cli add otp-fieldWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
OtpField,
OtpFieldCode,
OtpFieldInput,
} from "@/components/ui/otp-field"
import type { OtpFieldCodeProps } from "@/components/ui/otp-field"Then use it:
import { Field, FieldDescription } from "@/components/ui/field"
import { Label } from "@/components/ui/label"
import { OtpField, OtpFieldInput } from "@/components/ui/otp-field"
export function VerifyEmail() {
return (
<Field>
<Label htmlFor="code" className="mb-1">
Verification code
</Label>
<OtpField id="code" length={6} onValueComplete={(code) => console.log(code)}>
{Array.from({ length: 6 }, (_, index) => (
<OtpFieldInput key={index} aria-label={`Digit ${index + 1} of 6`} />
))}
</OtpField>
<FieldDescription>Enter the 6-digit code we sent to your email.</FieldDescription>
</Field>
)
}Expected result: You see the label Verification code above six empty boxes. Typing 470921 moves focus from box to box and logs the code, and pasting six digits into the first box fills all six.
When to use
Use OTP Field for
- A one-time code sent by email or SMS, typed once to confirm an address or a phone
- A code from an authenticator app when someone signs in with two steps
- A short PIN of 4 to 8 digits, masked or visible
Use something else for
- Input for a code with dashes, a license key or any value longer than a few characters
- Number Field for a quantity that people step up and down
- Field for the label, message and validation around any control, including this one
Length
Four or six slots are the usual codes, and the number of slots must match the field length. A separator between two groups is just an element between slots; hide it from assistive technology.
Enter the 4-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Characters
The validation type decides what a slot takes and which keyboard a phone shows: digits by default, letters and digits for recovery codes. Masking turns the slots into password inputs for a PIN.
Enter the 6-digit code we sent to your email.
Enter the 6 characters from your recovery sheet.
Enter the 4-digit PIN of your card.
States
Focus is a real state: press Tab or click a slot. Invalid, disabled and read-only are set on the field, while expired, verifying and verified are messages you compose under it.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
This code has expired.
Verifying...
Code verified.
Enter the 6-digit code we sent to your email.
Enter the 6-digit code we sent to your email.
Code input
OtpFieldCode is the field assembled: 4 or 6 boxes of 56 by 64 px in a named group, every digit announced as Digit n of N, and onComplete once the last digit is in. It replaces OtpCodeInput. The field shows no message, so write the text for an invalid code yourself.
That code is not correct. Check it and try again.
Keyboard interactions
The group is one tab stop, with focus on the next empty slot or on the last one when the code is complete. Inside it the keys move between slots.
- TaborShift+Tab
- Moves focus into and out of the group. The slots are not separate tab stops, so one Tab passes the whole code. A disabled field is skipped; a read-only one keeps its place.
- 0-9
- Types a character into the focused slot and moves to the next. A character that the rejects is ignored and reported in .
- Backspace
- Clears the focused slot and moves to the previous one. In an empty slot it clears the previous slot first.
- Delete
- Removes the character of the focused slot. The characters after it move one slot forward.
- Ctrl+BackspaceorCmd+Backspace
- Clears the whole code and puts focus on the first slot.
- ArrowLeftorArrowRight
- Moves focus to the previous or next slot. With Ctrl or Cmd it jumps to the first slot, or to the next empty one.
- HomeorArrowUp
- Moves focus to the first slot.
- EndorArrowDown
- Moves focus to the next empty slot, or to the last slot when the code is complete.
- Ctrl+VorCmd+V
- Pastes into the focused slot and the ones after it. Characters the rejects, and spaces, are dropped; a code that is too long is cut at .
- Enter
- Sends the form that holds the field, like any native input. With the form is sent by itself when the last slot is filled.
Behavior and motion
What the field does with the value, the focus and the label, and what it leaves to the page.
- One value
- The field holds the code as one string, not one value per slot. Control it with a value and change handler, or let a default value keep it.
- Auto-advance
- Typing moves focus to the next slot, Backspace moves it back, and arrow keys, Home and End move it freely. Clicking focuses a slot, and only the active slot is in the tab order.
- Paste and autofill
- A paste spreads over the slots from the focused one, after rejected characters are removed. The first slot offers one-time-code autofill, so a phone can fill the whole code in one step.
- Characters
- The validation type is numeric by default, or alpha, alphanumeric or none, and it sets the phone keyboard and filters typing and pasting. Mask turns the slots into password inputs for a PIN.
- Completion
- The complete handler fires with the code when the last slot is filled, and again when a full code is pasted over a full one. Auto-submit sends the form at that moment.
- Labelling
- The Label names the group and the first slot; slots after the first need your aria-label, or a screen reader calls them unnamed. FieldDescription and FieldError describe the group.
- Invalid
- Inside an invalid Field every slot gets a red border and focus ring, and the fill stays white. The message is yours: write it in a FieldError under the slots, which replaces the helper line.
- Disabled and read-only
- Disabled dims the slots to 40%, takes them out of the tab order and leaves the code out of the form data. Read-only keeps them focusable, blocks typing and paste, and uses the subtle tone.
- Expired, verifying and verified
- No prop covers these states: expired is a read-only field with a warning and a Resend action, pending sets aria-busy with a spinner message, and verified is read-only with a check message.
- Form data
- OtpField renders a hidden input that carries the whole code under the name, with required and form applied to it. The slots have no name, so the code is submitted once.
- Motion
- The border colour of a slot changes quickly on hover and focus. Nothing moves or scales, and typing never animates.
- Reduced motion
- With reduced motion the colour change stays, since it is a short fade and not movement. The spinner in a verifying message stops turning.
Anatomy
OTP Field is a row of single-character slots that behave as one field: typing moves on, Backspace moves back, a paste fills them all. You add the label and the message around it.
Enter the 6-digit code we sent to your email.
- 1
The visible name of the code: a Label whose htmlFor matches the OtpField id. It names the group and the first slot, and a click on it focuses the field.
- 2data-slot="otp-field"
The group of slots: it holds the code as one string, moves focus and reports when the last slot is filled. A hidden input submits the code with the form.
- 3data-slot="otp-field-input"
One slot per character: a native input, 40 px square with an 8 px corner. Only one slot is in the tab order, so give every slot after the first an aria-label such as Digit 2 of 6.
- 4Optional
The 12 px line under the slots: a FieldDescription with the rule, a FieldError with what to do, or a status for an expired, pending or verified code. An error replaces the helper.
- data-slot="otp-field-code"Optional
The ready-made code field: 4 or 6 boxes of 56 by 64 px with an 8 px gap in a named group, every digit announced as Digit n of N. Use it instead of assembling OtpField and OtpFieldInput yourself; it replaces OtpCodeInput.
- Optional
Best practices
- Do
Render one OtpFieldInput per character and set the same number as the length. A six-digit code needs six slots.
- Do
Give the field a visible Label whose htmlFor matches the id, and name every slot after the first with an aria-label such as Digit 2 of 6, so a screen reader announces the position.
- Do
Leave autoComplete at its one-time-code default, so a phone offers the code from the message. The first slot takes the paste and spreads it across the slots.
- Do
Check the code in the complete handler, or turn on auto-submit inside a form. The person should not have to find a button after the last digit.
- Do
Say what to do when a code fails, with a message like That code is not correct, or one for an expired code with a Resend action. Keep what was typed so one digit can be fixed.
- Don’t
Don't change the length while the person is typing, and don't mix code lengths in one field. Render another field instead.
- Don’t
Don't use an OTP Field for a long or free-form value. A long code is hard to check by eye in slots; use an Input.
- Don’t
Don't use real or reused codes in examples, tests or screenshots. Use demo values such as 470921.
API reference
OtpField is the group and takes every attribute of a div plus the props listed. OtpFieldInput is a native input; the group controls its value, type and keys, so those are not slot props. OtpFieldCode is the ready-made field built from the two and takes the props listed under it.
The group of slots: it holds the code as one string, moves focus and reports when the last slot is filled. A hidden input submits the code with the form.
| Prop | Type | Default | Description |
|---|---|---|---|
| length required | number | — | The number of slots, and so the length of the code. Required: the group uses it to cut a paste, detect completion and render the hidden input before the slots mount. Render the same number of . |
| value | string | — | The code, for a controlled field. A string with at most characters; a shorter string leaves the last slots empty. |
| defaultValue | string | — | The code the field starts with, for an uncontrolled field. |
| onValueChange | (value, eventDetails) => void | — | Called with the new code and the reason (, , or ) whenever a character is typed, pasted or removed. |
| onValueComplete | (value, eventDetails) => void | — | Called with the code when the last slot is filled, or when a complete code is pasted over a complete one. It runs after , so check the code here. |
| onValueInvalid | (value, eventDetails) => void | — | Called with the attempted text when typed or pasted characters are rejected by or , before the value changes. Use it to show a hint such as . |
| validationType | "none" | "alpha" | "numeric" | "alphanumeric" | "numeric" | Which characters the slots take: (default), , or . It filters typing and paste and sets the keyboard on a phone. |
| normalizeValue | (value) => string | — | A function that changes the code after the filter, for example . It runs on typed, pasted, controlled and default values. |
| mask | boolean | false | Shows the characters as dots by making the slots password inputs. Use it for a PIN. It does not change what the form submits. |
| autoSubmit | boolean | false | Sends the form around the field when the code is complete, by calling on it. |
| autoComplete | string | "one-time-code" | The of the first slot and the hidden input. Defaults to ; the other slots are always . |
| inputMode | HTMLAttributes<HTMLInputElement>["inputMode"] | — | The virtual keyboard of the slots. The sets a fitting one ( for digits, for letters); set it only to override that. |
| disabled | boolean | false | Dims the field to 40 %, removes it from the tab order and leaves the code out of the form data. |
| readOnly | boolean | false | Keeps the field readable and focusable but blocks typing, paste and Backspace. It is submitted with the form. |
| required | boolean | false | Marks the field as required. The form cannot be sent until every slot is filled. |
| name | string | — | The name under which the whole code is submitted with a form, through the hidden input. |
| form | string | — | The of a form elsewhere in the page that the hidden input belongs to, for a field that sits outside its form. |
| id | string | — | The of the first slot; the others get , and so on. Use it as the of the label. |
One slot per character: a native input, 40 px square with an 8 px corner. Only one slot is in the tab order, so give every slot after the first an aria-label such as Digit 2 of 6.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes on the slot, for example a different size. The default is 40 px square. |
The ready-made code field: 4 or 6 boxes of 56 by 64 px with an 8 px gap in a named group, every digit announced as Digit n of N. Use it instead of assembling OtpField and OtpFieldInput yourself; it replaces OtpCodeInput.
| Prop | Type | Default | Description |
|---|---|---|---|
| length | 4 | 6 | 6 | The number of boxes, 4 or 6. 6 by default. |
| value | string | — | The code, for a controlled field. A string of at most digits. |
| onValueChange | (value) => void | — | Called with the code whenever a digit is typed, pasted or removed. |
| onComplete | (value) => void | — | Called with the code once the last box is filled. Check the code here. |
| invalid | boolean | — | Marks every box invalid: a red border and . The field shows no message, so write the text yourself. |
| disabled | boolean | — | Dims the boxes to 40 % and takes them out of the tab order. |
| autoFocus | boolean | — | Focuses the first box on mount. |
| aria-label | string | — | Names the group for a screen reader. Each box is announced as Digit n of N. "One-time code" by default. |
| className | string | — | Extra classes on the group, for example so the boxes centre in a narrow column. |
| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string | — | Names the group for screen readers; each digit is announced as "Digit n of N". |
| autoFocus | boolean | — | |
| disabled | boolean | — | |
| invalid | boolean | — | |
| length | 4 | 6 | — | |
| onComplete | (value) => void | — | |
| onValueChange | (value) => void | — | |
| value | string | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("otp-field")npx wunderui-cli add otp-fieldThe full library index for assistants is at /llms.txt.