OTP field

A one-time code typed one character per cell. A paste fills every cell, and one hidden input carries the code to the form.

client - size not measured yet

OTP field

client - size not measured yet

A one-time code typed one character per cell. A paste fills every cell, and one hidden input carries the code to the form.

Install

Try it

length

size

invalid

groupSize

The code

otp-field.tsx

import { OTPField } from 'topclassui/otp-field'

<div className="grid justify-items-start gap-2">
  <label htmlFor="otp-playground-code" className="text-sm text-body">Verification code</label>
  <OTPField id="otp-playground-code" />
</div>

The export is OTPField. In a form the hidden input sends what is typed so far, a partial code too.

Every state

6 states

Invalid

Disabled

Read-only

Import from the package

topclassui/otp-field

import { OtpField } from 'topclassui/otp-field'

Install once:npm i topclassui@beta zod

Examples

length is 6 by default, clamped to a whole number from 1 to 12. groupSize draws a bar after every that many cells.
Digits are the default: ASCII, Arabic-Indic and Persian digits are taken and stored as ASCII, and spaces in a paste are dropped.
Past eight items, cells and bars together, the row breaks at whole cells, so twelve cells stay 44px tall on a phone.
Each cell is a square of the control scale, 40px at md, and gives up width before height. Six cells need 184px.
A Field's control object spreads onto it as it is.

basic

Verification code

Six digits from your authenticator app

basic.tsx

import { OTPField } from 'topclassui/otp-field'

/** Outside a Field: a native label points at the id of the field, which is the first cell, and a hint describes it. */
export default function Demo() {
  return (
    <div className="grid justify-items-start gap-2">
      <label htmlFor="otp-basic-code" className="text-sm text-body">Verification code</label>
      <OTPField id="otp-basic-code" aria-describedby="otp-basic-hint" />
      <p id="otp-basic-hint" className="text-sm text-muted">Six digits from your authenticator app</p>
    </div>
  )
}

grouped

Verification code

grouped.tsx

import { OTPField } from 'topclassui/otp-field'

/** Six cells in two groups of three, with a bar between them that a screen reader does not read. */
export default function Demo() {
  return (
    <div className="grid justify-items-start gap-2">
      <label htmlFor="otp-grouped-code" className="text-sm text-body">Verification code</label>
      <OTPField id="otp-grouped-code" groupSize={3} />
    </div>
  )
}

form

form.tsx

import { Button } from 'topclassui/button'
import { OTPField } from 'topclassui/otp-field'

/** In a plain form: it sends code= before anything is typed, and what is typed so far after, a partial code too. */
export default function Demo() {
  return (
    <form className="grid justify-items-start gap-3">
      <label htmlFor="otp-form-code" className="text-sm text-body">Verification code</label>
      <OTPField id="otp-form-code" name="code" />
      <Button type="submit">Verify</Button>
    </form>
  )
}

sizes

Extra small

Small

Medium

Large

Extra large

sizes.tsx

import { OTPField } from 'topclassui/otp-field'

/** The five sizes, each named by the text above it. A cell gives up width before it gives up height. */
export default function Demo() {
  return (
    <div className="grid justify-items-start gap-3">
      <span id="otp-sizes-xs" className="text-sm text-body">Extra small</span>
      <OTPField size="xs" aria-labelledby="otp-sizes-xs" defaultValue="482" />
      <span id="otp-sizes-sm" className="text-sm text-body">Small</span>
      <OTPField size="sm" aria-labelledby="otp-sizes-sm" defaultValue="482" />
      <span id="otp-sizes-md" className="text-sm text-body">Medium</span>
      <OTPField size="md" aria-labelledby="otp-sizes-md" defaultValue="482" />
      <span id="otp-sizes-lg" className="text-sm text-body">Large</span>
      <OTPField size="lg" aria-labelledby="otp-sizes-lg" defaultValue="482" />
      <span id="otp-sizes-xl" className="text-sm text-body">Extra large</span>
      <OTPField size="xl" aria-labelledby="otp-sizes-xl" defaultValue="482" />
    </div>
  )
}

