Action Swap

Building blocks for swapping a label or icon in place: the old one fades as the new one appears, plainly, with a small lift or letter by letter. Includes button, text, icon and multi-state versions.

Preview

Installation

npx @lumioui/cli add action-swap

Usage

import { ActionSwapText, ActionSwapIcon, ActionSwapButton, ActionSwap } from "@/components/ui/action-swap/action-swap";
<ActionSwap />

Also exported: ActionSwapText, ActionSwapIcon, ActionSwapButton.

Examples

Modes

A shared folder's settings group.

Sort

A podcast's episode list with a sort cycler in the section header.

Styles

A smart-home room.

Text Swap

A running coach's interval screen.

View Modes

An album header whose view toggle swaps List → Grid → Gallery and the photos below really re-lay out.

API reference

ActionSwapText

Prop Type Default
value* string

Slot identity — when this changes, the text animates.

—
children* ReactNode —
mode ActionSwapMode

Swap choreography. "cascade" needs a string child. Default "roll".

—
animation LegacySwapAnimation

@deprecated Use mode. "fade" maps to "blur".

—
light boolean

Cascade only: each letter of the incoming label switches on in place in reading order (over 390ms). No band is drawn. Default false.

false
lightColor string

@deprecated No effect: no reading-light band is drawn any more.

—
lightOnFill boolean

@deprecated No effect: no reading-light band is drawn any more.

—
className string

Applied to the root View AND the swapped text (text classes are inert on the View, layout classes are inert on the Text).

—

ActionSwapIcon

Prop Type Default
value* string

Slot identity — when this changes, the icon animates.

—
children* ReactNode —
mode ActionSwapMode

Swap choreography ("cascade" falls back to roll — icons are single glyphs). Default "roll".

—
animation LegacySwapAnimation

@deprecated Use mode.

—
className string —

ActionSwapButton

Prop Type Default
items* ActionSwapItem[] —
value string

Controlled active item id.

—
defaultValue string

Initial active item id (uncontrolled). Defaults to the first item.

—
onValueChange
(value: string, item: ActionSwapItem) … (value: string, item: ActionSwapItem) => void
—
variant ActionSwapButtonVariant "secondary"
size ActionSwapButtonSize "md"
mode ActionSwapMode

Swap choreography for icon + label slots. Default "roll".

—
animation LegacySwapAnimation

@deprecated Use mode.

—
light boolean

Cascade only: light the incoming label into place with a reading light (see ActionSwapText). Default false.

false
iconOnly boolean

Hide the label — icon slot only. Defaults to size === "icon".

size === "icon"
cycle boolean

Advance to the next item on press. Default true.

true
disabled boolean —
className string —

ActionSwap

Prop Type Default
states* ActionSwapState[]

States to cycle through. Must have at least 2.

—
value number

Controlled active index.

—
defaultValue number

Initial active index (uncontrolled). Default 0.

0
onStateChange (index: number) => void —
variant "pill" | "plain" | "outline"

Visual style. Default "pill".

"pill"
mode ActionSwapMode

Swap choreography for icon + label. Default "roll".

"roll"
light boolean

Cascade only: light the incoming label into place with a reading light (see ActionSwapText). Default false.

false
accessibilityLabelPrefix string

Accessible label prefix. Default "Swap to".

"Swap to"
disabled boolean —
className string —