A Badge attaches to the top-right corner of host elements like icons or avatars, conveying either "new content available" or "a specific count." The Dot type shows only a circle, indicating presence/absence; the Count type shows a number, collapsing to 99+ when maxCount is exceeded.
Anatomy
┌─ Host Element ────────────┐
│ ┌─Count─┐ │
│ │ 99+ │ │ ← background + number
│ └───────┘ │
└───────────────────────────┘
- Container — Rounded background (Count:
--ds-radius-sm; Dot: 8×8px circle)
- Content — Count type shows a number; Dot type is an empty circle
- Anchor — Badge is absolutely positioned at the
position: relative container's top-right corner
Usage Guidelines
✅ Do
- Use Dot for presence/absence cues (e.g. new notifications), not for conveying specific quantities
- Use Count for specific counts like "N unread", with an appropriate
maxCount (default 99)
- Place the badge at the top-right corner of the host element, avoiding obscuring critical content
- Hide the badge when count is 0 by default (
showZero: false) to avoid visual noise
❌ Don't
- Don't place multiple badges on the same host element — visually confusing and imprecise
- Don't use badges purely for decoration — they carry semantic meaning and overuse dilutes that
- Don't display excessively large numbers in Count type (must collapse beyond
maxCount)
- Don't apply badges to non-icon/avatar host elements (body text, button labels, etc.)
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 |
