Swap
Animated toggle between two icon/content states with rotate or flip transition
Category: inputs · WCAG 2.2-AA · toggle, icon, animate, switch, flip, rotate
Variants
- rotate
- flip
States
- unchecked
- checked
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Alias of `ariaLabel` — the same invisible accessible name under the other spelling. Neither is deprecated. |
ariaLabel | string | — | Invisible accessible name. The catalog convention; `aria-label` is accepted as an alias for the DOM spelling. |
on | React.ReactNode | — | Content shown in the active (on) state. |
off | React.ReactNode | — | Content shown in the inactive (off) state. |
checked | boolean | false | Whether the control is checked (controlled). |
onValueChange | (checked: boolean) => void | — | Called with the new checked state when the swap is toggled. |
mode | 'rotate' | 'flip' | rotate | Transition between states ('rotate' | 'flip'). |
aria-label | string | — | Accessible label used when no visible label is present. |
className | string | — | Additional CSS class names merged onto the root element. |
Design tokens
--cascivo-ring-width--cascivo-ring-color--cascivo-radius-control--cascivo-ease-out
When to use
- 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
- 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
How to build an accessible Swap in React →
Examples
Theme toggle (rotate)
Sun/moon icon that rotates between two states
<Swap on={<SunIcon />} off={<MoonIcon />} mode="rotate" aria-label="Toggle theme" />Flip mode
Heart icon that flips to filled on activation
<Swap on={<HeartFilledIcon />} off={<HeartIcon />} mode="flip" aria-label="Favorite" />