Badge

InstallCopy Anchor Link

pnpm exec vegastack-design verify badge

pnpm dlx shadcn@4.21.0 add @vegastack/badge

UsageCopy Anchor Link

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

<Badge variant="secondary">Badge</Badge>;

ExamplesCopy Anchor Link

VariantsCopy Anchor Link

Use the variant prop to change the variant of the badge. Upstream ships six; the four semantic status families (COL-12) add success, warning and info beside destructive, written in upstream's own tinted shape.

With IconCopy Anchor Link

You can render an icon inside the badge. Use data-icon="inline-start" to render the icon on the leading edge and data-icon="inline-end" to render it on the trailing edge.

With SpinnerCopy Anchor Link

You can render a spinner inside the badge. Give the spinner the same data-icon attribute so it takes the icon spacing.

LinkCopy Anchor Link

Use the render prop to render a link as a badge. The badge is a span by default, so the anchor brought in through render is what carries the link role.

Custom ColorsCopy Anchor Link

You can retint a badge by passing classes through className. Upstream's example reaches for the raw Tailwind palette; use semantic tokens instead, so the override follows the theme into dark mode and survives a retheme.

RTLCopy Anchor Link

Every variant is written in logical properties, so a right-to-left document mirrors the padding and the icon spacing without any extra work.

Mapping domain statusesCopy Anchor Link

Map each of your domain's statuses to a label and a variant in ONE typed table, and render every badge from it. BadgeVariant is the variant union, so satisfies rejects a misspelt or retired variant at compile time and fails the build when a new status has no entry.

import { Badge, type BadgeVariant } from "@/components/ui/badge";

type RunStatus =
  "live" | "running" | "paused" | "failed" | "draft" | "archived";

const RUN_STATUS = {
  live: { label: "Live", variant: "success" },
  running: { label: "Running", variant: "info" },
  paused: { label: "Paused", variant: "warning" },
  failed: { label: "Failed", variant: "destructive" },
  draft: { label: "Draft", variant: "secondary" },
  archived: { label: "Archived", variant: "outline" },
} satisfies Record<RunStatus, { label: string; variant: BadgeVariant }>;

<Badge variant={RUN_STATUS[status].variant}>{RUN_STATUS[status].label}</Badge>;

Warning pillCopy Anchor Link

A count that needs attention — missing specs, overdue items — is the warning variant with a TriangleAlert and the count. Say what is counted when the pill stands alone; the bare number is enough only where a column header or label already names it. It is the existing Badge: never a new pill component.

<Badge variant="warning">
  <TriangleAlert aria-hidden />
  {n} missing specs
</Badge>

API ReferenceCopy Anchor Link

AccessibilityCopy Anchor Link

• Renders a span — a badge is a label, not a control, and it is not focusable or clickable on its own. Pass render to make it an anchor or a button when it has to be operable.
• The tint never carries the meaning on its own (A11Y-8): every status badge keeps its word, and an icon beside it is decorative rather than load-bearing.
• Each tinted status variant takes the family's -text ink over its /10 fill (A11Y-13), which clears the AA contrast floor in both themes.
• The component carries no focus ring of its own. When render makes it operable, the global :focus-visible outline in base.css applies (FOC-1, FOC-6).

Do / Don'tCopy Anchor Link

DeviationsCopy Anchor Link

Upstream's file plus packages/ui/upstream/patches/badge.patch. Every hunk:

• FOC-1, FOC-6 — the focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 glow and the aria-invalid rings are removed; base.css owns focus outright.
• FOC-14 — the invalid border stays upstream's aria-invalid:border-destructive, held in every state, focused or not (FOC-14 retired FOC-5's not-focus: guard).
• COL-12 — success, warning and info variants, in upstream's own destructive shape.
• A11Y-13 — each tinted status variant takes the family's -text ink; bg-<family>/10 under text-<family> measures between 3.98:1 and 4.35:1, under the AA floor A11Y-1 enforces.
• A11Y-8 — a badge is a labelled chip: the tint never carries the meaning alone.
• DOC-2 — cn is imported from @vegastack/design.
• API-16 — "use client" is added: useRender calls React.useRef internally, so the module throws on import in a React Server Component without the boundary.
• A11Y-2 — an interactive badge (rendered as a link or a button) gets an invisible ::after hit area and drops overflow-hidden, so its pointer target clears 24px. Upstream's is 20px tall.
• API-25 — BadgeVariant, the variant union derived from badgeVariants, is exported so a status map is typed against the system's own variants.