When to Use
Example: unread badges in message list
- Indicating unread count on icons such as notifications or messages
- Showing online/offline presence on avatars or contact lists
- Highlighting new or updated items in navigation or lists
- Avoid using Badge purely for decoration — it should convey meaningful status
Usage Guidelines
DO
Use Dot for presence/absence cues (e.g. new notifications) and Count for specific counts like "N unread"
Don’t
Don't place multiple badges on the same host element — visually confusing and imprecise
DO
Place the badge at the top-right corner of the host element, avoiding obscuring critical content
Don’t
Don't use badges purely for decoration — they carry semantic meaning and overuse dilutes that
Interaction Behavior
| State | Behavior |
|---|---|
| Static display | Shown alongside the host element; does not receive independent pointer events |
| Count update | Recommend a scale animation on number change for visual feedback |
| Appear | Scale from 0 to 1, duration ≈ 200ms |
| Disappear | Reverse scale to 0, duration ≈ 200ms |
| Collapse | count > maxCount shows {maxCount}+, no longer increases |
Accessibility
| Requirement | Implementation |
|---|---|
| Semantic label | Host element or badge itself uses aria-label="3 unread messages" |
| Dot type | aria-label="New notifications" indicating presence/absence |
| Live updates | Wrap with aria-live="polite" to announce count changes |
| Contrast | Badge background-to-host/page contrast ≥ 3:1 |
| Pointer events | Badge has pointer-events: none to not interfere with host interactions |