How to build an accessible Swap in React

Renders a <button role="switch"> with aria-checked reflecting state. Both on/off slots are aria-hidden so screen readers announce the button state, not the icon content.

When to use a Swap

• Theme toggles where an icon animates between two states (sun/moon)
• Favorite or bookmark toggles that flip between outlined and filled icons
• Any scenario where exactly two icons swap places with a transition

When not to use it

• Form toggles with a visible label — use Toggle
• Checkbox-style inputs that are part of a submitted form — use Checkbox
• When a text label must always be visible alongside the control

Keyboard interactions

Role switch, verified at WCAG 2.2-AA.

• Space
• Enter

Common mistakes

Avoid: <Swap on="Enable" off="Disable" /> (text content)

Prefer: <Toggle label="Enable notifications" />

Swap is designed for icon transitions; for labeled on/off controls use Toggle

Example

<Swap on={<SunIcon />} off={<MoonIcon />} mode="rotate" aria-label="Toggle theme" />

See the full Swap reference →