Status Badge
Badge that morphs between states: the width animates, the label cross-fades and the dot pulses while live.
- Category: Feedback
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Status Badge
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
status | "idle" | "pending" | "live" | "success" | "error" | — | |
children | ReactNode | — | Label; defaults to the status name. |
About Status Badge
Status Badge morphs between states: the width animates, the label crossfades and the dot pulses while live. Deploys, builds and uptime read at a glance.
Status Badge is a feedback component 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 Status Badge
- Deployment and build status.
- Service health and uptime.
- Order and ticket states.
- Live and recording indicators.
How it works
Width follows the label with Motion layout so the badge never jumps. The dot pulse is CSS, and the state text changes are announced politely.
State changes are announced through live regions or the right ARIA roles, so screen-reader users hear what sighted users see. With prefers-reduced-motion on, it holds still or settles instantly instead of animating.
Customizing Status Badge
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.
- status.
Goes well with Status Badge
Status Badge is already composed into a ready-made section, so you can see it in context or install the whole block.
- Features Bento: Features section
- Progress: Animated React progress bars and rings on springs, with an indeterminate sweep
- Loader: Four quiet React loaders, dots, bars, orbit and pulse, that announce themselves
- Skeleton: React skeleton loaders with a soft sweep and a blur crossfade to real content
- Alert: Animated React alerts for info, success, warning and error that collapse smoothly
- Typing Indicator: A React typing indicator: a bubble with rippling dots that tells screen readers who is typing
Install Status Badge
npx shadcn@latest add https://charcoalui.com/r/status-badge.jsonStatus Badge is free and MIT licensed. The command copies status-badge.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 Thinking Orb, a Pro piece: A sphere of dots that shows an AI is busy, with nine motions for nine kinds of busy: working, searching, solving, listening, connecting, composing, breathing, weaving and shaping. States morph into each other; dots can lean towards the cursor.
Frequently asked questions
- Which states does status badge support?
- Any you define, such as building, live, failed or paused. The badge morphs its width and colour between them and pulses its dot while live.
- How do I install Status Badge?
- Run npx shadcn@latest add https://charcoalui.com/r/status-badge.json. The shadcn CLI copies status-badge.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Status Badge free for commercial use?
- Yes. Status Badge is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Status Badge 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 Status Badge?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Status Badge's props and source and get_install_command returns the exact command.