---
title: Badge
description: Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels

links:
  source: badge/badge.tsx
  styles: badge.css
  storybook: Components/Data Display/Badge
  figma: true
---

## Usage

```tsx
import { Badge } from '@heroui/react';
```

<ComponentPreview
  name="badge-basic"
/>

## Anatomy

Badge is designed to be positioned relative to another element using `Badge.Anchor`. Plain-text children are automatically wrapped in `<Badge.Label>`.

> For standalone label usage, use the [Chip](/docs/react/components/chip) component instead.

```tsx
<Badge.Anchor>
  <Avatar />
  <Badge color="danger">5</Badge>
</Badge.Anchor>
```

## Examples

### Variants

<ComponentPreview
  name="badge-variants"
/>

### Sizes

<ComponentPreview
  name="badge-sizes"
/>

### Colors

<ComponentPreview
  name="badge-colors"
/>

### Placements

<ComponentPreview
  name="badge-placements"
/>

### Dot Badge

Empty badges act as status indicators — useful for online/offline states or activity signals.

<ComponentPreview
  name="badge-dot"
/>

### With Content

Badge supports text, numbers, and icons as content. When no children are provided, it renders as a dot indicator.

<ComponentPreview
  name="badge-with-content"
/>

## Customization

### Tailwind CSS

<ComponentPreview name="badge-custom-styles" />

### Global CSS

To customize the Badge component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .badge {
    @apply rounded-full text-xs;
  }

  .badge__label {
    @apply font-semibold;
  }

  .badge--accent {
    @apply shadow-sm;
  }
}
```

## Styling Reference

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Badge component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)):

#### Base Classes [!toc]
- `.badge` - Base badge container styles
- `.badge__label` - Label text slot styles
- `.badge-anchor` - Positioning wrapper for the anchored element

#### Color Classes [!toc]
- `.badge--accent` - Accent color variant
- `.badge--danger` - Danger color variant
- `.badge--default` - Default color variant
- `.badge--success` - Success color variant
- `.badge--warning` - Warning color variant

#### Variant Classes [!toc]
- `.badge--primary` - Primary variant with filled background
- `.badge--secondary` - Secondary variant with default background
- `.badge--soft` - Soft variant with lighter background

#### Size Classes [!toc]
- `.badge--sm` - Small size
- `.badge--md` - Medium size (default)
- `.badge--lg` - Large size

#### Placement Classes [!toc]
- `.badge--top-right` - Position at top-right corner (default)
- `.badge--top-left` - Position at top-left corner
- `.badge--bottom-right` - Position at bottom-right corner
- `.badge--bottom-left` - Position at bottom-left corner

#### Compound Variant Classes [!toc]

Badges support combining variant and color classes (e.g., `.badge--primary.badge--accent`). The following combinations have default styles defined:

**Primary Variants:**
- `.badge--primary.badge--accent` - Primary accent with filled background
- `.badge--primary.badge--default` - Primary default with filled background
- `.badge--primary.badge--success` - Primary success with filled background
- `.badge--primary.badge--warning` - Primary warning with filled background
- `.badge--primary.badge--danger` - Primary danger with filled background

**Soft Variants:**
- `.badge--soft.badge--accent` - Soft accent with lighter background
- `.badge--soft.badge--default` - Soft default with lighter background
- `.badge--soft.badge--success` - Soft success with lighter background
- `.badge--soft.badge--warning` - Soft warning with lighter background
- `.badge--soft.badge--danger` - Soft danger with lighter background

## API Reference

### Badge

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Content to display inside the badge (text, number, or icon). When omitted, renders as a dot. |
| `className` | `string` | - | Additional CSS classes for the root element |
| `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the badge |
| `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | Visual style variant |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the badge |
| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Position of the badge relative to its anchor |

### Badge.Anchor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The element to anchor the badge to, plus the Badge itself |
| `className` | `string` | - | Additional CSS classes for the anchor wrapper |

### Badge.Label

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Label text content |
| `className` | `string` | - | Additional CSS classes for the label slot |

## Related Components

<RelatedComponents component="badge" />
