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

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.