Badge

Material Design 3 badge for compact status, count, and notification indicators. Not intended to carry critical standalone information without adjacent context.

Basic Usage

Use a badge inline to show a small numeric value. Badges summarize count or state while relying on nearby labels for meaning.

Inbox

<ds-badge value="3"></ds-badge>

Initial Value

Initialize with custom max and color attributes.

<ds-badge value="150" max="99" color="primary"></ds-badge>

Variants

Badge supports count, dot, and overlap positioning patterns.

Dot Badge

Messages

Overlap Position

<button style="position: relative">
  Notifications
  <ds-badge value="7" position="overlap"></ds-badge>
</button>

States

Examples of empty, textual, and overflow badge states.

<ds-badge value="999" max="99"></ds-badge>

Interactive Example

Change badge values and mode dynamically. The badge is attached to a positioned host so overlap mode is easy to see.

Increment

Toggle Dot

Toggle Position

State log:

API

Attributes

Attribute	Type	Default	Description
`value`	string \| number	none	Badge content for count or text mode.
`dot`	boolean	false	Renders a dot indicator with no text.
`max`	number	99	Maximum numeric value before overflow format.
`color`	string	error	Named token color (`error`, `primary`, `secondary`) or any CSS color string.
`position`	inline \| overlap	inline	Inline flow or overlap mode for overlays.

Properties

Property	Type	Description
`value`	string \| null	Gets/sets badge value.
`dot`	boolean	Gets/sets dot mode.
`max`	number	Gets/sets overflow threshold.
`color`	string	Gets/sets badge color mode.
`position`	string	Gets/sets inline or overlap mode.

Events

Event	Detail	Description
(none)	—	Badge has no custom emitted events.

CSS Parts

Part	Description
(none)	No exposed CSS parts in current implementation.

CSS Custom Properties

Property	Description
`--ds-badge-size`	Badge size in count mode (token-mapped).
`--ds-badge-dot-size`	Badge size in dot mode (token-mapped).
`--ds-badge-padding-inline`	Horizontal inner padding for count badge.

Accessibility

Keyboard Interaction

Key	Context	Expected Result
`Tab`	Badge attached to interactive host	Focus moves to host control, not the badge itself
`Enter` / `Space`	Focus on host control	Activates host action while badge remains informational

Semantics

Badge content uses role="status".
Badge is non-focusable and inherits surrounding focus semantics.
Pair badges with contextual labels for clear screen reader meaning.

Usage Guidelines

When to use: Use badges to signal lightweight count/status changes near related controls or labels.
When not to use: Avoid badges as the only place critical meaning appears.
Composition: Keep values short, use dot for binary status, and use position="overlap" on icon/button hosts.
Common mistakes: Large unreadable counts reduce scanability; set max to clamp overflow values.