---
metaTitle: Badge component | AwesCode UI
meta:
  - name: description
    content: The <AwBadge /> component is used to render badges - UI Vue component for AwesCode UI.
title: Badge
---

# Badge

**Category:** Molecule | **Import:** Global

The `AwBadge` component displays a small badge with text, icon, or custom content.

## Overview

`AwBadge` provides a small badge component for displaying counts, labels, or status indicators. It supports text, icons, custom colors, and can automatically hide when empty.

## Usage

**Note:** For best visual presentation, badges should be placed on surface backgrounds (e.g., within `AwCard`, `AwModal`, or `AwIsland` components).

### Basic Example

```markup
<AwBadge text="5" />
<AwBadge text="New" />
<AwBadge text="99+" />
```

### With Icon

```markup
<AwBadge icon="awesio/bell" />
<AwBadge text="3" icon="awesio/check" />
```

### Custom Color

Valid color values: `''` (default), `'info'`, `'success'`, `'warning'`, `'error'`

```markup
<AwBadge text="New" color="info" />
<AwBadge text="Error" color="error" />
<AwBadge text="Success" color="success" />
<AwBadge text="Warning" color="warning" />
```

### Hide When Empty

```markup
<AwBadge :text="count" :hide-if-empty="true" />
```

### With Pulse Animation

```markup
<AwBadge pulse />
```

### Custom Content with Slot

The default slot allows custom content alongside the badge's text and icon props:

```markup
<AwBadge color="success" text="3">
    <AwIcon name="awesio/star" size="14" />
</AwBadge>

<AwBadge color="info" text="12">
    <span class="text-xs font-bold">VIP</span>
</AwBadge>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| text | Text or number inside badge | `String` / `Number` | `false` | `''` |
| icon | Icon name inside badge | `String` | `false` | `''` |
| color | Badge background color. Valid values: `''` (default), `'info'`, `'success'`, `'warning'`, `'error'` | `String` | `false` | `'page-bg'` |
| hideIfEmpty | Hide badge if text is empty or 0 | `Boolean` | `false` | `false` |
| pulse | Show pulse animation | `Boolean` | `false` | `false` |

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Custom badge content | - | Text and/or icon |

### Events

No events are emitted by this component.

## Related Components

- `AwTag` - Tag component
- `AwLabel` - Label component
- `AwIcon` - Icon component

## Component Behavior

### Display on Surface Backgrounds

For optimal visual presentation:
- Place badges within surface background components (`AwCard`, `AwModal`, `AwIsland`)
- Badges can be used inline with text using `AwFlow` for horizontal layout
- The surface background provides proper contrast for badge colors

### Slot Usage

- The default slot renders **before** the badge's text/icon content
- Use slot for custom icons or text alongside the standard props
- Ensure badges always have visible content (text, icon, or slot content)

## Notes

- **Import Method:** Global - Available as molecule component
- Functional component for better performance
- Uses CSS custom properties for colors with RGB support
- Text badge has padding, icon-only badge has no padding
- Pulse animation shows animated indicator
- When `hideIfEmpty` is true, badge hides when text is empty, 0, or null
- **Valid color values:** Only `''` (empty string for default), `'info'`, `'success'`, `'warning'`, and `'error'` are valid color values. Other values will not work correctly.
- Use built-in icon names with `awesio/` prefix (e.g., `awesio/bell`, `awesio/check`)