# Badge

> A small marker that shows a status or a count on top of another element.

- Category: Communication
- API status: Stable
- Compose APIs: `BadgedBox`, `Badge`, `BadgeDefaults`
- Interactive page: https://m3e.ljzapps.app/#components/badge

## When to use

A small badge is a dot that says something changed. A large badge carries a number or a short text. Attach badges to icons in navigation bars, rails and toolbars with BadgedBox.

Cap counts at 99 and show 99+ above that.

## Playground

The interactive page has a playground with live property controls for this component and generated code.

## Examples

### Dot and count

```kotlin
BadgedBox(badge = { Badge() }) {
    Icon(Icons.Rounded.NotificationsActive, contentDescription = "Alerts")
}
BadgedBox(badge = { Badge { Text("3") } }) {
    Icon(Icons.Rounded.Email, contentDescription = "Inbox, 3 unread")
}
BadgedBox(badge = { Badge { Text("99+") } }) {
    Icon(Icons.Rounded.Notifications, contentDescription = "Notifications, more than 99")
}
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `badge` | `@Composable BoxScope.() -> Unit` |  | The Badge to show on the anchor. |
| `content` | `@Composable BoxScope.() -> Unit` |  | The anchor, usually an Icon. |
| `containerColor` | `Color` | `BadgeDefaults.containerColor` | Badge color, error by default. |

## Guidelines

Do:
- Use a dot for a new state and a number for a count.
- Remove the badge when there is nothing new.

Don't:
- Do not use badges as buttons.
- Do not show long text in a badge.

## Accessibility

- Put the count into the anchor's content description, for example Inbox, 3 unread.
- A dot badge without text needs a description of what changed.

## Related components

- [Navigation bar](https://m3e.ljzapps.app/docs/components/navigation-bar.md)
- [Icon button](https://m3e.ljzapps.app/docs/components/icon-button.md)