Cmpnts

Menu

Atoms

Badge, Status, Chip and Kbd

Small labels chosen by their job, such as a count on something, the state of something, a value someone chose or a key to press.

3 Passed Ferns Esc
Code
HTML
<span class="badge"><span class="badge__text">3</span></span>
<span class="status status--success"><span class="status__text">Passed</span></span>
<span class="chip"><span class="chip__text">Ferns</span></span>
<kbd class="kbd">Esc</kbd>

Why it exists

A small rounded label can mean almost anything: a count, a result, a tag, a key. When one pill does all of those jobs, the reader has to guess which one it’s doing, and the markup can’t help a screen reader tell them apart.

So there are four atoms, and you choose by job, not by look. If it’s attached to something, it’s a Badge. If it says what state something is in, it’s a Status. If it’s a value someone chose or could remove, it’s a Chip. If it’s a key, it’s a Kbd.

Each takes only the axes its job needs. A Badge is always solid, because it has to show on its host. A Chip has no intent, because a value someone picked isn’t good or bad. A Kbd has only a size and a quieter edge.

When to use

  • Badge: a count or dot attached to a host, such as unread items on a Tab.
  • Status: the state of a thing, in words, such as “Passed” in a Table row.
  • Chip: a value someone chose or could remove, such as an active filter or a tag.
  • Kbd: a key or shortcut to press.
  • Not for a message: a sentence that needs attention is a Banner.

Rules

  • Never colour alone (WCAG 1.4.1). A Status says its state in words, and a Badge’s meaning is in its host’s name.
  • Presence (online, away, busy) is a dot Badge on an Avatar, not a Status.
  • Scripts change the __text span. Text goes in .badge__text, .status__text or .chip__text, which trims it so it centres optically. A script that writes to the parent loses that.

Keyboard and screen readers

  • A Chip’s remove control is a real <button>, so Tab reaches it and Enter or Space presses it. Its aria-label says what goes: “Remove TypeScript”.
  • Removing a Chip is the product’s script, and so is the focus after it. Move focus to the next Chip, or back to the Input that created it, or keyboard users lose their place.
  • A .kbd only shows a key. The product scripts the shortcut itself, and mirrors it in aria-keyshortcuts on its control.
  • A Status that changes while someone is on the page isn’t announced on its own. Say the change in a role="status" element.

A Count Belongs to Its Host

The host’s name carries the count, and the Badge is hidden from screen readers so it isn’t read twice.

Issues , 14 open
Code
HTML
<button type="button" class="button button--icon" aria-label="Notifications, 3 unread">
  <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#BellFilled"/></svg>
  <span class="badge badge--danger badge--sm badge--top-end" aria-hidden="true"><span class="badge__text">3</span></span>
</button>
<a href="#when-to-use" class="tab">
  <span class="tab__text">Issues</span>
  <span class="badge badge--sm" aria-hidden="true"><span class="badge__text">14</span></span>
  <span class="sr-only">, 14 open</span>
</a>

A State Is Said in Words

The text carries the state, and intent backs it up. Choose the prominence for how much the state matters on this page.

Queued
Code
HTML
<span class="status"><span class="status__text">Queued</span></span>

A Value Someone Chose

A static tag, and a token someone can remove.

TypeScript TypeScript Lesson 04
Code
HTML
<span class="chip"><span class="chip__text">TypeScript</span></span>
<span class="chip chip--subtle">
  <span class="chip__text">TypeScript</span>
  <button type="button" class="chip__remove" aria-label="Remove TypeScript">
    <svg class="icon" width="1em" height="1em" aria-hidden="true" focusable="false"><use href="#Close"/></svg>
  </button>
</span>
<span class="chip chip--plain"><span class="chip__text">Lesson 04</span></span>

A Key to Press

A single key and a combination. Mirror the shortcut in aria-keyshortcuts on its control.

Esc ⌘K
Code
HTML
<kbd class="kbd">Esc</kbd>
<kbd class="kbd"><kbd>⌘</kbd><kbd>K</kbd></kbd>

Do and Don’t

DoDon’t
Choose the atom for its job.Use a Badge as a label because it looks right.
Say the state in words: “Failed”.Show a red dot and nothing else.
Put a Badge’s meaning in its host’s name: “Notifications, 3 unread”.Leave a screen reader with “3”.
Move focus to the next Chip after removing one.Let focus fall back to the top of the page.
Mirror a shortcut in aria-keyshortcuts on its control.Rely on a .kbd to make the shortcut work.

In Storybook

See also

  • Button: An action on the page, such as saving a Form, opening a Dialog or changing a setting.
  • Avatar and Avatar Group: Who someone is, as a photo, initials or an icon in a shape.
  • Icon and Icon Box: A small glyph that helps people recognise something, on its own or in a frame.
  • Form Controls: The parts people fill in or set, such as text inputs, selects, checkboxes, switches and sliders.

Search the docs