New Components

Badge

The badge is a small visual element displaying a number, a short text or a status icon in the immediate vicinity of another interface element. It is used to signal a counter, a state or a brief piece of information attached to that element. The badge is not interactive: it does not receive keyboard focus and does not trigger any action. When placed inside a button or a link, it contributes to the accessible name of that parent element.

On this page

When to use a badge

  • A counter attached to an element: show a number right next to what it counts, unread messages on an inbox, items in a basket.
  • A status indicator: flag the state of an item in a list, compliant, in progress, blocked.
  • A short highlight: mark something new or required, one word at most.

When not to use a badge

  • For an action: a badge is not clickable. If the user has to act, it is a button or a link.
  • For a choice: a value you select or remove is a chip, not a badge.
  • For long text: beyond two or three words, switch to a real label.

Modes of action

  • Mouse: none. The badge is not clickable; the element carrying it is.
  • Keyboard: none. The badge never takes focus and never enters the tab order.
  • Screen reader: the content of the badge is read inside the accessible name of the parent element, or announced by a live region when the counter changes.

Content

  • A number or a word: the badge is read straight after the label it completes, so it has to stay very short.
  • An explicit unit: "3" on its own means nothing. The meaning comes from the neighbouring label or from the accessible name, "Messages, 3 unread".
  • A readable overflow: show "99+" rather than a number that spills out of the pill.

On this page

Keywords

  • Badge: a small visual element showing a number or a word right next to what it qualifies.
  • Accessible name: the text an assistive technology exposes for an element. The badge is built into it rather than read on its own.
  • Live region: an area whose change is announced without moving focus. It is what the counter uses.
  • aria-hidden: removes an element from the accessibility tree. Reserved for pure decoration.

Breakdown of the components

The demonstration brings together the four situations where a badge behaves differently.

Standalone badge

  • The badge and the word it qualifies form a single sentence read in one go. The grouping is carried by one element, not by two neighbouring texts that a screen reader would expose separately.
  • Meaning is never carried by colour alone: the word is written inside the badge (WCAG 1.4.1).

Badge inside an interactive element

  • The badge is part of the accessible name of the button or link containing it: "Messages, 3 unread". The number on its own would be unusable.
  • The badge does not take focus and adds no tab stop. The focus indicator stays that of the parent element (WCAG 2.4.7).

Badge without text

  • The bare dot is decorative: it carries aria-hidden. What it suggests is written out in the accessible name of the parent element.

Updating the counter

  • The new value is announced by a live region present from page load, and empty. A region inserted at the moment of the announcement is not exposed (WCAG 4.1.3).
  • The announcement names what changes: "Messages, 4 unread", never "4".

Screen reader

  • A badge is never a separate element: it is read in the flow of the label it completes.
  • No ARIA role is added. A badge is text; giving it a role would pull it out of the sentence.
  • A purely decorative badge is hidden with aria-hidden, and the matching information appears elsewhere as text.
  • A counter that changes goes through a live region, with no focus move.

The badge is a non-interactive component: it does not receive keyboard focus and has no keyboard interaction of its own. When placed inside a button or a link, it is that parent element which carries the focus and the interactions.

Keyboard interactions for the Badge component
Key Function
Not applicable The badge does not receive focus and does not respond to any keyboard key. It is reachable through the virtual cursor of screen readers.
Tab When the badge is placed inside a button or a link, moves focus to that parent element, whose accessible name includes the content of the badge.

Note: the visible focus indicator is carried by the parent element and must not be obscured by an overlaid badge. See the Buttons and Links component pages for their keyboard interactions.