long

Recovery code

long.tsx

import { OTPField } from 'topclassui/otp-field'

/** Twelve cells, the most a field takes. Past eight items the row wraps, so on a phone every cell keeps 44 px. */
export default function Demo() {
  return (
    <div className="grid justify-items-start gap-2">
      <label htmlFor="otp-long-code" className="text-sm text-body">Recovery code</label>
      <OTPField id="otp-long-code" length={12} validationType="alphanumeric" />
    </div>
  )
}

In Arabic, right to left

رمز التحقق

rtl.tsx

import { TopClassProvider } from 'topclassui/provider'
import { OTPField } from 'topclassui/otp-field'

/** Arabic, inside TopClassProvider as the root layout would mount it. The group sits at the right, under its label,
 * and its cells still run left to right, as the code reads. */
export default function Demo() {
  return (
    <TopClassProvider direction="rtl" locale="ar">
      <div dir="rtl" lang="ar">
        <label htmlFor="otp-rtl-code" className="block text-sm text-body">رمز التحقق</label>
        <OTPField id="otp-rtl-code" name="code" className="mt-2" />
      </div>
    </TopClassProvider>
  )
}

Props

The props of OtpField
Prop	Type	Default	Limits	Description
`aria-labelledby`	`string`	-	-	The id of the visible text that names the first cell.
`id`	`string`	-	-	The id of the first cell, which a `<label htmlFor>` points at; the others are `<id>-2`, `<id>-3`.
`aria-describedby`	`string`	-	-	On the first cell, beside its name: the id of a hint or an error text.
`aria-invalid`	`boolean \| 'true' \| 'false' \| 'grammar' \| 'spe...`	-	-	On every cell; `invalid` sets it to true, and when `invalid` is off a Field's own value survives.
`aria-label`	`undefined`	-	-	Refused: Base UI drops it on the first cell. Name the field by `id` or `aria-labelledby`.
`className`	`string`	-	-	Merged last, so a consumer class wins a conflict with the group's own.
`groupSize`	`integer`, min 0, max 12	`0`	min 0, max 12	Draws a separator after every this many cells; 0 draws none. Clamped between 0 and length.
`invalid`	`boolean`	`false`	-	Marks the code as wrong: sets aria-invalid on every cell, whose line turns to danger and thickens.
`length`	`integer`, min 1, max 12	`6`	min 1, max 12	The number of cells, one character each. Clamped between 1 and 12; past eight items the row wraps.
`ref`	`Ref<HTMLDivElement>`	-	-	The `<div role="group">` around the cells.
`size`	`xs` \| `sm` \| `md` \| `lg` \| `xl` \| `custom`	`"md"`	-	The control scale of each square cell and its type step; custom emits no size classes.

Keyboard and accessibility

The keyboard of OtpField
Keys	What it does
`Tab`	Enters the field: the group is one tab stop.
`0-9`	Fills the cell and moves to the next one; a paste fills every cell from the focused one.
`Backspace`	Clears the cell and moves back.
`ArrowLeftArrowRight`	Move to the cell before or after, up to the first empty cell.
`HomeEnd`	Move to the first or the last cell the focus can reach.

Name it with id (for a <label htmlFor>) or aria-labelledby; the name lands on the first cell. aria-label is refused.
Every later cell is named by its place, "Character 2 of 6", in the provider's language. aria-describedby goes on the first cell.
invalid sets aria-invalid on every cell, never on the group: each line turns to danger and thickens.

Right to left

A code reads left to right, so on an Arabic page the cells still run left to right; the group sits at the inline start, beside its label.

Server and client

A client component: it renders on the server and hydrates in the browser.

Files: index.tsx, client.tsx.

On the chip: client - size not measured yet.