Chapter 23: One-Time Password Field (unstable)

Core Idea

A group of single-character inputs that behave like one cohesive field for OTP/verification-code entry — handles keyboard navigation between characters, paste-to-fill, password-manager autofill, and exposes a single combined value via a hidden input.

Key Concepts

• Unstable export: imported as unstable_OneTimePasswordField — API may still change.
• Anatomy: Root (one per field, holds the combined value) → one Input per character position → one HiddenInput (submits the full value as a single form field).
• validationType (default "numeric"): restricts input to numeric or alphanumeric characters per position.
• autoSubmit/onAutoSubmit: fires automatically once every position is filled — the standard "submit as soon as the code is complete" UX.
• [data-index]: on each Input, its position within the value — useful for custom per-position styling.
• Segmented layout: Root accepts arbitrary children (e.g. a Separator between groups of inputs) since decorative children don't interfere with the group role semantics — just mark them aria-hidden.

Code Examples

// 6-character code: one Input per character, plus one HiddenInput for form submission
<OneTimePasswordField.Root autoSubmit onAutoSubmit={verifyCode}>
  <OneTimePasswordField.Input />
  <OneTimePasswordField.Input />
  <OneTimePasswordField.Input />
  <OneTimePasswordField.Input />
  <OneTimePasswordField.Input />
  <OneTimePasswordField.Input />
  <OneTimePasswordField.HiddenInput />
</OneTimePasswordField.Root>

• What it demonstrates: minimal 6-digit OTP field with auto-submit on completion.

Key Takeaways

1. Render exactly one Input per expected character — the number of Input children defines the code length.
2. Always include HiddenInput for plain <form> submission compatibility — Inputs themselves don't carry the combined value into FormData.
3. Treat this as unstable_ — pin versions carefully if relying on its exact prop API in production.

Connects To

• Password Toggle Field: another form-input-focused primitive, for show/hide password UX instead of segmented code entry.