React Badge component

Preview

import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="sm" wrap>
  <Badge>Draft</Badge>
  <Badge tone="success">Passing</Badge>
  <Badge tone="warning">Stale</Badge>

Usage

Use when

Marking item status: active, pending, archived
Showing a count inline
Tagging or categorising content
Flagging what is new or changed

Avoid when

Real errors that need attention — use Alert
Anything longer than a few words — use Alert
Clickable filters or a selected filter — use Chip or ToggleGroup
View switching — use Tabs or links

Implementation notes

Under 20 characters; a longer label truncates
A badge is as wide as its label in every parent; a column or a grid cell never stretches it
dot for live status, always beside words
Neutral is the band with secondary ink; tones are soft fill plus tone ink
onRemove for user-created tags only, never system labels

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

With Dot

A status dot in the tone's ink, beside words.

import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="sm" wrap>
  <Badge tone="success" dot>Online</Badge>
  <Badge tone="warning" dot>Degraded</Badge>
  <Badge tone="danger" dot>Offline</Badge>

Removable

Dismissible tags the user added themselves.

import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="sm" wrap>
  <Badge onRemove={() => {}}>react</Badge>
  <Badge tone="info" onRemove={() => {}}>typescript</Badge>
</Stack>

Announced Status

Looks the same, but screen readers now hear the change.

<Badge tone="success" announce>Saved</Badge>

API reference

Component props
Prop	Type	Default	Description
`announce`	`boolean \| undefined`	`false`	Opt into role="status" live announcement semantics
`children`Required	`React.ReactNode`	Not set	Badge label text
`dot`	`boolean \| undefined`	`false`	A status dot in the tone's ink before the label
`icon`	`React.ReactNode`	Not set	Optional icon element before the text
`onRemove`	`(() => void) \| undefined`	Not set	Makes the badge removable. Called when X is clicked.
`tone`	`BadgeTone \| undefinedinfowarningdangerneutralaccentsuccess`	`neutral`	Colour. `neutral` is the band with secondary ink; the semantic tones paint their soft fill and ink.
`role`	`AriaRole \| undefined`	Not set	—

Accessibility

The text must carry the meaning — colour alone never does
Removable badges need a named dismiss button
Badges are silent to screen readers unless you pass announce
Do not make a badge the only signal that something changed

Standards references

AlertalternativeUse Alert for prominent, longer messages with actions
ChipsiblingChip is interactive (clickable/filterable); Badge is display-only

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.