Badge

Anatomy

import {Badge} from '@staffbase/design';

<Badge />;

Examples

Variants

Empty (dot) badge

When no value is provided, the badge renders as a small dot indicator.

Truncated value

Use truncate to cap the displayed number at 9+.

Positioned over an element

Wrap a target element in a relative container, then place the Badge immediately after it. The position prop controls which corner the badge anchors to.

Inline

Use position="inline" to render the badge as an inline element alongside text or other content.

API reference

When to use

• To show a count of unread notifications or pending items anchored to an icon, avatar, or navigation item.
• To signal that new activity exists without revealing an exact count — use a dot badge (omit value) when presence alone is sufficient.
• To distinguish urgency or category through color when attaching a count to a UI element.

When not to use

• Don’t use a Badge for a status or category label on content — use Pill instead.
• Don’t use a Badge as an interactive action or button — use Button instead.
• Don’t use a Badge to show a count embedded in body text — use a plain number in the text instead.

How to use

Variants

• Use primary for standard notifications and new-item counts.
• Use secondary for lower-priority or secondary notification counts.
• Use critical for urgent or error-state counts, such as failed items requiring immediate attention.
• Use gamification for rewards, achievements, or point counts in a gamification context.
• Don’t choose a variant based on visual preference alone; match it to the semantic meaning of the notification.

Empty badge (dot)

• Omit value to render a dot indicator when an exact count is unavailable or unnecessary.
• Use the dot badge when you only need to convey that something is new, not how many items there are.
• Don’t rely on color alone — always pair the dot badge with a meaningful a11yDescription.

Truncation

• Use truncate when the count can exceed 9 and the exact number above 9 is not meaningful — the badge then displays 9+.
• Don’t use truncate when the exact count matters, such as a shopping cart total or an error count.

Position

• Use topRight for most anchored badges on icons, avatars, and navigation items.
• Use topLeft, bottomLeft, or bottomRight only when the element shape or layout requires a different anchor.
• Use position="inline" to place the badge alongside text or other inline content, such as a navigation label.
• Wrap the target element in a relative container and place the Badge immediately after it to anchor it correctly.

Accessibility

• Always provide a11yDescription — it is a required prop that gives screen readers a meaningful label for the badge value or state.
• Don’t rely on color alone to convey meaning; always pair color with the count or an a11yDescription that names the state.
• The badge is display-only and must never receive keyboard focus or act as an interactive trigger.

Content & UX copy

• Keep a11yDescription concise and specific; prefer “5 unread notifications” over “notifications”.
• Use a consistent naming pattern across the product, for example “N notifications” or “N unread messages”.
• For a dot badge, describe the state rather than a count, such as “New activity” or “Unread messages”.