Skip to content
flyingsalmon

Badge

A badge is a static marker for a status, a category, or a small count.

UnderwayBookedNeeds a passport

Installation

npx shadcn@latest add @flyingsalmon/badge

Usage

import { Badge, BadgeVariant } from '@/components/ui/badge'

export function TripStatus() {
  return <Badge variant={BadgeVariant.Success}>Booked</Badge>
}

Examples

Variants

Default marks what is live right now, secondary fills quietly, and outline draws a border only. Success, warning, and error are the status trio: a tinted fill behind coloured text.

UnderwayDraftSharedBookedExpiringPayment failed

Leading icon

The icon prop takes one icon before the label. Pass it bare: the badge sizes it, spaces it, and hides it from screen readers. There is no trailing slot.

NewBookedExpiringPayment failed

Count

A small number reads as a badge beside a label. Keep it to a count the traveller would glance at, not a figure they would compare.

Places to visit12

In a table row

The badge keeps one height, so it sits in a cell without changing the row’s rhythm.

TripStatus
Hanoi in springBooked
Da Nang with the familyNeeds a passport
Kyoto in autumnDraft

In a line of text

The badge sits inline after the words it qualifies.

Brian Nguyen invited you to Hanoi in spring Shared

Guidelines

When to use

  • To label the state of a thing: a trip is booked, a payment failed, a visa is expiring.
  • To tag a category or show a small count beside a label.

When not to use

  • Use Button when the marker must do something on press, because a badge takes no focus and nothing inside it is interactive.
  • Use Notice to report the result of an action, because a result belongs on the item that changed or in a notice that links back to it.
  • Use Avatar to mark a person, because a person has a face and a name.

Do and don’t

  • Don’t
    Give the normal state a badge.An exception reads at a glance only against plain rows. When every item wears a badge, none of them stands out.
  • Do
    Name the state in the label, such as Booked or Date clash.Colour only reinforces the word. A reader who cannot tell orange from green still has to learn the state.
  • Do
    Keep the orange badge for what is live right now, such as today or a trip underway.Orange is the loudest colour on the page, so it marks the one thing happening now. A finished state is green, a fact or an absence takes the outline, and quiet metadata takes the grey badge.
  • Do
    Paint a condition that already holds, such as a failed payment, in error red.Error red reports a condition. Destructive red names an action a person can take, such as delete, and belongs to the destructive button.
  • Do
    Add an icon to a state that needs attention or is done, and leave neutral states as words.The icon gives the states that matter a shape the eye catches before it reads, so a warning stands out from a row of quiet labels.
  • Don’t
    Put more than one state badge on an item.Each badge asks to be read, and a second state means the first is not the one that matters. Put the rest in the item’s details. Category tags are the exception and sit together as a quiet row.

Accessibility

The badge renders a plain span with no role and no tab stop, so a screen reader reads its text inline with the surrounding content. A leading icon is decoration and is hidden, so the label is read once. A link or a button inside a badge is unreachable by keyboard, so a badge holds only its label and icon. Every variant meets WCAG AA contrast. When the badge is the only carrier of a meaning, state that meaning in the surrounding text as well.

API

Badge

Also takes every <span> attribute except tabIndex.

PropTypeDefaultDescription
variantBadgeVariantBadgeVariant.DefaultDefault, Secondary, Outline, Success, Warning, or Error. Error marks a condition that already holds, never an action.
iconReactNode–One leading icon. The badge owns its size and hides it from screen readers.

  • Avatar

    The mark for a person rather than a state.
  • Table

    Where a status column puts one badge per row.
  • Notice

    Where a result with no visible home goes.
  • Colours

    The status tints a badge draws from.