Badge

Overview

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 fill
2. Label

Basic usage

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>
<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>

Tag variant

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

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

Status variant

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.

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>
<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>

Large variant

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.

Large variants (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

Edit live code
<Cluster spaceBetween={2}>
  <ClusterItem>
    <Badge variant="info">Default</Badge>
  </ClusterItem>
  <ClusterItem>
    <Badge variant="info" size="large">Large</Badge>
  </ClusterItem>
</Cluster>
<Cluster spaceBetween={2}>
  <ClusterItem>
    <Badge variant="info">Default</Badge>
  </ClusterItem>
  <ClusterItem>
    <Badge variant="info" size="large">Large</Badge>
  </ClusterItem>
</Cluster>

Variant mapping

Use the variants prop to map custom variant names to the built-in 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.

import { createTheme, Badge } from '@kaluza-platform/nebula';
import { ThemeProvider } from 'styled-components';

const Example = () => {
  const theme = createTheme({
    badge: {
      variants: {
        accepted: 'success',
        rejected: 'error',
      },
    },
  });

  return (
    <ThemeProvider theme={theme}>
      <Badge variant="accepted">Accepted</Badge>
    </ThemeProvider>
  );
};
import { createTheme, Badge } from '@kaluza-platform/nebula';
import { ThemeProvider } from 'styled-components';

const Example = () => {
  const theme = createTheme({
    badge: {
      variants: {
        accepted: 'success',
        rejected: 'error',
      },
    },
  });

  return (
    <ThemeProvider theme={theme}>
      <Badge variant="accepted">Accepted</Badge>
    </ThemeProvider>
  );
};

In a group

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 betweenChips spacing token for horizontal and vertical gaps.

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>
<Stack spaceBetween={2}>
  <Cluster spaceBetween={2}>
    <ClusterItem><Badge>UK</Badge></ClusterItem>
    <ClusterItem><Badge>Electricity</Badge></ClusterItem>
    <ClusterItem><Badge>EV owner</Badge></ClusterItem>
  </Cluster>
</Stack>

Content

Writing labels

Badge labels must be short and fully descriptive of the status or classification they represent.

A well-written label should:

• Be no longer than 3 words - longer labels suggest the content belongs elsewhere
• Not rely on colour to communicate meaning, because Badge fill colours do not meet AA contrast requirements against canvas and canvasMuted and may not be perceived by all users
• Not wrap onto multiple lines
• Most commonly be an adjective describing a state (Sent, Complete), but may be a noun (particularly for tag Badges, e.g. Life support), or occasionally a verb (Waiting)

Properties

Related

• Chip
• CTA Button
• CTA Link
• Notification