Chapter 24: Password Toggle Field (unstable)

Core Idea

A password <input> paired with a built-in visibility-toggle button, handling the fiddly focus-management and security details (auto-hide on submit) that a hand-rolled show/hide password button usually gets wrong.

Key Concepts

• Unstable export: imported as unstable_PasswordToggleField — API may still change.
• Anatomy: Root → Input + Toggle (→ Icon or Slot for the visible/hidden glyph).
• Focus behavior: toggling with a pointer returns focus to Input; toggling with keyboard/virtual navigation keeps focus on the Toggle button itself — deliberately different per input modality.
• Auto-reset after submit: visibility resets to hidden after form submission, so a plaintext password doesn't stay visible on screen after the page state changes.
• Icon vs Slot: Icon takes visible/hidden React nodes directly; Slot is the lower-level primitive, also accepting a render function for full control (e.g. animating between two SVG paths).

Code Examples

<PasswordToggleField.Root>
  <PasswordToggleField.Input />
  <PasswordToggleField.Toggle>
    <PasswordToggleField.Icon visible={<EyeOpenIcon />} hidden={<EyeClosedIcon />} />
  </PasswordToggleField.Toggle>
</PasswordToggleField.Root>

• What it demonstrates: minimal show/hide password field with icon swap.

Key Takeaways

1. Don't hand-roll password-visibility toggles — the focus-return and submit-reset behaviors here are exactly the details that are easy to get wrong (and are UX/security relevant) in a custom implementation.
2. Icon-only Toggle buttons get implicit accessible labeling automatically — no extra aria-label wiring needed for the common case.
3. Reach for Slot + render instead of Icon when you need something beyond a simple two-state icon swap (e.g. an animated path transition).

Connects To

• One-Time Password Field: another unstable_-prefixed form-input primitive from the same family.