Action Swap Blur

pnpm dlx shadcn@latest add @paneui/action-swap-blur

Installation

pnpm dlx shadcn@latest add @paneui/action-swap-blur

Usage

import { ActionSwapBlurButton } from "@/components/ui/action-swap-blur"

<ActionSwapBlurButton
  resetAfter={1600}
  items={[
    { value: "copy", label: "Copy", icon: <CopyIcon /> },
    { value: "copied", label: "Copied", icon: <CheckIcon /> },
  ]}
/>

Examples

Cycle

Use when one button steps through several states in turn.

Text Only

Use when the states need words but no icon.

Controlled

Custom Slots

Animations

Motion

The swap runs 220ms ease-out while the width springs. With reduced motion they cross-fade and the width snaps. Each new state is announced through a polite live region.

Action Swap Roll has the same API with a rolling animation.

API Reference

ActionSwapBlurButton

A Button that advances through items on click, swapping its icon and label with a blur. Same props as ActionSwapButton without animation. Also accepts every prop of Button.

items*: ActionSwapItem[]; States in order: { value: string; label: ReactNode; icon?: ReactNode; ariaLabel?: string }.
value: string; Controlled current item value.
defaultValue: string; Initial item value. Defaults to the first item.
onValueChange: (value: string, item: ActionSwapItem) => void; Called when the current item changes, including on reset.
iconOnly= true for `icon*` sizes: boolean; Hide the label and swap only the icon slot.
cycle= true: boolean; Advance to the next item on click. Turn off to drive value yourself.
resetAfter: number; Milliseconds after which the button returns to its first item, e.g. Copied → Copy.
size= "default": Button size; Passed to Button.

Prop	Type	Default	Description
items*	ActionSwapItem[]	—	States in order: `{ value: string; label: ReactNode; icon?: ReactNode; ariaLabel?: string }`.
value	string	—	Controlled current item value.
defaultValue	string	—	Initial item value. Defaults to the first item.
onValueChange	(value: string, item: ActionSwapItem) => void	—	Called when the current item changes, including on reset.
iconOnly	boolean	true for `icon*` sizes	Hide the label and swap only the icon slot.
cycle	boolean	true	Advance to the next item on click. Turn off to drive `value` yourself.
resetAfter	number	—	Milliseconds after which the button returns to its first item, e.g. Copied → Copy.
size	Button size	"default"	Passed to Button.

ActionSwapBlurText

Label slot that swaps its content when value changes, gliding to the new width. Also accepts every prop of span.

value*: string; Identity of the current label; a new value triggers the swap.
children*: ReactNode; The label.
className: string; Classes for the slot.

Prop	Type	Default	Description
value*	string	—	Identity of the current label; a new value triggers the swap.
children*	ReactNode	—	The label.
className	string	—	Classes for the slot.

ActionSwapBlurIcon

16px icon slot; the old glyph leaves as the new one arrives in the same cell. Also accepts every prop of span.

value*: string; Identity of the current icon.
children*: ReactNode; The icon.
className: string; Classes for the slot.

Prop	Type	Default	Description
value*	string	—	Identity of the current icon.
children*	ReactNode	—	The icon.
className	string	—	Classes for the slot.

ActionSwapButton

The shared engine behind the blur, roll and cascade presets. Also accepts every prop of Button.

animation= "blur": "blur" | "roll" | "cascade"; Swap style. cascade splits plain-string labels letter by letter and rolls anything else.
…: same as ActionSwapBlurButton

Prop	Type	Default	Description
animation	"blur" \| "roll" \| "cascade"	"blur"	Swap style. `cascade` splits plain-string labels letter by letter and rolls anything else.
…	same as ActionSwapBlurButton	—

ActionSwapText / ActionSwapIcon

Engine slots; the preset slots are these with animation fixed.

animation= "blur": "blur" | "roll" | "cascade"; Swap style.

Prop	Type	Default	Description
animation	"blur" \| "roll" \| "cascade"	"blur"	Swap style.