---
title: Badge
description: Displays a badge or a component that looks like a badge.
icon: award
author:
  name: shadcn
  url: https://github.com/shadcn
search:
  keywords: [chip, label, pill]
related:
  - /badge-group
  - /status-badge
  - /tags
mode: wide
---

<PoweredBy packages={[{ name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/badge' }]} />

### Installation

```package-install
npx shadcn@latest add @redpanda/badge
```

<ComponentPreview
  name="badge-variants-demo"
  description="Every tone across the solid, subtle, and outline emphases, plus the disabled state."
/>

## Usage

Badge has a two-axis API: a semantic **`tone`** for color crossed with a **`variant`** for emphasis. Both are optional — the default is a `default`-tone solid badge, and it renders as a `rounded-full` pill.

```tsx lineNumbers
import { Badge } from "@/components/redpanda-ui/badge"
import { CheckIcon } from "lucide-react"

// Default (`default` tone, solid emphasis)
<Badge>Neutral</Badge>

// Semantic color via `tone`
<Badge tone="success">Live</Badge>
<Badge tone="destructive">Error</Badge>

// Emphasis via `variant` (solid | subtle | outline)
<Badge tone="informative" variant="subtle">Draft</Badge>
<Badge tone="warning" variant="outline">Degraded</Badge>

// Sizes (sm | md | lg)
<Badge size="sm">Small</Badge>
<Badge size="lg">Large</Badge>

// Leading icon
<Badge tone="success" icon={<CheckIcon />}>Verified</Badge>

// As a link
<Badge tone="primary" variant="subtle" render={<a href="/tags/react">React</a>} />

// Disabled
<Badge disabled>Archived</Badge>
```

## API

### `tone` — semantic color

| Tone          | Use for                                                                                |
| ------------- | -------------------------------------------------------------------------------------- |
| `default`     | General-purpose labels. Paints `secondary-*`, the same neutral Button's `default` uses |
| `primary`     | Primary actions and highlights                                                         |
| `brand`       | Brand-related, featured items                                                          |
| `informative` | Informational status, pending states                                                   |
| `success`     | Positive status, completions                                                           |
| `warning`     | Caution, degraded states                                                               |
| `destructive` | Errors, critical issues                                                                |

### `variant` — emphasis

| Variant   | Description                                   |
| --------- | --------------------------------------------- |
| `solid`   | Filled background, highest emphasis (default) |
| `subtle`  | Soft tinted background, low emphasis          |
| `outline` | Border only, lowest emphasis                  |

### Other props

- **`size`** — `sm` (20px) · `md` (24px, default) · `lg` (32px). Icons auto-scale per size (12 / 14 / 16px).
- **`disabled`** — renders the inactive appearance and sets `aria-disabled`.
- **`icon`** — a leading icon, sized to the badge; composes with text children.
- **`render`** — render as another element (e.g. a link or button) via Base UI's polymorphic `render` prop.

:::info
Flat color/style spellings such as `success-inverted` and `primary-outline` have been removed. See [Removed flat variants](#removed-flat-variants) for the migration map.
:::

## Examples

### With icon

<ComponentPreview name="badge-with-icon-demo" description="Leading icons via the icon prop, across tones and sizes." />

### Sizes

<ComponentPreview name="badge-sizes-demo" description="The sm, md, and lg sizes." />

### Count / notification

<ComponentPreview name="badge-with-count-demo" description="Badge as a numeric indicator anchored to an icon." />

### Removable (filter chips)

<ComponentPreview
  name="badge-removable-demo"
  description="Outline badges with an inline close affordance for filter chips."
/>

### As a link

<ComponentPreview
  name="badge-link-demo"
  description="Badge rendered polymorphically as an anchor via the render prop."
/>

### Live status (announced)

<ComponentPreview name="badge-announced-demo" description="A status badge announced to screen readers via aria-live." />

## When to use

**Use Badge when:**

- Displaying status or state (Active, Pending, Complete)
- Showing categories, tags, or metadata
- Indicating counts or numbers
- Creating filterable tags or labels

**Don't use Badge when:**

- The content is long-form (use a label or text instead)
- You need a real interactive control (use Button instead)
- The information is primary, not supplementary
- It would be the only way to convey critical information (pair it with text)

## Removed flat variants

:::warning
The flat spellings below are not accepted by Badge or `badgeVariants`. Pass `tone` and `variant` separately. Invalid JavaScript calls throw instead of silently rendering an unstyled badge. The former `BadgeVariant` and `BadgeVariantKey` exports are removed.
:::

Before the two-axis API, Badge exposed a flat list of variant strings — a 10-color × 3-style matrix (`base`, `-inverted`, `-outline`) plus shadcn aliases. The `simple`, `ghost`, `link`, and flat disabled aliases are removed. The two neutral families (`neutral` and `secondary`) use `default`.

| Removed                                                                                 | Replacement                                     |
| --------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `default` / `primary` / `brand` / `informative` / `success` / `warning` / `destructive` | `tone="…"` (solid is the default)               |
| `*-inverted` (e.g. `success-inverted`)                                                  | `tone="…" variant="subtle"`                     |
| `*-outline` (e.g. `success-outline`)                                                    | `tone="…" variant="outline"`                    |
| `disabled`                                                                              | `disabled`                                      |
| `disabled-inverted`                                                                     | `disabled variant="subtle"`                     |
| `disabled-outline`                                                                      | `disabled variant="outline"`                    |
| `simple` / `simple-*`                                                                   | `tone="default"` (`subtle`/`outline` as needed) |
| `neutral` / `neutral-*` · `secondary` / `secondary-*`                                   | `tone="default"` — the two neutrals merged      |
| `outline` (generic)                                                                     | `tone="default" variant="outline"`              |
| `ghost` / `link` (shadcn aliases)                                                       | `tone="default" variant="subtle"`               |

The public `badgeVariants` helper accepts the same `tone`, `variant`, `size`, and
`disabled` options as Badge. It no longer accepts internal flat style keys or CVA
`class`/`className` options. Combine its result with caller-owned layout separately.
A bare `variant="outline"` now uses the default tone's outline, matching the two-axis API.

## Related Components

### BadgeGroup

When displaying multiple badges with overflow handling, use [BadgeGroup](/docs/badge-group) instead of manually arranging badges:

```tsx
import { Badge } from '@/components/redpanda-ui/badge';
import { BadgeGroup } from '@/components/redpanda-ui/badge-group';

// Shows: [React] [TypeScript] [Tailwind] [+1]
<BadgeGroup
  maxVisible={3}
  items={[
    {
      id: 'React',
      textValue: 'React',
      content: <Badge>React</Badge>,
    },
    {
      id: 'TypeScript',
      textValue: 'TypeScript',
      content: <Badge>TypeScript</Badge>,
    },
    {
      id: 'Tailwind',
      textValue: 'Tailwind',
      content: <Badge>Tailwind</Badge>,
    },
    {
      id: 'Next.js',
      textValue: 'Next.js',
      content: <Badge>Next.js</Badge>,
    },
  ]}
/>;
```

**Use BadgeGroup when:**

- Displaying a dynamic list of tags/badges
- You need "+N more" overflow handling with a tooltip
- Badge count may exceed available space

## Credits

- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/badge) for the badge component and style.