Badge

Data displaySince 0.9.0

import { Badge } from '@absoluteui/components/badge';
import '@absoluteui/components/badge/style.css';

Using Angular? See Badge for Angular.

What it does

A short, static label such as “Active”, “Beta”, or “3 new” that classifies the content next to it. Badge renders an optional decorative dot or icon and the label. The label carries the meaning; tone colors, the dot, and the icon are decorative, so a badge never depends on color alone. Badges are not interactive: removable or selectable tags are Tag Group.

When to use

• Status or category of an item in a list, table cell, card, or heading: Active, Draft, Overdue, Beta.
• A count that belongs to a label, such as ‘3 new’ beside a section title.

When not to use

• Tags the user can remove or select: use Tag Group.
• Status that changes while the user works and must be announced: use Inline Message with live set.
• Messages that need explanation or actions: use Alert.

Examples

Status badges in each tone

import { Badge, type BadgeTone } from '@absoluteui/components/badge';

const row = document.createElement('p');
document.body.append(row);
const statuses: [string, BadgeTone][] = [['Draft', 'neutral'], ['In review', 'info'], ['Active', 'success'], ['Expiring', 'warning'], ['Overdue', 'error']];
for (const [label, tone] of statuses) {
  const host = document.createElement('span');
  row.append(host, ' ');
  Badge.create(host, { label, tone, dot: true });
}

Outline variant, small size, and an icon

import { Badge } from '@absoluteui/components/badge';

const heading = document.createElement('h3');
heading.textContent = 'Release notes ';
const beta = document.createElement('span');
heading.append(beta);
document.body.append(heading);
Badge.create(beta, { label: 'Beta', tone: 'info', variant: 'outline', size: 'sm', icon: 'info' });

Usage

import { Badge } from '@absoluteui/components/badge';
import '@absoluteui/components/badge/style.css';

const host = document.querySelector<HTMLElement>('#plan');
if (host) Badge.create(host, { label: 'Beta', tone: 'info', variant: 'outline', size: 'sm' });

More usage

import { Badge } from '@absoluteui/components/badge';

const host = document.querySelector<HTMLElement>('#status');
if (host) {
  const status = Badge.create(host, { label: 'Active', tone: 'success', dot: true });
  status.update({ label: 'Suspended', tone: 'warning' });
}

Anatomy

<span class="aui-badge aui-badge--{tone} aui-badge--{variant} aui-badge--{size}">
  <span class="aui-badge__dot | aui-badge__icon" aria-hidden="true">(dot or icon, optional)</span>
  <span class="aui-badge__label">label</span>
</span>

API reference

Factory

Badge.create(host: HTMLElement, options: BadgeOptions): Badge

Global configuration key: badge (see Configuration).

Options

Option	Type	Default	Description
label	string		Visible text; carries the meaning. Required.
tone	'neutral' | 'info' | 'success' | 'warning' | 'error'	"neutral"	Decorative tone color.
variant	'subtle' | 'outline'	"subtle"	subtle: tone fill; outline: tone boundary. Globally configurable.
size	'sm' | 'md'	"md"	Badge size. Globally configurable.
icon	IconRef | null		Decorative icon before the label.
dot	boolean	"false"	Decorative status dot before the label (not with icon).

Properties

Property	Type	Description
host	HTMLElement	The host element (receives the classes).
label	string	Current label.
options	Readonly<BadgeOptions>	Current options.

Methods

Method	Description
update(options: Partial<BadgeOptions>): void	Merge and apply options.
destroy(): void	Remove rendering, classes, and the configuration subscription.

CSS classes

All rules live in the aui.components cascade layer, so application styles override them without specificity battles.

Class	Purpose
aui-badge	Host.
aui-badge--neutral | --info | --success | --warning | --error	Tone modifiers.
aui-badge--subtle | --outline	Variant modifiers.
aui-badge--sm | --md	Size modifiers.
aui-badge__dot	Decorative status dot.
aui-badge__icon	Decorative icon.
aui-badge__label	Label text.

Design tokens

Tokens this stylesheet reads (verified in CI). Override them in a theme or with the Theme Designer.

