Basel Standard / Docs

Badge

Compact status and category marker for metadata-heavy surfaces.

Default

Neutral

Outline

Critical

Badges are for short state, category, or inventory signals that need to stay attached to stronger content. In this system they are intentionally compact and typographic, so they support cards, rows, and titles without becoming the dominant element on the page.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

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

<Badge>Ready</Badge>
<Badge variant="secondary">Draft</Badge>
<Badge variant="destructive">Blocked</Badge>

Why This Primitive Exists

Badges help dense interfaces communicate state without introducing another full card, alert, or button.

Use them for short labels like status, category, stock state, or moderation flags.
Keep them adjacent to the content they describe instead of floating them as decoration.
Avoid badges for long copy, primary actions, or anything that needs paragraph-level explanation.

Examples

Variant Overview

The badge API is intentionally small. Most of the decision is not which color to choose, but whether the information deserves a badge at all.

Default

Neutral

Outline

Critical

Variant	Use it for
`default`	Standard status or taxonomy labels on neutral surfaces.
`secondary`	Lower-emphasis metadata that should recede slightly.
`outline`	Lightweight tags on already-dense cards or rows.
`destructive`	Critical or blocking states that need stronger contrast.

Attached To A Surface

Badges work best when they reinforce an existing heading or row instead of trying to carry meaning on their own.

State label

Launch checklist is ready for final review.

Ready

Badges work best when they add concise state or category metadata to a stronger heading, row, or card title.

Inventory

Docs

Blocked

import { Badge } from "@/components/ui/badge"
import { Card, CardHeader, CardTitle } from "@/components/ui/card"

<Card>
  <CardHeader>
    <CardTitle className="flex items-center gap-3">
      Launch checklist
      <Badge>Ready</Badge>
    </CardTitle>
  </CardHeader>
</Card>

In Context

On editorial and operational surfaces, use badges as secondary metadata. The title, row label, or surrounding copy should still communicate the main idea without relying on color.

<Badge variant="outline">Docs</Badge>
<Badge variant="secondary">Inventory</Badge>

Guidance

Prefer Short, Stable Labels

Keep badge text to one or two words when possible.
Use them for values that remain legible even if color is removed.
If a state needs nuance, pair the badge with nearby descriptive copy instead of stretching the badge label.

Do Not Turn Badges Into Buttons

Badges are metadata, not CTAs.
If the user can click it to make something happen, a button, link, or filter chip is usually the better primitive.
If the label controls selection state, document it and style it as an interactive element rather than reusing Badge.

Use Variant Sparingly

Start with default or outline.
Reach for destructive only when the state is genuinely urgent or blocking.
If every row gets a brightly styled badge, hierarchy collapses and the labels stop helping.

API Reference

Badge

Badge renders a div and accepts standard React.ComponentProps<"div"> plus the shared badge variant below.

Prop	Type	Default
`variant`	`"default" \| "secondary" \| "destructive" \| "outline"`	`"default"`

Exports

Export	Notes
`Badge`	Root badge component for short metadata labels.
`badgeVariants`	Class-variance helper used to compose the repo's badge styles.

Because Badge extends normal div props, attributes like className, id, data-*, and aria-* pass through as expected.

Previous: Avatar Next: Breadcrumb