Skip to content

Badge

A short label for a status, category or count.

betaSource
DraftIn reviewPaidPendingRejectedNew

Installation

pnpm add @syntara/react @syntara/tokens
import { Badge } from '@syntara/react';

Usage

import { Badge } from '@syntara/react';

export function PaymentStatus() {
  return <Badge tone="success">Paid</Badge>;
}

Examples

Status

variant="status": a tone dot and the label in body text, with no chip.

Ready to reviewProcessingWaiting on approvalBuild failedIn betaArchivedSynced

Variants

Soft, solid and outline across all six tones.

NeutralBrandInfoSuccessWarningDanger
NeutralBrandInfoSuccessWarningDanger
NeutralBrandInfoSuccessWarningDanger

Icons, dots and sizes

A leading icon, a status dot, and the small size for counts and tags.

ApprovedAwaiting documentsNeeds attention
ActivePausedArchived
Beta12v2.4.0

Accessibility

No keyboard interaction of its own.

  • A badge is plain text (a span); it is not focusable and has no role.
  • Icons and the dot are aria-hidden: the label must carry the meaning on its own.
  • Every tone pairing (soft bg/fg, solid/onSolid) is a contrast pair the theme engine guarantees.
  • Edges are box-shadow hairlines over a transparent 1px border, so forced-colours mode still draws an edge.

Guidelines

Do

  • Use soft badges in tables and lists; save solid for one badge that must stand out.
  • Keep labels to one or two words.
  • Use the same tone for the same status everywhere.
  • Use variant="status" in tables and dense lists, where a column of filled pills gets loud.
  • Pick by job: Badge = a state or count, Tag = a static attribute, PersonChip = a person, Chip = something the user picks or removes (see the chip-family example).

Don’t

  • Don't make a badge interactive — use a Button or ToggleButton.
  • Don't rely on colour alone: 'Rejected', not a red dot.
  • Don't use brand for statuses; it has no meaning beyond emphasis.

API reference

Badge

tone
  • neutraldefault
  • info
  • success
  • warning
  • danger
  • brand

Colour. `brand` uses the primary action colours.

variant
  • softdefault
  • solid
  • outline
  • status

soft = quiet pill with a tinted fill (neutral adds a faint hairline edge so a sunken fill never reads as a hole), solid = strong fill, outline = a hairline edge only, status = no chip: a small tone dot plus the label in text.default (text.subtle for neutral), for tables and lists.

size
  • sm
  • mddefault

md is 24px tall, sm is 20px.

icon
ReactNode

Leading icon, sized to the text. Decorative.

dot
boolean

Shows a small status dot before the label, centred on the text's x-height. Always on for variant="status".

Default false

childrenRequired
ReactNode

The label: one or two words, or a number.

Tokens

The semantic tokens this component reads, grouped by what they control. Swatches show this site’s theme; change a tenant’s brand and the component follows with no code change.

Colour18
action.primary.bgaction.primary.fgaction.secondary.bgaction.secondary.fgborder.defaultfeedback.*.bgfeedback.*.borderfeedback.*.fgfeedback.*.onSolidfeedback.*.solidsurface.inversesurface.sunkentext.brandtext.defaulttext.inversetext.subtleborder.strongborder.subtle
Type6
font.bodyfont.size.xsfont.tracking.xsfont.weight.mediumfont.size.smfont.tracking.sm
Space and size4
space.1space.2space.5space.6
Shape1
radius.pill
Depth3
shadow.highlightshadow.raisedhairline
Motion5
motion.duration.fastmotion.easingmotion.duration.springmotion.easingOutmotion.spring