SagUI

Badge

A small label for status, category, or metadata.

import { Badge } from "@sagui/ui";
Markdown
Loading demo

When to use

  • Short statuses next to titles or in table cells, such as Live, Draft, or Failed.
  • Counts or states that change in place and should morph instead of jump.
  • Tagging a row with one tone plus an optional icon.

When not to use

  • Use alert or toast when the message needs a full sentence.
  • Use chip-group when people toggle the values.
  • Use stat-card for a headline number with a trend.

Installation

Install the package and import the styles once. The installation guide covers the Tailwind setup.

$ npm install @sagui/ui

Usage

example.tsx
import { Check } from "lucide-react";
import { Badge } from "@sagui/ui";

export function DeployStatus({ live }: { live: boolean }) {
  return (
    <Badge tone={live ? "success" : "neutral"} icon={live ? <Check size={12} /> : undefined}>
      {live ? "Live" : "Draft"}
    </Badge>
  );
}

Examples

Tones

Loading demo

Sizes

Loading demo

With an icon

Loading demo

Morphing status

Change the children, tone and icon on the same badge to get the morph.

Loading demo

API reference

Badge

A small status pill whose label and icon morph in place when they change.

Prop Type Default Description
tone "neutral" | "success" | "info" | "warning" | "danger" "neutral" Color of the pill.
size "sm" | "md" "md" Height and text size.
icon ReactNode – Leading icon. A different icon component crossfades in.
children ReactNode – Label. String or number children get the rolling text swap; other nodes render as is.
...props HTMLAttributes<HTMLSpanElement> – Forwarded to the root span, including className.

Accessibility

  • Renders a plain span, so it is read inline with surrounding text.
  • The icon is aria-hidden; the label must state the status on its own, not rely on tone color.
  • Outgoing labels are hidden from assistive tech while they fade, so only the current text is read.
  • It does not announce changes. Put it inside a live region if a status update must be spoken.

Motion

  • A new label rises in with a short blur while the old one lifts away, and the pill width springs to fit.
  • Passive reflows such as font swaps resize instantly; only a content change springs.
  • Reduced motion swaps the label with a quick fade and snaps the width.

Responsive behavior

  • The pill sizes to its label and never wraps, so keep labels to a word or two in narrow cells.
  • Hover styles apply only on hover-capable fine pointers.

Performance

  • Each badge has a ResizeObserver for the width spring; fine per row, but avoid thousands in one table.
  • Font swaps and passive reflows resize instantly; only content changes animate.

Notes

  • Use for short statuses and counts next to titles or in table cells. Use alert or toast for messages with sentences.
  • Keep the badge mounted and change its children to get the morph; remounting with a new key loses it.

Also in data display