toc

Badge

A badge shows a small dot or a count to signal new or changed information.

99+

<md-gb-badge></md-gb-badge>
<md-gb-badge>3</md-gb-badge>
<md-gb-badge>99+</md-gb-badge>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-badge.json (setup)

Usage guidelines

Link to “Usage guidelines”

Use a dot for something new. A badge without content signals new or changed information.
Use a count for a number. A large badge shows a number, such as unread messages.
Keep counts short. Content is limited to four characters, including a +, so large numbers show as 999+.
Attach it to an icon. Anchor the badge to the top trailing corner of the icon it describes.

Anatomy

Link to “Anatomy”

A badge is a single element. Without content it is a dot; with content it is a larger badge.

<md-gb-badge>5</md-gb-badge>

Examples

Link to “Examples”

Count

Link to “Count”

Set value to show a number. Counts above max (999 by default) show as max+.

<md-gb-badge value="1200"></md-gb-badge>

Anchored

Link to “Anchored”

Add anchored to place the badge on the top trailing corner of its positioned parent.

notifications

<span style="position: relative; display: inline-flex">
  <md-gb-icon>notifications</md-gb-icon>
  <md-gb-badge anchored>3</md-gb-badge>
</span>

Accessibility

Link to “Accessibility”

A dot badge is announced with its label, which defaults to "New notification". Set it to match your content.
Place the badge after the label of the destination it belongs to, so it is read in that order.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked91% tokens

63 of 135 buildable spec units are tested, 2 are excluded with a written reason and 0 are uncovered (the target is 0). 10 of 11 token declarations match the spec (91%), and 1 have no spec token.

badges on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

It uses no newer features.

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 pass

The component renders no interactive role of its own.

1 rendered state run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse100 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify JavaScript
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-badge>

Link to “<md-gb-badge>”

A Material Design badge component.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`anchored` Anchors the badge to the top trailing corner of its positioned parent (the icon's bounding box).	`anchored`	`boolean`	`false`
`label` Screen reader text for a small (non-counting) badge. Spec: non-counting badges announce "New notification", read after the destination's label.	`label`	`string`	`'New notification'`
`max` The largest count shown before it is truncated to `max+`.	`max`	`number`	`999`
`value` A count to display. Counts above `max` show as `max+` (spec: limit content to four characters, including a +). Slotted content is shown when unset.	`value`	`number`

Slots

Link to “Slots”

Slot	Description
default	The large badge's label, e.g. a count.

CSS parts

Link to “CSS parts”

Part	Description
`::part(badge)`	The badge container.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-color`
`--label-text-color`
`--padding-inline`
`--shape`
`--size`