Skip to documentation content
|

Action Swap

Cycle an action's label and icon with blur, roll, or letter-cascade transitions.

github
action-swap-demo

Overview

Use Action Swap when one compact control moves through a small, predictable set of related modes. The button can animate its label, icon, or both while preserving a stable hit target.

Installation
npx honestui@latest add action-swap

Usage

 
import { ActionSwapButton } from "@/components/animated/action-swap"

const items = [
  { id: "digest", label: "Daily digest" },
  { id: "paused", label: "Digest paused" },
]

<ActionSwapButton items={items} animation="cascade" />

Use ActionSwapText and ActionSwapIcon directly when another control owns the interaction. The action-swap-blur, action-swap-roll, and action-swap-cascade entry points provide fixed-animation wrappers.

Accessibility

Keep every state label specific. Icon-only items need an ariaLabel. Reduced-motion users receive an immediate, legible state change without the full transition.

API Reference
PropTypeDefaultDescription
items*ActionSwapItem[]–Ordered states with an id, visible label, optional icon, and optional ariaLabel.
valuestring–Controlled active item id.
defaultValuestring–Initial item id for uncontrolled use.
onValueChange(value, item) => void–Runs after the active item changes.
animationblur|roll|cascade"blur"Transition used for the label and icon.
variantprimary|secondary|outline|ghost"secondary"Visual emphasis of the button.
sizesm|md|lg|icon"md"Button size.
cyclebooleantrueAdvances to the next item when clicked.