# Badge

Labels a status or category in a compact chip.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Badge.tsx)

Figma: [Badge](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3286), [Icon Badge](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1191-4539)

## Overview

A compact chip at least 80px wide, in one of five `variant` fills and two sizes, or a square or round chip that holds one icon. It renders a `<span>` unless you pass `render`.

## Examples

### Basic

```tsx
import { Badge } from '@tempoxyz/ds'

export function Demo() {
  return <Badge>Routes</Badge>
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Basic.tsx)

### Variant

Set `variant` to `soft` (default), `outlined`, `elevated`, `inverse`, or `accent`.

```tsx
import { Badge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <Badge>Routes</Badge>
      <Badge variant="outlined">Testnet</Badge>
      <Badge variant="elevated">New</Badge>
      <Badge variant="inverse">Recommended</Badge>
      <Badge variant="accent">Beta</Badge>
    </div>
  )
}

namespace styles {
  export const row = style({
    alignItems: 'center',
    backgroundColor: 'container.regular',
    borderRadius: 'xs',
    display: 'flex',
    flexWrap: 'wrap',
    gap: '8',
    padding: '16',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Variant.tsx)

### Size

Set `size` to `small` (28px) or `medium` (32px, the default).

```tsx
import { Badge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium'] as const).map((size) => (
        <Badge key={size} size={size}>
          {size}
        </Badge>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Size.tsx)

### Shape

Set `shape="icon"` for a badge that holds one icon. A `medium` icon badge is a 32px square, and a `small` one is a 24px circle.

```tsx
import { Badge, style } from '@tempoxyz/ds'
import { ArrowRight } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.rows()}>
      {(['medium', 'small'] as const).map((size) => (
        <div key={size} {...styles.row()}>
          {(['soft', 'outlined', 'elevated', 'inverse', 'accent'] as const).map((variant) => (
            <Badge key={variant} shape="icon" size={size} variant={variant}>
              <ArrowRight />
            </Badge>
          ))}
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })

  export const rows = style({ display: 'grid', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Shape.tsx)

### Render

Pass a `button` or link to `render` for an interactive badge with pointer, focus, and press feedback.

```tsx
import { Badge, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['small', 'medium'] as const).map((size) => (
        <Badge key={size} render={<button type="button" />} size={size}>
          Stablecoins
        </Badge>
      ))}
      <Badge render={<button type="button" />} variant="accent">
        Accent chip
      </Badge>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Badge/Render.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Badge } from '@tempoxyz/ds'

<Badge />
```

## Guidelines

### When to Use

* Label an attribute next to a title or row value, such as Routes, New address, or Testnet.
* Label the status of a record in words, such as Confirmed, Pending, or Failed.
* Build compact filters, such as Stablecoins, with `render={<button type="button" />}`.

### When Not to Use

* Use an [Alert](/docs/components/alert) or [Banner](/docs/components/banner) for a message that needs a sentence.
* Use a [Button](/docs/components/button) for an action, such as Retry.
* Use the `status` of a [Table](/docs/components/table) cell to color a status in a table.
* Use a [ChoiceGroup](/docs/components/choice-group) to switch between two to four views.
* Use [Kbd](/docs/components/kbd) for keyboard keys.

### Choose a Variant by Emphasis

* **Soft (soft):** The default. Attributes and categories on any surface.
* **Outlined (outlined):** Lower emphasis, such as a network beside its name.
* **Elevated (elevated):** A white fill that stands out on a tinted surface.
* **Inverse (inverse):** The strongest fill, for one recommended option.
* **Accent (accent):** Something new or highlighted, such as Beta.

### Keep One Variant per Context

Use one variant for every badge in a list or column, so only the label differs.

**Do:** Keep one variant per list or column, so only the status differs.

```tsx
/**
 * Do example for "Keep One Variant per Context" on the Badge page.
 * Keep one variant per list or column, so only the status differs.
 * @module
 */
import { Badge, style } from '@tempoxyz/ds'

const payments = [
  { address: '0x8f3c…a21b', status: 'Confirmed', variant: 'outlined' },
  { address: '0x41d0…9c7e', status: 'Pending', variant: 'outlined' },
  { address: '0xb27a…04f5', status: 'Failed', variant: 'outlined' },
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {payments.map((payment) => (
        <div {...styles.row()} key={payment.address}>
          <span>{payment.address}</span>
          <Badge size="small" variant={payment.variant}>
            {payment.status}
          </Badge>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'mono.m1',
  })
}
```

**Don't:** Mix `soft`, `outlined`, and `inverse` badges in one list.

```tsx
/**
 * Don't example for "Keep One Variant per Context" on the Badge page.
 * Don't mix `soft`, `outlined`, and `inverse` tags in one list.
 * @module
 */
import { Badge, style } from '@tempoxyz/ds'

const payments = [
  { address: '0x8f3c…a21b', status: 'Confirmed', variant: 'soft' },
  { address: '0x41d0…9c7e', status: 'Pending', variant: 'outlined' },
  { address: '0xb27a…04f5', status: 'Failed', variant: 'inverse' },
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {payments.map((payment) => (
        <div {...styles.row()} key={payment.address}>
          <span>{payment.address}</span>
          <Badge size="small" variant={payment.variant}>
            {payment.status}
          </Badge>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    width: '100% !custom',
  })

  export const row = style({
    alignItems: 'center',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'mono.m1',
  })
}
```

### Make a Badge Interactive Only for an Action

* **Display (span):** A status or attribute. Keep the default `span`.
* **Action (render):** Pass a button or link only if the badge does something.

## Content

* Keep the text to one or two words in sentence case, such as Expiring soon.
* Describe a state, not an action. Write Failed, not Retry.
* Use one word for one state across a product, such as Confirmed everywhere, not Confirmed in one place and Complete in another.
* Tags don't wrap, so a long label overflows its cell.

## Accessibility

A badge renders a `<span>` with no role, so screen readers read its text inline.

### Semantics

* **Root (span):** Screen readers read its text in place, as part of the surrounding content.
* **Render (render):** Takes the semantics of the button or link you pass, with a focus outline and press scale.
* **Variant (variant):** Changes only the fill, sets no state or role, and isn't announced. The text must name it.

### Keyboard

A static badge takes no focus. A badge rendered as a button or link is a native control:

* **Move Focus to the Badge (Tab):** Moves focus to the badge.
* **Activate or Follow (Enter):** Activates a button badge or follows a link badge.
* **Activate a Button Badge (Space):** Activates a button badge.

### Your Responsibilities

* **Name Meaningful Icons (aria-label):** If an icon badge carries meaning, set `role="img"` and an `aria-label` that names it.
* **Use Native Controls (button or a):** Pass a native button or link to `render`, so keyboards reach it. Don't add `onClick` to a static span.
* **Add Context (aria-describedby):** If a badge sits apart from its subject, add context, so "Pending" isn't read alone.
* **Report Toggle State (aria-pressed):** A filter badge must report whether it is pressed, so its state is announced.
* **Size Interactive Badges (24px):** Both sizes clear the 24px minimum target. Use medium where people tap.

## Related

[Table](/docs/components/table)

Use for status columns.

[Alert](/docs/components/alert)

Use for messages about a section.

[ChoiceGroup](/docs/components/choice-group)

Use for switching views.

[Feedback and Status](/docs/patterns/feedback-and-status)

Covers status conventions.
