OTP Field

Preview

Installation

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

Usage

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

<OTPField />

Examples

Alphanumeric

Accept letters and numbers for recovery or backup codes.

Grouped

Split inputs into visual groups with a separator.

Placeholder Hints

Show placeholder characters that hide when the slot is focused.

Custom Sanitization

Restrict input to specific characters with shake animation feedback on invalid input. Uses the bundled useInvalidFeedback hook.

Masked Entry

Obscure entered characters for shared screens.

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, sanitizeValue, and onValueInvalid.

OTPFieldInput

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

No custom props — all Base UI Input props are passed through.

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"
  sanitizeValue={myCustomSanitizer}
  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