Skip to main content
On this page

Badge

Badges bring the user's attention to something.

When to use​

  • To categorise or label an object
  • To indicate the stage of a process
  • To elevate a specific data item so that it is easier to glance

When not to use​

  • As a clickable item - Badge is a decorative component, not an interactive one. Depending on context, use CTA Button, CTA Link, Chip, or TextLink instead.
  • To communicate multiple pieces of information - each Badge should communicate one clear thing about the object it is attached to. If the object needs more detailed information, use Data Table or Summary List instead.

Anatomy​

  1. Badge
  2. Label

Basic usage​

Loading...
Edit live code
<Cluster spaceBetween={2}>
  <ClusterItem><Badge>Tag</Badge></ClusterItem>
  <ClusterItem><Badge variant="info">Info</Badge></ClusterItem>
  <ClusterItem><Badge variant="success">Success</Badge></ClusterItem>
  <ClusterItem><Badge variant="warning">Warning</Badge></ClusterItem>
  <ClusterItem><Badge variant="error">Error</Badge></ClusterItem>
</Cluster>

Variants and features​

Tag variant​

Use when the Badge classifies or categorises an entity without implying a process state. Tags carry no inherent urgency or semantic direction.

Loading...
Edit live code
<Cluster spaceBetween={2}>
  <ClusterItem><Badge>Tag</Badge></ClusterItem>
</Cluster>

Status variants​

Use when the Badge communicates a process state. The variant should semantically match the state:

  • Success for successful, active, or complete states (Done, Complete, Active, Sent)
  • Error for failed, deleted, or cancelled states (Failed, Cancelled, Error)
  • Warning for flagged, at-risk, or delayed states (At risk, Overdue, Flagged, Waiting)
  • Info for in-progress or other neutral states (In progress, Scheduled, New)

The right variant depends on the context, not just the label text. The same word can carry different meanings in different processes - for example, 'Pending' might be a neutral step in one workflow and indicate a delay or problem in another. Always choose the variant that reflects what the state means to the user, not just what it is called.

Loading...
Edit live code
<Cluster spaceBetween={2}>
  <ClusterItem><Badge variant="info">Info</Badge></ClusterItem>
  <ClusterItem><Badge variant="success">Success</Badge></ClusterItem>
  <ClusterItem><Badge variant="warning">Warning</Badge></ClusterItem>
  <ClusterItem><Badge variant="error">Error</Badge></ClusterItem>
</Cluster>

Variant mapping​

Map custom variant names onto the built-in variants with the theme's badge.variants. This is useful when your application uses domain-specific status names that differ from Nebula's defaults - for example, mapping closed to success, or overdue to warning.

Provide the custom variant name as the key and the built-in variant to map it to as the value, then pass the custom name to variant. A name with no mapping falls back to tag.

Loading...
Edit live code
<ThemeProvider
  theme={createTheme({
    config: { accessibleBadge: true },
    badge: { variants: { closed: 'success', overdue: 'warning' } },
  })}
>
  <Cluster spaceBetween={2}>
    <ClusterItem><Badge variant="closed">Closed</Badge></ClusterItem>
    <ClusterItem><Badge variant="overdue">Overdue</Badge></ClusterItem>
    <ClusterItem><Badge variant="unmapped">Unmapped</Badge></ClusterItem>
  </Cluster>
</ThemeProvider>

Sizes​

The default size (height space.6) is correct for the vast majority of contexts: table cells, summary lists, inline with body text, tab labels, account header.

The large variant (height space.7) is for higher-prominence placements only:

  • Beside a page title
  • As a primary status indicator in the top right corner of a Card
Loading...
Edit live code
<Cluster spaceBetween={2}>
  <ClusterItem>
    <Badge variant="info">Default</Badge>
  </ClusterItem>
  <ClusterItem>
    <Badge variant="info" size="large">Large</Badge>
  </ClusterItem>
</Cluster>

Legacy badge​

The accessible badge is the style shown throughout this page, and the docs site enables it. The library default is still the legacy badge, until teams have migrated. Set the accessibleBadge theme config flag to switch between them.

The legacy badge ignores size, so both badges below render at the same height.

Loading...
Edit live code
<ThemeProvider theme={createTheme({ config: { accessibleBadge: false } })}>
  <Cluster spaceBetween={2}>
    <ClusterItem><Badge>Tag</Badge></ClusterItem>
    <ClusterItem><Badge variant="info">Info</Badge></ClusterItem>
    <ClusterItem><Badge variant="success">Success</Badge></ClusterItem>
    <ClusterItem><Badge variant="warning">Warning</Badge></ClusterItem>
    <ClusterItem><Badge variant="error">Error</Badge></ClusterItem>
    <ClusterItem><Badge variant="info" size="large">Large is ignored</Badge></ClusterItem>
  </Cluster>
</ThemeProvider>

Grouping​

Tag Badges can be grouped to show multiple attributes of an entity. Status Badges should be used alone.

Use the Cluster layout component for groups of Badges, with the betweenBadges spacing token for horizontal and vertical gaps.

Loading...
Edit live code
<Stack spaceBetween={2}>
  <Cluster spaceBetween={2}>
    <ClusterItem><Badge>UK</Badge></ClusterItem>
    <ClusterItem><Badge>Electricity</Badge></ClusterItem>
    <ClusterItem><Badge>EV owner</Badge></ClusterItem>
  </Cluster>
</Stack>