OTP Field

An OTP field splits a one-time passcode across individual character slots, with paste and auto-advance handled for you. Use it for two-factor codes, email verification, or recovery codes.

Preview

Installation

npx shadcn@latest add @cubby-ui/otp-field

Usage

import {
  OTPField,
  OTPFieldInput,
} from "@/components/ui/cubby-ui/otp-field";

<OTPField />

Composition

OTPField
└── OTPFieldGroup
    ├── OTPFieldInput
    └── OTPFieldSeparator

Examples

Alphanumeric

Set validationType="alphanumeric" to accept letters and numbers for recovery or backup codes.

Grouped

Wrap inputs in OTPFieldGroup and place an OTPFieldSeparator between groups.

Placeholder Hints

Set placeholder on each OTPFieldInput to show a hint that hides when the slot is focused.

Custom Sanitization

Restrict input to specific characters, with shake feedback on invalid input via the bundled useInvalidFeedback hook.

Masked Entry

Set mask on OTPField to obscure entered characters for shared screens.

Elevated Variant

On a Card, Dialog, or popover surface, the opaque default slots collapse into the parent. Use variant="elevated" on each OTPFieldInput for a translucent overlay that adapts to the substrate. See the Surfaces docs.

Form Integration

Use Field for labeling and form participation. See the Forms guide for more patterns.

API Reference

The OTP Field is built on top of Base UI's OTP Field. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI OTP Field documentation.

Props

OTPField

Groups all OTP field parts and manages their state. Wraps Base UI's OTPField.Root. Renders a <div>.

No custom props. All Base UI Root props are passed through, including length, value, onValueChange, validationType, mask, normalizeValue, and onValueInvalid.

OTPFieldInput

Individual character input slot. Wraps Base UI's OTPField.Input. Renders an <input>.

OTPFieldSeparator

Visual separator between input groups. Wraps Base UI's Separator. Renders a <div>.

OTPFieldGroup

Layout wrapper for grouping inputs together. Not a Base UI component; renders a plain <div> with display: flex and gap.

Hooks

useInvalidFeedback

function useInvalidFeedback(options?: UseInvalidFeedbackOptions): UseInvalidFeedbackReturn;

Manages shake animation and screen reader feedback for invalid OTP input. Bundled with the component, installed automatically when you install otp-field.

Wire its handlers to OTPField and its className getter to each OTPFieldInput:

import { useInvalidFeedback } from "@/components/ui/cubby-ui/otp-field/hooks/use-invalid-feedback";
 
const invalidFeedback = useInvalidFeedback();
 
<OTPField
  length={6}
  validationType="none"
  normalizeValue={myCustomNormalizer}
  onValueChange={invalidFeedback.handleValueChange}
  onValueInvalid={invalidFeedback.handleValueInvalid}
>
  {Array.from({ length: 6 }, (_, index) => (
    <OTPFieldInput
      key={index}
      className={invalidFeedback.getInvalidClassName(index)}
      onFocus={() => invalidFeedback.setFocusedIndex(index)}
    />
  ))}
</OTPField>
<span aria-live="polite" className="sr-only">
  {invalidFeedback.statusMessage}
</span>

Options

Returns