--aui-border-width | --aui-color-border-strong | --aui-color-error-fg | --aui-color-error-subtle | --aui-color-info-fg | --aui-color-info-subtle | --aui-color-success-fg | --aui-color-success-subtle | --aui-color-surface | --aui-color-surface-sunken | --aui-color-text | --aui-color-text-muted | --aui-color-warning-fg | --aui-color-warning-subtle | --aui-font-family-sans | --aui-font-size-sm | --aui-font-size-xs | --aui-font-weight-medium | --aui-icon-size-sm | --aui-line-height-tight | --aui-radius-pill | --aui-space-1 | --aui-space-2

TypeScript definitions

type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'error';
type BadgeVariant = 'subtle' | 'outline';
type BadgeSize = 'sm' | 'md';
interface BadgeConfig { variant: BadgeVariant; size: BadgeSize }
interface BadgeOptions extends Partial<BadgeConfig> {
  label: string;
  tone?: BadgeTone;
  icon?: IconRef | null;
  dot?: boolean;
}

Accessibility

Pattern: Static text: no role; the label is read in document order with the content it classifies.

Keyboard

Key	Context	Action
None	Any	Not focusable; read in document order by assistive technology.

Roles

Element	Role
host	none (inline text)
dot and icon	none (aria-hidden=true)

ARIA attributes

Attribute	Element	Value
aria-hidden	dot and icon	true (decorative)

Focus

Never receives or moves focus.

WCAG 2.2 success criteria addressed

Criterion	Level	Note
1.3.1 Info and Relationships	A
1.4.1 Use of Color	A
1.4.3 Contrast (Minimum)	AA
1.4.11 Non-text Contrast	AA

Automated test results: Accessibility and compliance.

Notes and known caveats

• The label carries the meaning; tone colors, the dot, and the icon are decorative, so meaning never depends on color alone.
• A badge that changes while the user works is not announced; use Inline Message with live set for that.
• Manual screen-reader verification (NVDA, JAWS, VoiceOver) is pending.

Behavior

States

Tones neutral, info, success, warning, error; variants subtle and outline; sizes sm and md; with a dot or an icon.

State transitions

From	Trigger	To
any	update({ tone, variant, size, label })	new appearance and label
any	global configuration change	variant and size follow the configuration unless set on the instance
any	destroy()	host restored to empty

Accessibility notes

• Write labels that make sense without color: “Overdue”, not a red dot alone.
• A badge is not announced when it changes. For status that changes while the user works, use Inline Message with live.
• The e2e axe run covers the default, dark, and high-contrast themes; manual screen-reader verification is pending.

Responsive behavior

An inline-flex pill limited to the container width; a long label is truncated with an ellipsis. Keep labels to one or two words.

Right-to-left

Logical properties: the dot or icon sits at the inline start.

Theming

Subtle badges pair color-text with color-{tone}-subtle (or color-surface-sunken for neutral); outline badges pair color-text with color-surface. These pairs are in the contrast gate. Forced-colors mode draws a CanvasText boundary and dot.

Global configuration

configureAbsoluteUI({ components: { badge: { variant: 'outline', size: 'sm' } } });

Component configuration

Instance variant and size override global and theme configuration. Configuration changes re-render existing badges.

Icons

icon takes any registered icon name or icon definition; it is decorative.

Security

The label uses textContent; it is never parsed as HTML. CSP-safe.

Data handling

No persistence, network access, or telemetry.

Performance

Constant work per render: class toggles, one optional icon, and one text update.

Supported data scale

Not data-driven. Hundreds of badges on a page (for example one per table row) are fine.

Edge cases

• dot: true together with an icon is rejected; use one decoration.
• icon: null removes the icon; the dot shows again only when dot is true.
• Safe in renderers that discard nodes without calling destroy(), such as Data Table cells: the configuration subscription holds the instance weakly, so a discarded badge is released.

Errors

Code	Category	Cause
BADGE_OPTIONS	configuration	Missing or blank label, unknown tone, non-boolean dot, or dot combined with icon.
ICON_UNKNOWN	configuration	Unknown icon.
CFG_INVALID_VALUE / CFG_UNKNOWN_OPTION	configuration	Invalid variant or size, or unknown configuration.

Invalid options throw before the host is modified; an invalid update() leaves the previous state intact.

Known limitations

• Text only.
• Manual screen-reader verification is pending.

Unsupported scenarios

• Interactive badges (click, remove, select): use Tag Group or Button.
• HTML or Node content.