Home

Badge

A small pill that labels something with a word or a number: a status, a count or a tag.

ui.badgecomponents/ui/badge.tsx

Use case

For the AI

Use a badge for a record's status where it is scanned in a list: an invoice that is Paid, Due soon or Overdue in a table row, an order In review, a quote still a Draft. The four state variants (success, warning, error, info) say where something stands at a glance; the quiet default labels without judging, and outline suits a count beside a title (3,820 members). It is a label, not a message: a sentence about a problem belongs in an Alert.

Use it when

  • An invoice's or an order's status in a table cell
  • A short tag beside a title (Draft, New)
  • A count next to a name or a heading
  • A small pill that links somewhere, through render

Use something else when

  • The state needs a sentence and stays on the page (the site is down): Alert
  • Something just happened and the person should know (the invoice was sent): Toast
  • Showing a keyboard shortcut: Keyboard key
  • The pill switches a filter or a view on and off: Toggle group

Examples

Draft3,820 membersNew
Quiet, outline, the ink
PaidDue soonOverdueIn review
The four states
SmallDefaultLarge
Sizes

Code

Import

import { Badge } from "@/components/ui/badge"

Usage

const TONE = {
  Paid: "success",
  "Due soon": "warning",
  Overdue: "error",
  "In review": "info",
  Draft: "secondary",
} as const

export function InvoiceStatus({ status }: { status: keyof typeof TONE }) {
  return <Badge variant={TONE[status]}>{status}</Badge>
}

export function MemberCount() {
  return <Badge variant="outline">3,820 members</Badge>
}

Rules

  • The variant carries meaning: success for done or paid, warning for soon or needs a look, error for late or failed, info for in progress or in review. secondary, the default, labels anything without a state.
  • Map each status to its variant in one object (a TONE map), so the same status wears the same colour on every screen.
  • default, the ink fill, is for the one label that matters on a screen, not for every badge.
  • One or two words in sentence case. Sizes are sm, default and lg; a table uses the default.
  • A plain badge is a span and does nothing on press; to make it a link or a button pass render, which gives it press feedback.