Text Swap
Swaps one label for another with a short rise and blur while the width eases to fit: Pay → Processing… → Paid.
- Category: Transitions
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Text Swap
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
children | string | — | The current text. |
distance | number | 8 | Vertical travel in px. |
About Text Swap
Text Swap changes one label for another with a short rise and blur while the width eases to fit, as in Pay, Processing…, Paid.
Text Swap is an UI transition for React 19, styled with Tailwind CSS 4 and animated with Motion. It drops into Next.js, Vite, Remix or Astro through the shadcn CLI as a single file you own.
When to use Text Swap
- Button states.
- Status labels.
- Toggle labels.
- Live counters.
How it works
Width animates with layout and labels crossfade with a vertical offset.
The change it animates is also announced to assistive tech, and the motion is short enough never to block what the user wants to do. With prefers-reduced-motion on, it holds still or settles instantly instead of animating.
Customizing Text Swap
Every prop is documented in the API reference above with its type and default. The ones you will reach for first are listed here.
The Customize panel next to the preview lets you change distance live, and the Code tab updates to match, so the snippet you copy already carries your values.
- distance (number, default 8): Vertical travel in px.
Goes well with Text Swap
These transitions pieces share its tokens and motion language, so they sit together on one page without clashing.
- Icon Swap: A React icon swap: copy to check, play to pause, with a blur crossfade
- Card Resize: A React box that springs to the size of its content
- Notification Badge: A React notification badge that pops in and slides new counts in
- Page Transition: React page transitions: native-feeling push and pop between views
- Error Shake: A React error shake: a decaying head shake for wrong input
Install Text Swap
npx shadcn@latest add https://charcoalui.com/r/text-swap.jsonText Swap is free and MIT licensed. The command copies text-swap.tsx into components/ui and installs clsx, tailwind-merge; you can also copy the source from the Code tab by hand.
It pairs well with Organic Shimmer, a Pro piece: A shimmer whose band ripples like heat haze with a glowing edge, moved by transform so it composites.
Frequently asked questions
- Why does the width animate?
- Labels of different lengths would otherwise make the button jump. Text Swap eases the width to fit the new label while the old one rises and blurs out, so Pay to Processing to Paid feels like one motion.
- How do I install Text Swap?
- Run npx shadcn@latest add https://charcoalui.com/r/text-swap.json. The shadcn CLI copies text-swap.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Text Swap free for commercial use?
- Yes. Text Swap is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Text Swap work with Next.js?
- Yes. It is a client component for React 19 styled with Tailwind CSS 4, so it works in the Next.js App Router and Pages Router, Vite, Remix and Astro.
- Can an AI coding agent install Text Swap?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Text Swap's props and source and get_install_command returns the exact command.