OTP Field

When to Use

Use OTPField for a short verification code that is entered one character at a time and may be pasted from a message. Use PasswordToggleField for a reusable secret chosen by the person, and Input when the value belongs in one normal text box instead of visually separated cells.

Features

The behavior Atom owns before your product adds appearance.

• Controlled and uncontrolled full value.
• Coordinates rendered input cells and assigns indexes from their render order.
• Optional explicit input indexes.
• Roving tab stop so the field behaves as one logical control.
• Paste distribution across cells.
• Arrow, Backspace, Delete, Home, and End navigation.
• Numeric, alphabetic, alphanumeric, or custom pattern filtering.
• Hidden input for native form submission.
• Optional masking, completion callback, auto-focus, and form submission.

Import

import { OTPField } from "@flowstack-ui/atom";

Anatomy

<OTPField.Root>
  <OTPField.Input />
  <OTPField.Separator />
  <OTPField.Input />
</OTPField.Root>

API Reference

Root

Owns the complete code value, filtering, cell registration, focus movement, Field state, completion behavior, and optional hidden form input.

Input

Renders one visible character cell, joins the roving tab stop, and delegates typing, paste, deletion, and focus movement to Root.

Separator

Decorative separator between cells.

The package exports useOTPFieldContext and its provider for advanced compound parts. It also exports getOTPFieldPattern, isOTPFieldCharAccepted, getOTPFieldChars, filterOTPFieldValue, and getOTPFieldDisplayChar for using the same filtering and display rules outside the rendered field.

Examples

Six Digit Code

import { OTPField } from "@flowstack-ui/atom";

export function VerificationCode() {
  return (
    <OTPField.Root name="code" length={6}>
      {Array.from({ length: 6 }, (_, index) => (
        <OTPField.Input key={index} />
      ))}
    </OTPField.Root>
  );
}

Grouped Code

import { OTPField } from "@flowstack-ui/atom";

export function GroupedCode() {
  return (
    <OTPField.Root length={6} onComplete={(code) => console.log(code)}>
      <OTPField.Input />
      <OTPField.Input />
      <OTPField.Input />
      <OTPField.Separator>-</OTPField.Separator>
      <OTPField.Input />
      <OTPField.Input />
      <OTPField.Input />
    </OTPField.Root>
  );
}

Accessibility

The first visible cell owns required validity and aria-required for the logical OTP value; the combined named input remains submission-only. A validation attempt is mirrored across Root and every cell. Inline behavior suppresses the browser bubble.

The root uses role="group" and the visible inputs use roving tabIndex, so Tab enters the OTP field once. Each input receives a generated position label, and the separator is hidden from assistive technology. The group does not carry aria-required, because that attribute is unsupported on role="group". Give the group a clear label through native aria-label/aria-labelledby or Field. The first visible cell owns required validity and anchors native browser feedback. The combined hidden native input is submission-only; uncontrolled content resets to defaultValue.

Use getInputLabel to localize every generated cell position label. A direct aria-label on an Input still overrides the generated label for that cell.

Changelog

Unreleased

0.24.0

• Added public Agent Knowledge for component selection, required composition, recurring mistakes, and validation.

0.19.2

• Removed unsupported aria-required from the role="group" root while preserving required semantics and native validity on the visible cells.

0.19.0

• Added getInputLabel for localizing generated cell position labels.

0.6.16

• Explicitly scrolled inline validation-directed focus into view.

0.6.15

• Exposed inline validation-directed focus through [data-focus-visible] until blur.

0.6.13

• Added logical-field inline/native validation presentation and synchronized invalid state across Root, visible cells, Field, and Form.

0.6.12

• Moved required validity to the first visible cell and made the combined named value submission-only.

0.5.0

• Removed ariaLabel/ariaDescribedBy in favor of native ARIA and added a required-capable native combined-value input with uncontrolled reset.

0.1.0

• Initial Atom release.