Icon Swap
Swaps icons with a scale-and-blur cross-fade: copy to check, play to pause, sun to moon.
- Category: Transitions
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Icon Swap
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
state | string | — | Identifies the current icon; change it to swap. |
children | ReactNode | — |
About Icon Swap
Icon Swap changes icons with a scale-and-blur crossfade: copy to check, play to pause, sun to moon.
Icon 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 Icon Swap
- Copy buttons.
- Media controls.
- Theme toggles.
- Expand and collapse.
How it works
Icons are keyed children of AnimatePresence with scale and blur transitions.
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 Icon 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.
Style it with className like any other element. It only uses your theme's tokens, so it follows light and dark mode without extra work.
- state (string): Identifies the current icon; change it to swap.
Goes well with Icon Swap
These transitions pieces share its tokens and motion language, so they sit together on one page without clashing.
- Text Swap: A React text swap: labels change with a rise and blur as the width eases
- 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 Icon Swap
npx shadcn@latest add https://charcoalui.com/r/icon-swap.jsonIcon Swap is free and MIT licensed. The command copies icon-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 Morph Menu, a Pro piece: A button that stretches into its own menu surface, then shrinks back. Arrow keys and Escape work.
Frequently asked questions
- Can I swap any two icons?
- Yes. Pass whichever icons you like, from lucide-react, your own SVGs or emoji. Icon Swap keys each one so the outgoing icon scales and blurs out while the new one comes in, which reads clearly at small sizes.
- How do I install Icon Swap?
- Run npx shadcn@latest add https://charcoalui.com/r/icon-swap.json. The shadcn CLI copies icon-swap.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Icon Swap free for commercial use?
- Yes. Icon Swap is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Icon 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 Icon Swap?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Icon Swap's props and source and get_install_command returns the exact command.