## Usage

Use the `<Badge />` component to quickly communicate the current status of an item. You can place the badge before or after the item, but make sure that it's clear what item the status relates to. For tallies and counts, use the [NumberBadge](#numberbadge).

NOTE: For displaying labels or contextual attributes related to a component/item, use the [Tag](/packages/tag) instead of a badge.

## Label and tone

The `label` is the primary representation of the current status of the item. Keep the label text succinct and in an active voice, often using no more than 1-2 words.

To support the label, the `tone` prop helps convey the semantic meaning of the status.

```tsx live
<Flex gap="medium" flexWrap="wrap">
  <Badge label="Neutral" tone="neutral" />
  <Badge label="Informative" tone="informative" />
  <Badge label="Caution" tone="caution" />
  <Badge label="Critical" tone="critical" />
  <Badge label="Positive" tone="positive" />
</Flex>
```

## Progress status in ELMO

Across different ELMO products, status badges are used widely to communicate the stage an item is currently in.

Below are the recommended badge colours for some of the most common status labels used across ELMO product suite. New status badge label or colour should only be introduced when there is a new, specific use case.

<Table minWidth="30rem" tableBorder>
  <TableHead>
    <TableRow>
      <TableHeaderCell>Status</TableHeaderCell>
      <TableHeaderCell>Badge</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>
        <ul>
          <li>Not yet started</li>
          <li>Recompletion required</li>
          <li>Planning</li>
          <li>Active</li>
        </ul>
      </TableCell>
      <TableCell>
        <Badge label="Informative" tone="informative" />
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <ul>
          <li>In progress</li>
          <li>Pending</li>
          <li>Pending approval</li>
          <li>Finalise</li>
        </ul>
      </TableCell>
      <TableCell>
        <Badge label="Caution" tone="caution" />
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <ul>
          <li>Completed</li>
          <li>Approved</li>
          <li>Success</li>
          <li>Synced</li>
        </ul>
      </TableCell>
      <TableCell>
        <Badge label="Positive" tone="positive" />
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <ul>
          <li>Conflict</li>
          <li>Rejected</li>
          <li>Fail</li>
        </ul>
      </TableCell>
      <TableCell>
        <Badge label="Critical" tone="critical" />
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>
        <ul>
          <li>Exempted</li>
          <li>Disabled</li>
        </ul>
      </TableCell>
      <TableCell>
        <Badge label="Neutral" tone="neutral" />
      </TableCell>
    </TableRow>
  </TableBody>
</Table>

## Weight

The `weight` prop controls the visual weight of the badge to be either `subtle` (default) or `bold`.

```tsx live
<Flex gap="medium" flexWrap="wrap">
  <Badge label="Subtle (default)" tone="informative" />
  <Badge label="Bold" tone="informative" weight="bold" />
</Flex>
```

### Example of a status system

"Mapping" a status label to a suitable semantic tone can be hard. Here's a contrived example of a status system, representing the state of a training course.

NOTE: Combined labels and tones can be different depending on the product and the features it supplies. In many cases you might find that you don't need to use all of the available tones for a particular status system.

```tsx live
<Flex gap="medium" flexWrap="wrap">
  <Badge label="Not started" tone="neutral" />
  <Badge label="In progress" tone="informative" />
  <Badge label="5 days left" tone="caution" />
  <Badge label="Expired" tone="critical" />
  <Badge label="Completed" tone="positive" />
</Flex>
```

## Max width

If space is limited you can set a `maxWidth` on the badge. This will truncate any overflowing text in the label. The default max width is `100%`, so alternatively you can set a width on the parent element to achieve the same effect (denoted below with a border). Avoid truncation of text where possible, as it hides information from the user.

```tsx live
<>
  <Badge maxWidth="10rem" label="Badge max width will truncate overflowing label" tone="neutral" />

  <Flex width="10rem" borderColor="neutralBold" borderStyle="solid" borderWidth="thick">
    <Badge label="Parent fixed width will also truncate overflowing label" tone="neutral" />
  </Flex>
</>
```

## NumberBadge

Use the `<NumberBadge />` component when you need to notify the user about a tally or count. It only accepts a numeric value via its `number` prop, and supports all the same semantic tones as `<Badge />`. The default `tone` is `informative`. It also supports the `weight` prop, which defaults to `bold`.

```tsx live
<Flex gap="medium">
  <NumberBadge number={3} />
  <NumberBadge number={3} tone="caution" />
  <NumberBadge number={3} tone="critical" />
  <NumberBadge number={3} tone="positive" />
  <NumberBadge number={0} tone="neutral" />
</Flex>
```

### Cap

When the `number` is expected to exceed a certain point, and the exact number is not particularly valuable to the user, you can optionally "cap" the `number` of the badge. When the `number` is greater than the `cap` value, the `cap` value will be displayed along with a `+`.

```tsx live
<Flex gap="medium">
  <NumberBadge cap={99} number={1000} />
  <NumberBadge cap={4} number={5} />
</Flex>
```

Badge

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

label

tone

Optionally set the colour weight to help emphasise the badge. Defaults to `subtle`.

weight

Set the max width of the badge, truncating any overflowing text in label. Defaults to `100%`.

maxWidth

number

Optionally set the semantic tone to help convey the intent. Defaults to `informative`.

Optionally set the colour weight to help emphasise the badge. Defaults to `bold`.

Optionally cap the `number` of the badge. When the `number` is greater than the `cap` value,
the `cap` value will be displayed along with a `+`.

NumberBadge

Prop	Required	Description	Type
`label`	✅	Label of the status.	string
`tone`	✅	Semantic tone to communicate the status.	"positive" \| "informative" \| "caution" \| "critical" \| "neutral"
`weight`	—	Optionally set the colour weight to help emphasise the badge. Defaults to subtle.	"subtle" \| "bold"
`maxWidth`	—	Set the max width of the badge, truncating any overflowing text in label. Defaults to 100%.	string \| numberSupports responsive prop syntax

Prop	Required	Description	Type
`number`	✅	Numeric label of the badge.	number
`tone`	—	Optionally set the semantic tone to help convey the intent. Defaults to informative.	"positive" \| "informative" \| "caution" \| "critical" \| "neutral"
`weight`	—	Optionally set the colour weight to help emphasise the badge. Defaults to bold.	"subtle" \| "bold"
`cap`	—	Optionally cap the number of the badge. When the number is greater than the cap value, the cap value will be displayed along with a +.	number