Variants
- Default: Optional icon and text in various decorative colors used to display a tag or metadata label.
- Status: Optional icon and text in various semantic colors used to display a status, such as success, warning, or critical.
- Count: A label used to communicate a number, and commonly embedded within other primitives such as Buttons, Segmented controls, and Tabs.
- Dot: A small round dot used to display a status indicator, typically positioned on top of primitives like Avatar or Button.
- Closeable: Optional icon and text used to display a closeable item like a filter chip, commonly found inside Select or Combobox or positioned below filter Toolbars.
Dos and don’ts
- Do use Badges to display metadata that can easily be sorted or filtered.
- Do take caution to avoid too many Badges in a single context as this can become overwhelming and confusing for the user.
- Do use an icon and label and correct semantic color pairing for the status Badge.
- Do use an overflow Badge to display a count of items that exceeds the available space, often used for closeable Badges.
- Don’t add interactivity to a Badge that would confuse it for a Button or link. Only closeable Badges should be interactive.
Behavior
- Default, status, count, and dot variants are informational and non-interactive unless product-specific rules say otherwise.
- Closeable badges may expose a dismiss control only; they must not behave like primary navigation or arbitrary Button actions.
Status Badge usage
Often used with
Badges are often used with or within Buttons, Tabs, Avatars, Data grid cells, Toolbar filter rows, Combobox and Select menu items, and Menu items.Visual examples
The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.Icon only
Use an icon-only Badge when space is limited and the icon alone conveys the metadata meaning—for example, a tag type indicator beside a label.Dot indicators
Use dot Badge indicators on Avatars or Buttons to signal status such as online presence, unread notifications, or active state without adding text.Click interaction
Use click interaction on closeable Badges when users need to dismiss filters, tags, or selections directly from the badge control.Keyboard interactions
Ensure closeable and interactive Badges support keyboard focus and activation so users who rely on keyboard navigation can dismiss or trigger badge actions.Accessibility
- Screen reader context: Append hidden utility text (e.g.,
<span className="sr-only">5 unread messages</span>) when badges contain raw numeric indicators or shorthand status symbols. - Decorative elements: Apply
aria-hidden="true"to badges used purely for aesthetic dot indicators or layout decoration.