OTP Field

A one-time-password field — a row of character slots that owns focus movement, paste, and completion.

Show code

import { OTPField } from "@makeplane/propel/components/otp-field";

export default function BasicDemo() {
  return <OTPField length={6} size="lg" aria-label="Verification code" />;
}

Installation

import { OTPField } from "@makeplane/propel/components/otp-field";

Usage

import { OTPField } from "@makeplane/propel/components/otp-field";

export default function BasicDemo() {
  return <OTPField length={6} size="lg" aria-label="Verification code" />;
}

Examples

Sizes

size sets the box size of every slot — lg, xl, and 2xl.

Show code

import { OTPField, type OTPFieldInputSize } from "@makeplane/propel/components/otp-field";

const SIZES: OTPFieldInputSize[] = ["lg", "xl", "2xl"];

export default function SizesDemo() {
  return (
    <div className="flex flex-col items-start gap-4">
      {SIZES.map((size) => (
        <OTPField
          key={size}
          length={6}
          size={size}
          defaultValue="123456"
          aria-label="Verification code"
        />
      ))}
    </div>
  );
}

Grouped

groups splits the run with separators — [3, 3] renders the 123-456 shape. The counts must sum to length.

Show code

import { OTPField } from "@makeplane/propel/components/otp-field";

export default function GroupedDemo() {
  return <OTPField length={6} size="lg" groups={[3, 3]} aria-label="Verification code" />;
}

Hint

hint shows helper text below the slots, e.g. a resend countdown. It’s replaced by error when set.

Resend OTP in 15 seconds

Show code

import { OTPField } from "@makeplane/propel/components/otp-field";

export default function HintDemo() {
  return (
    <OTPField length={6} size="lg" hint="Resend OTP in 15 seconds" aria-label="Verification code" />
  );
}

Invalid

Passing error shows the message and flips every slot to the danger state.

Code is invalid

Show code

import { OTPField } from "@makeplane/propel/components/otp-field";

export default function InvalidDemo() {
  return (
    <OTPField
      length={6}
      size="lg"
      defaultValue="12"
      error="Code is invalid"
      aria-label="Verification code"
    />
  );
}

Controlled

normalizeValue rewrites accepted characters while rejected ones surface through onValueInvalid, fed back as an error until the next valid keystroke clears it.

Show code

import { OTPField } from "@makeplane/propel/components/otp-field";
import * as React from "react";

export default function ControlledDemo() {
  const [error, setError] = React.useState<React.ReactNode>(null);
  return (
    <OTPField
      length={6}
      size="lg"
      validationType="alphanumeric"
      normalizeValue={(value) => value.toUpperCase()}
      onValueChange={() => setError(null)}
      onValueInvalid={() => setError("Only letters and numbers are allowed")}
      error={error}
      aria-label="Recovery code"
    />
  );
}

API Reference

OTPField

The ready-made one-time-password / verification-code field: a row of `length` character slots. Drive it with `value`/`defaultValue` + `onValueChange`; the root owns focus movement, paste, and completion across the slots. Pass `mask` to obscure entered characters, `size` to set the box size, `hint` for helper text below the slots (e.g. a resend countdown), and `error` to show an error message instead — `Field.Root invalid` then propagates `data-invalid` to every slot, which recolors its border (and focus ring) to danger off that state. Grafts Base UI `OTPField` behavior onto the `elements/otp-field` styled parts (`OTPField` root + `OTPFieldInput`). Each slot resolves its index from the root context, so the ready-made simply renders one per slot; `groups` splits the run with separators (e.g. `groups={[3, 3]}` renders `123-456`).

Prop	Type	Default	Description
size(required)	"lg" \| "xl" \| "2xl"	—	Box size passed to every slot.
render	ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, OTPFieldRootState>	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
hint	ReactNode	—	Helper text shown below the slots, e.g. a resend countdown. Replaced by `error` when set.
error	ReactNode	—	Error text shown below the slots; its presence flips every slot to the danger state.
groups	readonly number[]	—	Slot counts per visual group, separated by an `OTPFieldSeparator` (e.g. `[3, 3]` renders `123-456`). The counts must sum to `length`; omit for one flat run of slots.