Badge

A badge marks an element with a count, a short label, or a dot, so people see what changed at a glance. Reach for a number only when the count changes what someone does; otherwise a dot is enough. Below, badges mark icon buttons, buttons, and tabs, and two of them hide and return on a timer.

Inbox forum Chat Updates Messages Cart inbox Inbox Forum person Friends Messages

Reference docs⁠

BlazorReactWebOverviewExamplesAPIStylingAccessibility

Choosing a variant⁠

Two kinds of badge say different amounts, from least to most:

  • Dot: that something is new or needs a look, with no count, such as an unread conversation or a new item in a list.
  • Value: a short number or label, such as 3, 99+, or New, when the count itself matters.

Built in⁠

  • floating anchors the badge at the top-end corner of a positioned parent, and the corner flips in right-to-left layouts.
  • A value badge is at least 16 pixels wide and grows with its text, so 99+ and New fit without sizing.
  • concealed fades the badge out and back in, and skips the animation for a reader who prefers reduced motion.
  • The fill is the system error color by default, and the badge tokens on the Styling tab change it.
  • Forced-colors mode shows the badge in system colors, with the value text kept.
  • Buttons, icon buttons, and the other controls listed on the Examples tab carry a badge of their own through badge-value, badge-dot, and badge-concealed.

Using badges well⁠

  • Put a badge on the top-end corner of an icon, not on a text label.
  • Cap a count in your own code and pass 99+; the badge shows any string and grows to fit.
  • Use a host's own badge attributes when it has them, and reach for the badge element only on an image, a link, an avatar, or a list row.
  • Show one badge per element.
  • Write a labeled state such as Draft as text, and use a chip for anything people can remove or act on.
  • Keep the error color so the badge reads as needing attention, and change it through the badge tokens, never a local background.

These rules follow Material 3 Expressive's guidance for badges, on material.io.

Dot or value⁠

value takes any string, so a count, 99+, or New all work. dot swaps the text for a small dot and ignores value; use it when something is new and the number adds nothing. With neither set, a badge renders empty.

Floating⁠

floating lifts the badge out of the flow and pins it to the top-end corner of the nearest positioned ancestor, so give that parent position: relative. Without it, the badge sits inline beside its neighbors.

Concealing⁠

Setting concealed fades the badge out and clearing it fades the badge back in. A badge in the first render appears without animation, and a reader who prefers reduced motion sees it simply appear or disappear.

On a host⁠

A button, icon button, floating action button, chip, checkbox, switch, select, field, or card carries a badge itself through badge-value, badge-dot, and badge-concealed. The host places the badge at its top-end corner and removes it when the value clears. Clearing badge-value removes the badge with no animation; badge-concealed is the animated way to hide it.

Properties⁠

PropertyAttributeTypeDescription
concealedconcealedbooleandefault falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
dotdotbooleandefault falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
floatingfloatingbooleandefault falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
valuevaluestringThe text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when dot is true. See Dot or value.

Props⁠

PropTypeDescription
concealedbooleandefault falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
dotbooleandefault falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
floatingbooleandefault falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
valuestringThe text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when dot is true. See Dot or value.

Parameters⁠

ParameterTypeDescription
Concealedbool?default falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
Dotbool?default falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
Floatingbool?default falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
Valuestring?The text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when Dot is true. See Dot or value.

Inputs⁠

InputTypeDescription
concealedbooleandefault falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
dotbooleandefault falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
floatingbooleandefault falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
valuestringThe text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when dot is true. See Dot or value.

Props⁠

PropTypeDescription
concealedbooleandefault falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
dotbooleandefault falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
floatingbooleandefault falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
valuestringThe text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when dot is true. See Dot or value.

Props⁠

PropTypeDescription
concealedbooleandefault falseHides the badge with an animated transition. Toggle this property to show or hide the badge dynamically. A concealed badge keeps its space in the layout and is hidden from assistive technology. See Concealing.
dotbooleandefault falseDisplays the badge as a small dot indicator instead of showing text. Use for simple attention markers without a specific count or value. A dot is hidden from assistive technology, so it must not be the only signal. See Dot or value.
floatingbooleandefault falsePositions the badge at the top-end corner of its nearest positioned ancestor. The corner flips in right-to-left layouts, and the ancestor needs position: relative or another non-static position. See Floating.
valuestringThe text or number displayed in the badge. Common values include counts ("3", "99+") or short labels. Ignored when dot is true. See Dot or value.

A value is what the token defaults to; selecting it copies the token's name.

Tokens⁠

TokenValue
--ct-badge-color--ct-sys-color-error --ct-badge-color
--ct-badge-large-label-text-color--ct-sys-color-on-error --ct-badge-large-label-text-color
--ct-badge-large-label-text-font--ct-sys-typescale-label-small-font --ct-badge-large-label-text-font
--ct-badge-large-label-text-line-height--ct-sys-typescale-label-small-line-height --ct-badge-large-label-text-line-height
--ct-badge-large-label-text-size--ct-sys-typescale-label-small-size --ct-badge-large-label-text-size
--ct-badge-large-label-text-tracking--ct-sys-typescale-label-small-tracking --ct-badge-large-label-text-tracking
--ct-badge-large-label-text-weight--ct-sys-typescale-label-small-weight --ct-badge-large-label-text-weight

Names and states⁠

A badge follows no WAI-ARIA Authoring Practices pattern: it has no role, because it is a status marker rather than a widget.

  • The badge has no accessible name. Its text is content, and value is not a label.
  • The badge forwards no ARIA attributes, so any aria-* set on it has no effect. A dot or a concealed badge is hidden from assistive technology, and any other badge is exposed.
  • A value badge is exposed as plain text with no live region, so a change of count is not announced. Announce it yourself, for example in a live region elsewhere on the page.
  • A dot says nothing to assistive technology. State what it means another way, in the host's aria-label or in text beside it.
  • On a host, put the meaning in the host's aria-label, such as "Inbox, 3 unread". In an icon button or a floating action button, the value text joins the button's name unless it has an aria-label.

Keyboard and focus⁠

Key Action
None A badge responds to no keys.
  • A badge is not focusable and takes no pointer events when floating, so it never enters the Tab order.

Pointer and touch⁠

  • A badge adds no touch target, because it is not interactive; the host's own target size applies against WCAG 2.5.8.

Display settings⁠

  • Forced colors: the fill becomes CanvasText with a Canvas outline. A dot stays a filled disc, and a value badge becomes a Canvas pill ringed in CanvasText with its text visible. Color meaning is lost, so do not rely on it alone.
  • Reduced motion: the transitions and both conceal animations stop, and the badge appears or disappears at once.
  • Right-to-left: floating places the badge at the top-end corner, so it moves to the opposite corner when the page direction flips.

Standards⁠

With its defaults, a badge meets zero WCAG 2.2 success criteria on its own, because it takes no focus. One depends on how you use it:

  • 1.3.1 Info and Relationships (A) — give a dot's meaning in the host's aria-label or in text beside it, and announce a change of count yourself, because the badge has no live region.