PinInput

OTP-style code field — raised cells with a lift-on-focus active state, auto-advance, paste / SMS-autofill distribution, and backspace transfer.

stable
since v0.1.0
2.14 kB
forms
input

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <PinInput length={6} aria-label="One-time code" />;
}

Lengths

Use length to size the OTP field. 4 cells for short PINs, 6 for typical OTPs.

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <PinInput length={4} aria-label="4-digit PIN" defaultValue="1234" />
      <PinInput length={6} aria-label="6-digit OTP" defaultValue="123456" />
    </div>
  );
}

Sizes

Three sizes are available: sm, md (default), and lg.

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <PinInput length={4} size="sm" aria-label="Small" defaultValue="12" />
      <PinInput length={4} size="md" aria-label="Medium" defaultValue="12" />
      <PinInput length={4} size="lg" aria-label="Large" defaultValue="12" />
    </div>
  );
}

Type

Set type to "numeric" (default), "alphanumeric", or "alphabetic" to restrict the accepted characters.

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <PinInput length={4} type="numeric" aria-label="Numeric" defaultValue="1234" />
      <PinInput length={4} type="alphanumeric" aria-label="Alphanumeric" defaultValue="aB7x" />
      <PinInput length={4} type="alphabetic" aria-label="Alphabetic" defaultValue="abcd" />
    </div>
  );
}

Masked

Set mask to render bullets in place of the entered characters, like a password field.

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return <PinInput length={6} mask aria-label="Security code" defaultValue="123456" />;
}

States

Preview

Open

tsx

import { PinInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
      <PinInput length={4} aria-label="Default" defaultValue="12" />
      <PinInput length={4} aria-label="Invalid" defaultValue="12" invalid />
      <PinInput length={4} aria-label="Disabled" defaultValue="1234" disabled />
    </div>
  );
}

API

PropTypeDefaultDescription

length

number

Number of cells to render.

value

string

—

Controlled value (trimmed to `length`).

defaultValue

string

—

Uncontrolled initial value.

onChange

((value: string) => void)

—

Fires on every cell change with the next value.

onComplete

((value: string) => void)

—

Fires once the user has filled all `length` cells.

type

"numeric"|"alphanumeric"|"alphabetic"

"numeric"

Allowed character class. `numeric` enables the numeric mobile keyboard.

mask

boolean

false

Mask the displayed characters (like a password).

size

"sm"|"md"|"lg"

"md"

Control size.

disabled

boolean

false

Disables every cell.

invalid

boolean

—

Renders the invalid state on every cell.

autoFocus

boolean

—

Focuses the first cell on mount.

separator

ReactNode

—

Visual separator rendered at the midpoint of the cells (e.g. a dash for a `123–456` grouping). Omitted by default.

name

string

—

Submitted form field name (renders a hidden input carrying the concatenated value).

string

—

aria-label

string

"Verification code"

Accessible label for the group; individual cells append `digit N`.

className

string

—

style

CSSProperties

—

Accessibility

The cells are wrapped in role="group" with an aria-label (defaults to “Verification code”).
Each cell has aria-label="… digit N"; the first carries autoComplete="one-time-code" so platform autofill works.
Numeric pins set inputMode="numeric" and pattern="[0-9]*" for mobile keyboards.
Arrow Left/Right, Home/End move focus; Backspace deletes and transfers focus to the previous cell.
Pasting a code distributes characters across the remaining cells.

Recipes

Paste a full code into any cell — it’s distributed across the cells (non-matching characters like spaces or dashes are skipped). iOS SMS one-time-code autofill is handled the same way.
Pass separator (e.g. "–") to visually group the cells into halves.
Use onComplete to auto-submit once the user fills all length cells.
Set mask for security codes you don’t want shoulder-surfed.
Pair with a Resend control and a countdown timer for transactional flows.