# Badge · HeroUI

> Displays a small indicator positioned relative to another element, commonly used for notification counts, status dots, and labels

- Page: https://jiguang132.com/systems/heroui/docs/components/badge
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

## Anatomy

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

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

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

### Usage


> Example `badge-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### Colors


> Example `badge-colors`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### Sizes


> Example `badge-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### Variants


> Example `badge-variants`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### Placements


> Example `badge-placements`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### With Content

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


> Example `badge-with-content`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


### Dot Badge

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


> Example `badge-dot`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/badge


## Styling

### Passing Tailwind CSS classes

You can style the root container and individual slots:

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

function CustomBadge() {
  return (
    <Badge.Anchor>
      <Avatar />
      <Badge className="border-2 border-white" color="danger">
        <Badge.Label className="font-bold">99+</Badge.Label>
      </Badge>
    </Badge.Anchor>
  );
}
```

### Customizing the component classes

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;
  }
}
```

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
- `.badge` - Base badge container styles
- `.badge__label` - Label text slot styles
- `.badge-anchor` - Positioning wrapper for the anchored element

#### Color Classes
- `.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
- `.badge--primary` - Primary variant with filled background
- `.badge--secondary` - Secondary variant with default background
- `.badge--soft` - Soft variant with lighter background

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

#### Placement Classes
- `.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

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 Props

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

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

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

---

Index of all JGuang resources: https://jiguang132.com/llms.txt