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)
• 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

Accessibility Highlights:

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

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'	'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-pulse-*).
number	number	number | undefined	undefined	Displays a numeric indicator after the badge content.
countLabel	count-label	string | undefined	—	Accessible label for the badge count. Use for internationalization. Overrides the default "${n} items" pattern.
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

Property	Description
--hy-badge-text-transform	Text transform for badge label Default: none
--hy-badge-font-family	Font family override for badge label Default: var(--hy-label-xs-font-family)
--hy-badge-spacing	Gap between badge content parts (icon, text) Default: var(--hy-gap-pill-md-inline)
--hy-badge-radius	Badge corner radius Default: var(--hy-radius-pill-md) (pill)
--hy-badge-padding-x	Inline padding at medium size Default: var(--hy-padding-pill-md-inline)
--hy-badge-padding-y	Block padding at medium size Default: var(--hy-padding-pill-md-block)
--hy-badge-padding-size-sm	Block padding at small size Default: var(--hy-padding-pill-sm-block)
--hy-badge-padding-size-sm-inline	Inline padding at small size Default: var(--hy-padding-pill-sm-inline)
--hy-badge-padding-size-lg-block	Block padding at large size Default: var(--hy-padding-pill-lg-block)
--hy-badge-padding-size-lg-inline	Inline padding at large size Default: var(--hy-padding-pill-lg-inline)
--hy-badge-dot-padding-x	Inline padding in dot-only mode Default: var(--hy-padding-layout-2xs)
--hy-badge-dot-padding-y	Block padding in dot-only mode Default: var(--hy-padding-layout-none)
--hy-badge-dot-radius	Dot corner radius Default: var(--hy-radius-pill-md) (pill)
--hy-badge-number-radius	Number indicator corner radius Default: var(--hy-radius-pill-md) (pill)
--hy-badge-number-size	Size of the number indicator
--hy-badge-number-padding	Horizontal padding of the number indicator
--hy-badge-dot-size-sm	Dot size at small / dot-only mode Default: var(--hy-indicator-size-2xs)
--hy-badge-dot-size-md	Dot size at medium Default: var(--hy-indicator-size-xs)
--hy-badge-dot-size-lg	Dot size at large Default: var(--hy-indicator-size-sm)
--hy-badge-pulse-duration	Duration of the pending dot pulse Default: var(--hy-motion-loop-pulse-duration)
--hy-badge-pulse-easing	Easing of the pending dot pulse Default: var(--hy-motion-loop-pulse-easing)