Loading…

Text Swap

beta

Text that animates from the old string to the new one when its value changes — fade through, shared axis X/Y/Z and per-word crossfade — with a TextRotate for cycling phrases.

Effects & motion
2 files
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add text-swap

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { TextSwap } from "@/components/ui/text-swap";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Directions
In Sentence
Live Region
In View

API

Generated from the component's own types, so a prop cannot appear here without existing.

<TextSwap>

Prop	Type	Default
`children` (required) The value. Whenever it changes, the old text animates out and the new text in.	`string \| number`	—
`appear` Animate the first value in too. `in-view` waits until the element scrolls into view (SmoothUI's `triggerOnView`). Default `false`: only changes animate.	`boolean \| "in-view"`	`false`
`as` Rendered element. Block elements lay out as `grid`, inline ones as `inline-grid`.	`TextSwapElement`	`"span"`
`delay` Milliseconds added before every entrance.	`number`	`0`
`direction` Which way the change moves. `forward` (default) is the sources' motion: with `shared-axis-x` the next phrase arrives from the inline end (the right in LTR, the left in RTL); `backward` reverses it on every axis, and runs a staircase from the last word.	`"forward" \| "backward"`	`"forward"`
`ref`	`Ref<HTMLElement>`	—
`stagger` Milliseconds between words, for the split transitions. Defaults to the source's.	`number`	—
`transition` How the old text leaves and the new text arrives.	`TextSwapTransition`	`"fade-through"`

Plus every attribute of <span> except children, ref.

Accessibility

The incoming text is the accessible text from the moment it changes; the outgoing copy is aria-hidden while it animates out and is then removed, and a change mid-transition replaces the pending text rather than stacking copies. Per-word transitions keep the whole string in a visually hidden copy with the word spans aria-hidden. Nothing is a live region unless you pass aria-live, and then only the settled value is added, never per word. Under reduced motion the swap is instant and TextRotate stops rotating; `paused` stops it on demand. shared-axis-x mirrors in RTL so forward always arrives from the inline end.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

children

The value. Whenever it changes, the old text animates out and the new text in.

string | number

—

appear

Animate the first value in too. in-view waits until the element scrolls into view (SmoothUI's triggerOnView). Default false: only changes animate.

boolean | "in-view"

false

as

Rendered element. Block elements lay out as grid, inline ones as inline-grid.

TextSwapElement

"span"

delay

Milliseconds added before every entrance.

number

0

direction

Which way the change moves. forward (default) is the sources' motion: with shared-axis-x the next phrase arrives from the inline end (the right in LTR, the left in RTL); backward reverses it on every axis, and runs a staircase from the last word.

"forward" | "backward"

"forward"

ref

Ref<HTMLElement>

—

stagger

Milliseconds between words, for the split transitions. Defaults to the source's.

number

—

transition

How the old text leaves and the new text arrives.

TextSwapTransition

"fade-through"