Feedback

Badge

Badge is a compact non-interactive label for status, classification, or numeric counts at a glance.

Style × Size — React: neutral/info/success/warning/error × sm/md/lg (no Primary; Figma has Primary × Small/Medium)

betaReact AvailableFigma AvailableDocs Partial

React last updated: 2026-07-11
Documentation last updated: 2026-06-01
Accessibility target: WCAG 2.2 AA (target)
Version: 0.3.0-beta

Known open questions

Removable Badge behavior is deferred — use Content/Tag when user-generated removable labels are required.
Warning text is shared with Figma: React --badge-warning-text → color/warning/800 (#8A4F00); Figma component/badge/warning/text → color/warning/800 (#8A4F00).
Neutral/Info/Success/Error Badge foregrounds remain accessibility-safe React divergences from Figma component/badge/*/text — do not lighten to the finalized Figma hexes for parity alone.
React has no Primary Badge variant (Figma does). Primary is a future enhancement, not Stable-v1 scope.
Stable-v1 intentional React extensions (not parity defects): 1px borders, size lg, optional status/leading icons, count mode, and API variant name error (maps to Figma Danger). Figma masters are label-only Small/Medium without borders. React tinted surfaces vs Figma opaque /100 remain a deferred visual sync, not a Stable-v1 blocker.

Live preview

Compact read-only status and count labels.

Neutral / Info / Success / Warning / Error

DraftInfoBetaReviewFailed

Counts and compact usage

Numeric / Sizes

499+SmallLarge

Badges sit inline beside headings or metadata — they are not buttons or notifications.

Purpose

A small, non-interactive status or category label — communicates state or classification at a glance.

Anatomy

Badge = optional status icon + compact label or numeric count.

Variants and states

neutral · info · success · warning · error

When to use

Status indicators (New, Beta, Draft), category tags shown read-only, count indicators.

When not to use

A removable, user-generated label — use Content/Tag. An interactive/clickable element.

Accessibility

If it conveys meaning beyond decoration, ensure that meaning is also available as text to screen readers.

Keyboard behavior

Not focusable or interactive by default.

Common mistakes

Using Badge where Tag (removable) was actually needed.

Properties

Style × Size as variants. Label (text). Warning text matches Figma (#8A4F00 via warning/800); Neutral/Info/Success/Error foregrounds are accessibility-safe React divergences. Intentional React extensions: borders, lg, optional icons, count mode, error (vs Figma danger). No Primary in React (future enhancement).

What is the difference between Badge and Alert?

Badge is a compact read-only label. Alert is a persistent message block with title, description, and optional actions.

Is a Badge interactive?

No. Badge is a span by default. Use Button or Tag patterns for interactive controls.

Tokens used

semantic/surface/elevatedsemantic/text/primary--badge-info-text--badge-success-text--badge-warning-textcolor/warning/800--badge-error-text

Component API

Prop	Type	Default	Description
variant	"neutral" \| "info" \| "success" \| "warning" \| "error"	"neutral"	Status style.
size	"sm" \| "md" \| "lg"	"md"	Compact sizing.
count	number	—	Numeric count badge.
countMax	number	99	Abbreviation threshold.
showStatusIcon	boolean	false	Shows leading status icon.

React example

Copy React example

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

export function Example() {
  return (
    <div style={{ display: "flex", gap: "0.5rem" }}>
      <Badge variant="neutral">Draft</Badge>
      <Badge variant="success" showStatusIcon>Beta</Badge>
      <Badge variant="info" count={128} />
    </div>
  );
}