How to Use
Badge
Badge attaches a numeric count, text label, or status dot to a child element. It wraps its child and positions the badge content at one of four corners (top-right by default). Use Badge for unread notification counts on icons, online/offline status dots on avatars, or numeric indicators on navigation items.
Notification Counts
The content prop accepts a number or string. Wrap any element — an icon button, avatar, or generic span — with Badge to show a count at the top-right corner. Use color="danger" (red) for urgent counts like errors or critical notifications, color="primary" for standard counts like unread messages, and color="warning" for moderate alerts. The badge position adjusts automatically based on the wrapped element's size.
<div className="flex items-center gap-6">
<Badge content={5} color="danger">
<Button variant="soft" aria-label="Notifications">
<span>🔔</span>
</Button>
</Badge>
<Badge content="99+" color="primary">
<Button variant="soft" aria-label="Messages">
<span>✉</span>
</Button>
</Badge>
<Badge content={3} color="warning">
<Button variant="soft" aria-label="Tasks">
<span>✓</span>
</Button>
</Badge>
</div>Status Dots
Set isDot to true to show a small colored dot instead of a numeric badge. This is ideal for online/offline/away presence indicators on avatars or user cards. The placement prop controls where the dot appears — top-right (default), bottom-right, top-left, or bottom-left. Use color="success" (green) for online, color="warning" (amber) for away, color="danger" (red) for offline or do-not-disturb.
<div className="flex items-center gap-6">
<Badge isDot color="success" placement="bottom-right">
<Avatar name="John Doe" />
</Badge>
<Badge isDot color="warning" placement="bottom-right">
<Avatar name="Jane Smith" />
</Badge>
<Badge isDot color="danger" placement="bottom-right">
<Avatar name="Alex Lee" />
</Badge>
</div>Accessibility
Badge uses aria-label on its inner wrapper to announce the badge content to screen readers. When content is a number, the aria-label reads "X notifications" or "X items". The dot variant uses aria-label "Online status" or similar based on the color. Ensure the wrapped element has its own accessible label for context.
Props Reference
All available props for Badge. See the full API reference page for interactive playground examples.
| Prop | Type | Default | Description |
|---|---|---|---|
| content | string | number | ReactNode | — | Badge content (count or text). |
| color | "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "default" | Badge color. |
| variant | "solid" | "soft" | "bordered" | "solid" | Badge variant. |
| placement | "top-right" | "top-left" | "bottom-right" | "bottom-left" | ... | "top-right" | Badge position relative to child. |
| isDot | boolean | false | Render as a small dot. |
| isInvisible | boolean | false | Hide the badge. |
| max | number | 99 | Max count before showing +N. |
| size | "xs" | "xs-sm" | "sm" | "md" | "lg" | "xl" | "md" | Badge size. |
| showOutline | boolean | false | Show an outline ring. |
Best Practices
- ◆Use color="danger" (red) for urgent counts that need immediate attention; color="primary" for standard informational counts
- ◆Use placement to control which corner the badge appears on — bottom-right is standard for avatar presence indicators
- ◆For dot badges, color="success" signals online/active, color="warning" signals away/idle, color="danger" signals offline/dnd
- ◆The badge inherits its size relative to the child element — wrapping a large element produces a proportionally sized badge
- ◆Combine Badge with Button (isIconOnly) for notification bell icons, message icons, or alert icons in navigation headers