Skip to content

Badge

Badge is used to notify users of updated content.
Figma logo
  • An empty dot draws a user’s attention to updated content in a space-constrained UI, such as the top nav
  • Badge can be used to draw a user’s attention to numerical counts
  • The root DOM node is a span, so child content should also be inline

Notification dots are generally placed next to icons.

Numbers larger than the max value will be appended with a + sign.

Use the color prop to call attention to urgent notifications.

React props
NameTypeDefaultDescription
children  ReactNodeThe content that sits alongside the dot, most frequently an icon; should be inline elements
color  errorprimaryprimaryColor of the notification dot
max  number99The largest numerical value before it is maxed out and appended with a + sign
value  numberThe numerical value inside the dot
  • Badge applies a default aria-label to the root DOM node. This can be easily overwritten by defining the aria-label prop.
  • The value of the dot is hidden from screen readers in favor of the more comprehensive text provided by aria-label on the root node.
  • Consider using aria-hidden on child content if it is not helpful to screen readers. Workbench icons are hidden from screen readers by default.

The following testing snippet(s) offer suggestions for testing the component using React Testing Library with occasional help from Jest.

// Testing with icon child
render(
<Badge value={7} max={6}>
<News />
</Badge>,
);
// label is generated automatically but can be overwritten via aria-label
const badge = screen.getByLabelText('7 new notifications');
expect(badge).toHaveTextContent('6+');
// Testing with default label
render(<Badge>Badge contents</Badge>);
// 'New notifications' is the default label with no value specified but can be overwritten via aria-label
const badge = screen.getByLabelText('New notifications');
expect(badge).toHaveTextContent('Badge contents');
// Testing with custom label
render(<Badge aria-label="Custom label">Badge contents</Badge>);
const badge = screen.getByLabelText('Custom label');
expect(badge).toHaveTextContent('Badge contents');
// Testing with value
render(<Badge value={7}>Badge contents</Badge>);
const badge = screen.getByLabelText('7 new notifications');
expect(badge).toHaveTextContent('Badge contents');
// Testing with value and max
render(
<Badge value={7} max={6}>
Badge contents
</Badge>,
);
const badge = screen.getByLabelText('6+ new notifications');
expect(badge).toHaveTextContent('Badge contents');
// Testing with value, max, and custom label
render(
<Badge value={7} max={6} aria-label="Custom label">
Badge contents
</Badge>,
);
const badge = screen.getByLabelText('Custom label');
expect(badge).toHaveTextContent('Badge contents');