Status Badge

Description

StatusBadge is a single-element component rendered as a <span role="status"> styled as a small filled circle with a white outline ring. It carries no text content of its own; the surrounding label, row, or avatar gives it meaning.

Reach for it when you need a steady-state indicator next to something else: presence on an avatar (online, away, offline), a "live" marker on a row, a status legend in a table header, or mixed-state items in a roster. It is intentionally small so it sits inside dense layouts without crowding the content beside it.

Don't use StatusBadge when the indicator needs to carry a label or count. Use Badge for that. If the element triggers an action, use Button. If you're announcing a transient event (a save, a network blip), use Toast. If the state is "loading," use Spinner.

Installation

pnpm dlx @create-ui/cli add status-badge

Usage

import { StatusBadge } from "@/components/ui/status-badge"

<StatusBadge />

Examples

Variants

variant sets the dot color. Twelve options cover product intent (primary), status tones (success, danger, warning, info), presence (away, verified), neutral metadata (neutral), specialty tones (highlighted, cyan, lime), and white. The white variant drops the outline ring, so pair it with a dark surface.

Sizes

Three sizes (xs at 4px, sm at 6px, md at 8px). md is the default and reads well next to body text. Drop to sm or xs inside dense lists, table cells, or tooltips.

With a label

The most common pattern. Place the dot in a flex row next to a text label. The component does not render children, so the label is a sibling element.

Pinned to an avatar

Presence indicator. Position the dot absolutely on the avatar's corner. The built-in white outline keeps the dot legible against any avatar background.

In a list

Rosters and feeds where each row carries a state. Color the dot, leave the row chrome neutral.

Accessibility

The root has role="status", which exposes it as a polite live region. The dot has no text of its own, so the announced content comes from the visible label sitting next to it (or from an aria-label on the parent control).

ARIA notes:

• The component sets role="status" on the <span> root. Place a visible text label nearby so screen readers have something to announce; color alone is not announced.
• Do not rely on color alone to communicate state. If the only differentiator between two badges is hue, pair each with a label or set aria-label on the surrounding control.
• For unread counts or numerals, use Badge with numberOnly so the value is read aloud.

Styling

Tailwind override: pass className to merge classes with the component's CVA classes (via cn()):

<StatusBadge className="size-3" />

Data slots and attributes:

• data-slot="status-badge" on the root element.
• The component does not emit data-variant or data-size. Variant and size are applied as Tailwind classes, so target them through the slot plus a class selector.

Target the slot in CSS:

[data-slot="status-badge"] {
  /* … */
}

Related Components

• Badge: use when the indicator needs a label or a count. Status Badge is the dot-only sibling.
• Avatar: the canonical host surface for a Status Badge presence indicator.
• Toast: use this for transient status events, not steady-state presence.
• Spinner: use this when the state is "loading" rather than a discrete presence value.

API Reference

StatusBadge

Decorative status dot with a built-in white outline ring. Extends React.ComponentProps<"span">, so any standard span attribute (id, aria-label, onClick, etc.) is accepted.

Props

Variants