HyBadge

Usage examples on this page are written for Lit / plain HTML (<hy-badge>). The same component ships as HyBadge in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A versatile badge component for displaying status indicators, counts, and labels.

Key Features:

• Multiple semantic variants (neutral, brand, success, warning, danger, info), and highlight for the one label that stands out on a screen
• Optional dot indicator for status visualization
• Number display for counts and notifications
• Flexible sizing options
• Accessible with proper ARIA attributes
• CSS custom properties for extensive theming
• Dot-only mode for status indicators without background — the lone dot takes the role's solid fill (the count bubble's color), since there is no fill behind it for on-fill ink to read against
• The count bubble is the role's solid fill in every emphasis; the neutral one wears the neutral solid badge's inverse pair

Accessibility: built in

• Semantic color choices with sufficient contrast
• Screen reader friendly content
• Supports high contrast mode
• Proper role attributes for status indicators

Accessibility: your part

• Never let a dot alone carry a state. Name the state in the badge text or next to it.

When to use

• A count on an icon or a tab: unread messages, items in a cart.
• A short status on a row or a card: Draft, Paid, Overdue.
• A dot that says something is new, with dot.

Do

• Keep it to a number or one or two words.
• Show the same status with the same badge everywhere.

When not to use

• A tag people remove, select or use as a filter: hy-chip.
• Something people click to act: hy-button.
• A condition that needs a sentence or an action: hy-alert.
• A label longer than two or three words: plain text.
• A tag colored by category, with no status meaning: variant="neutral" with category-group and identity, not success, warning or danger.

Examples

Basic usage - Default neutral badge

<hy-badge>LABEL</hy-badge>

Badge with status dot

<hy-badge variant="success" dot>LABEL</hy-badge>

Dot-only indicator (no background)

<hy-badge variant="success" dot></hy-badge>

Badge with number indicator

<hy-badge variant="danger" number="99">Notifications</hy-badge>

Number-only indicator (no background)

<hy-badge variant="danger" number="99"></hy-badge>

Different variants

<hy-badge variant="brand">LABEL</hy-badge>
<hy-badge variant="success">LABEL</hy-badge>
<hy-badge variant="warning">LABEL</hy-badge>
<hy-badge variant="danger">LABEL</hy-badge>

API

Properties

Property	Attribute	Type	Default	Description
variant	variant	'neutral' | 'brand' | 'success' | 'warning' | 'danger' | 'info' | 'highlight'	'neutral'	Visual style variant determining the badge's color scheme and semantic meaning.
emphasis	emphasis	'solid' | 'soft' | 'outlined' | 'tinted'	'solid'	Visual chrome weight on top of the role.
size	size	'small' | 'medium' | 'large'	'medium'	Physical size of the badge affecting dimensions, padding, and typography scale.
dot	dot	boolean	false	Displays a colored dot indicator before the badge content.
pending	pending	boolean	false	Marks the badge as in-progress / processing: shows the status dot (even if dot is not set) and gives it a gentle pulse, plus aria-busy on the status region. The idiomatic "processing" indicator (cf. Ant Badge status="processing") — pair with any variant (e.g. warning for a running task). The pulse honors prefers-reduced-motion and is driven by the loop.pulse motion token (overridable via --hy-badge-motion-loop-pulse-duration / --hy-badge-motion-loop-pulse-easing).
number	number	number | undefined	undefined	Displays a numeric indicator after the badge content.
countLabel	count-label	string	'{count, plural, one {# item} other {# items}}'	Accessible label for the badge count, a template: {count} is replaced by the number, formatted for the resolved locale, and a plural choice ({count, plural, one {# item} other {# items}}) picks the word's form in that locale. Use for internationalization.
categoryGroup	category-group	string | undefined	—	Categorical group name to hash into. Only applied when variant is neutral; a non-neutral variant wins. Selects which palette in the active DS's roles.categorical map this badge pulls from.
identity	identity	string | undefined	—	Identity string hashed to a stable slot within categoryGroup — same identity always produces the same color. Ignored when slotIndex is set.
slotIndex	slot-index	number | undefined	—	Explicit 1-indexed slot within categoryGroup. Takes precedence over identity. Out-of-range values fall back to default styling.

Slots

Slot	Description
default	Primary badge content (text, inline elements). Usage: Main badge label; can contain text nodes and inline elements. Accessibility: Content contributes to accessible name calculation.

CSS Parts

Part	Description
base	The root badge element. Usage: Primary styling target for customizing the badge's appearance.
dot	The dot indicator element (when dot=true). Usage: Styling target for the status dot.
number	The number indicator element (when number is set). Usage: Styling target for the number badge.

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-badge-background-brand-soft-rest	var(--hy-background-brand-soft-rest)	One of the generated color hooks (paint/badge.mjs): --hy-badge[-<part>]-<family>-<variant>-<emphasis-or-on>-<state> (family: background, foreground or border), one per cell and state, each falling back to the job token of the same name (the default cell is neutral solid). Components ▸ Add an override lists them all.
--hy-badge-text-transform	none	Text transform for badge label Default: none
--hy-badge-label-xs-font-family	var(--hy-label-xs-font-family)	Font family override for badge label
--hy-badge-gap-pill-md-inline	var(--hy-gap-pill-md-inline)	Gap between badge content parts (icon, text)
--hy-badge-radius-pill-md	var(--hy-radius-pill-md)	Badge corner radius (pill)
--hy-badge-padding-pill-md-inline	var(--hy-padding-pill-md-inline)	Inline padding at medium size
--hy-badge-padding-pill-md-block	var(--hy-padding-pill-md-block)	Block padding at medium size
--hy-badge-padding-pill-sm-block	var(--hy-padding-pill-sm-block)	Block padding at small size
--hy-badge-padding-pill-sm-inline	var(--hy-padding-pill-sm-inline)	Inline padding at small size
--hy-badge-padding-pill-lg-block	var(--hy-padding-pill-lg-block)	Block padding at large size
--hy-badge-padding-pill-lg-inline	var(--hy-padding-pill-lg-inline)	Inline padding at large size
--hy-badge-padding-layout-2xs	var(--hy-padding-layout-2xs)	Inline padding in dot-only mode
--hy-badge-padding-layout-none	var(--hy-padding-layout-none)	Block padding in dot-only mode
--hy-badge-dot-radius-pill-md	var(--hy-radius-pill-md)	Dot corner radius (pill)
--hy-badge-number-radius-pill-md	var(--hy-radius-pill-md)	Number indicator corner radius (pill)
--hy-badge-number-indicator-size-sm	var(--hy-indicator-size-sm)	Size of the number indicator at small
--hy-badge-number-indicator-size-md	var(--hy-indicator-size-md)	Size of the number indicator at medium
--hy-badge-number-indicator-size-lg	var(--hy-indicator-size-lg)	Size of the number indicator at large
--hy-badge-padding-layout-3xs	var(--hy-padding-layout-3xs)	Horizontal padding of the number indicator
--hy-badge-indicator-size-2xs	var(--hy-indicator-size-2xs)	Dot size at small
--hy-badge-indicator-size-xs	var(--hy-indicator-size-xs)	Dot size at medium
--hy-badge-dot-indicator-size-sm	var(--hy-indicator-size-sm)	Dot size at large
--hy-badge-motion-loop-pulse-duration	var(--hy-motion-loop-pulse-duration)	Duration of the pending dot pulse
--hy-badge-motion-loop-pulse-easing	var(--hy-motion-loop-pulse-easing)	Easing of the pending dot pulse