OTP Field

A row of single-character boxes for entering one-time codes.

Usage

import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

<OTPField length={6} aria-label="Verification code">
  {Array.from({ length: 6 }, (_, i) => (
    <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of 6`} />
  ))}
</OTPField>

OTPField is a compound component for one-time codes. The root owns the value and length; you render one OTPFieldInput per slot (commonly mapped over length). Typing fills slots left to right and auto-advances, Backspace moves back, pasting a full code distributes across the slots, and onValueComplete fires when every slot is filled.

Give the group an accessible name with aria-label (or aria-labelledby) and label each slot — the inputs aren't tied to a single <label> the way a plain field is.

Examples

Variants

variant on the root switches every slot between a bordered outline (default) and a filled soft field.

import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldVariants() {
  return (
    <div className="flex flex-col gap-5">
      <OTPField length={LENGTH} variant="outline" aria-label="Outline code">
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
      <OTPField length={LENGTH} variant="soft" aria-label="Soft code">
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
    </div>
  )
}

Sizes

size on the root scales all slots together — sm, md (default), or lg.

import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 4

function Field({ size, label }: { size: 'sm' | 'md' | 'lg'; label: string }) {
  return (
    <OTPField length={LENGTH} size={size} aria-label={label}>
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}

export default function OTPFieldSizes() {
  return (
    <div className="flex flex-col items-center gap-5">
      <Field size="sm" label="Small code" />
      <Field size="md" label="Medium code" />
      <Field size="lg" label="Large code" />
    </div>
  )
}

With a separator

Drop an OTPFieldSeparator between slots to break a long code into groups. It renders a dash by default; pass children to customise it.

import { OTPField, OTPFieldInput, OTPFieldSeparator } from '@appica/ui-react/otp-field'

export default function OTPFieldWithSeparator() {
  return (
    <OTPField length={6} aria-label="Verification code">
      <OTPFieldInput aria-label="Digit 1 of 6" />
      <OTPFieldInput aria-label="Digit 2 of 6" />
      <OTPFieldInput aria-label="Digit 3 of 6" />
      <OTPFieldSeparator />
      <OTPFieldInput aria-label="Digit 4 of 6" />
      <OTPFieldInput aria-label="Digit 5 of 6" />
      <OTPFieldInput aria-label="Digit 6 of 6" />
    </OTPField>
  )
}

Placeholder

Give each OTPFieldInput a placeholder to hint at empty slots — a single • is a common choice. It shows only while a slot is empty and unfocused.

import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldPlaceholder() {
  return (
    <OTPField length={LENGTH} aria-label="Verification code">
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} placeholder="•" aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}

Masked

Set mask to obscure the entered characters — useful when the code is sensitive and shouldn't be shown on screen.

import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

export default function OTPFieldMask() {
  return (
    <OTPField length={LENGTH} mask defaultValue="135790" aria-label="Masked code">
      {Array.from({ length: LENGTH }, (_, i) => (
        <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
      ))}
    </OTPField>
  )
}

Controlled & verify on complete

Drive the value with value + onValueChange, and use onValueComplete to act once all slots are filled — typically to verify or submit the code.

Enter the 6-digit code (123456)

'use client'

import { useState } from 'react'
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6
const CODE = '123456'

export default function OTPFieldControlled() {
  const [value, setValue] = useState('')
  const [status, setStatus] = useState<'idle' | 'valid' | 'invalid'>('idle')

  return (
    <div className="flex flex-col items-center gap-3">
      <OTPField
        length={LENGTH}
        value={value}
        onValueChange={(next) => {
          setValue(next)
          setStatus('idle')
        }}
        onValueComplete={(next) => setStatus(next === CODE ? 'valid' : 'invalid')}
        aria-label="Verification code"
      >
        {Array.from({ length: LENGTH }, (_, i) => (
          <OTPFieldInput key={i} aria-label={`Digit ${i + 1} of ${LENGTH}`} />
        ))}
      </OTPField>
      <p className="text-foreground-muted text-sm" aria-live="polite">
        {status === 'valid'
          ? '✓ Code verified'
          : status === 'invalid'
            ? `✗ Incorrect code (try ${CODE})`
            : `Enter the 6-digit code (${CODE})`}
      </p>
    </div>
  )
}

Disabled, read-only & error states

disabled greys out every slot and blocks interaction; readOnly keeps the code visible and focusable but not editable. For the error state, place the field in a Field marked invalid — data-invalid propagates to every slot (OTP derives its invalid state from Field context, not a standalone aria-invalid).

import { Field } from '@appica/ui-react/field'
import { OTPField, OTPFieldInput } from '@appica/ui-react/otp-field'

const LENGTH = 6

const slots = (prefix: string) =>
  Array.from({ length: LENGTH }, (_, i) => (
    <OTPFieldInput key={i} aria-label={`${prefix} digit ${i + 1} of ${LENGTH}`} />
  ))

export default function OTPFieldStates() {
  return (
    <div className="flex flex-col gap-5">
      <OTPField length={LENGTH} disabled aria-label="Disabled code">
        {slots('Disabled')}
      </OTPField>
      <OTPField length={LENGTH} readOnly defaultValue="123456" aria-label="Read-only code">
        {slots('Read-only')}
      </OTPField>
      <Field invalid>
        <OTPField length={LENGTH} defaultValue="123456" aria-label="Code with error">
          {slots('Error')}
        </OTPField>
      </Field>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The slots lay out from the right and focus advances start-to-end following the resolved direction. For setup details and caveats, see the RTL guide.

رمز التحقق

API reference

OTPField wraps Base UI's OTP Field. Each part forwards its remaining props to the matching Base UI primitive — the tables below list the Appica additions and the most common props.

OTPField

The root. Owns the value and the shared variant / size (cascaded to every slot); renders a <div>.

Prop	Type	Default	Description
`length`	`number`	—	Required. Number of input slots.
`variant`	`'outline' \| 'soft'`	`'outline'`	Slot appearance — bordered or filled.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Scales every slot.
`value`	`string`	—	Controlled value. Pair with `onValueChange`.
`defaultValue`	`string`	—	Uncontrolled initial value.
`onValueChange`	`(value: string, details) => void`	—	Fires whenever the value changes (typing, paste, clear).
`onValueComplete`	`(value: string, details) => void`	—	Fires once every slot is filled.
`validationType`	`'numeric' \| 'alpha' \| 'alphanumeric' \| 'none'`	`'numeric'`	Which characters the slots accept.
`mask`	`boolean`	`false`	Obscure the entered characters.
`autoSubmit`	`boolean`	`false`	Submit the owning form when the code completes.
`autoComplete`	`string`	`'one-time-code'`	Applied to the first slot and hidden input for OS autofill.
`name`	`string`	—	Field name submitted with a form.
`required`	`boolean`	`false`	A complete value is required before the form submits.
`disabled`	`boolean`	`false`	Disables every slot.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the root element, or compose it with another component.
`className`	`string \| ((state) => string)`	—	Extra classes on the root, merged via `tailwind-merge`.

OTPFieldInput

One slot. Inherits variant / size from the root via context; renders an <input>.

Prop	Type	Default	Description
`className`	`string`	—	Extra classes on the slot, merged via `tailwind-merge`.

Also forwards every native <input> prop (aria-label, ref, …). It exposes data-* state attributes (data-disabled, data-complete, data-filled, …) for styling.

OTPFieldSeparator

A divider between slot groups. Renders a dash by default.

Prop	Type	Default	Description
`children`	`ReactNode`	dash	Replace the default dash mark with custom content.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

Each slot is a native <input> (role="textbox"). Give every slot an aria-label (e.g. Digit 1 of 6) and name the whole group with aria-label or aria-labelledby.
Typing fills slots left to right and auto-advances; Backspace clears and moves back; ←/→ move between slots; pasting a full code distributes it across the slots.
autoComplete="one-time-code" lets the OS offer codes from SMS for autofill.
mask obscures the characters for sensitive codes.
disabled removes the slots from the tab order and exposes data-disabled for styling.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback