Badges

Badges are used to show a notification, a count, or a status indicator attached to another object (like a navigation rail item, a tab, or an icon button).

Introduction

The MD3 Expressive Badge is a compact status indicator. It can be used as a simple decorative dot to signal new activity, or as a container for numerical counts (e.g., unread messages). Integrated with Framer Motion, badges appear and disappear with a smooth spring-based scaling animation.

Anatomy

• Container: A rounded surface that holds the content. Uses the theme's error color roles by default for maximum visibility.
• Content (Optional): A number or brief text string. If omitted, the badge renders as a small dot.
• Anchor (via BadgedBox): The underlying element the badge is attached to.

Variants

Small (Dot) Badge

A small, purely visual indicator (6x6dp) used to signal that something has changed without providing a specific count.

Large (Count) Badge

A larger container (16dp height) that holds numeric or text content. It expands horizontally to fit the content.

Features

Max Count Handling

For numeric badges, you can set a max value (e.g., 99). If the count exceeds this value, the badge will automatically display as "99+".

BadgedBox Wrapper

The BadgedBox component makes it easy to attach a badge to any element. it handles the absolute positioning and offsets automatically.

Usage

Simple Dot Badge

import { Badge, BadgedBox, IconButton, Icon } from "@bug-on/m3-expressive";

<BadgedBox badge={<Badge />}>
  <IconButton icon={<Icon name="notifications" />} />
</BadgedBox>

Numeric Badge with Max Count

<BadgedBox badge={<Badge max={99}>{150}</Badge>}>
  <IconButton icon={<Icon name="mail" />} />
</BadgedBox>

Best Practices

Do

• Use badges to provide time-sensitive or important status updates.
• Keep badge content very short (typically numbers or 1-2 characters).
• Use the max prop to prevent badges from becoming too wide.
• Place badges in the top-trailing corner of the anchor element.

Don't

• Don't use badges for information that isn't urgent or secondary.
• Don't put long words or sentences inside a badge.
• Avoid using too many badges on a single screen, as it can be visually overwhelming.

Accessibility

• Decorative Dots: If a badge is just a dot, ensure the anchor has an aria-label that includes the status (e.g., "Notifications (new)").
• Screen Readers: Badges with content are read alongside the anchor's text.
• Motion: Scaling animations respect prefers-reduced-motion settings.

API Reference

Badge

BadgedBox