Badge Indicator
Overlay notification badges on buttons, icons, avatars, and other elements.
BadgeIndicator is the positioned version of Badge. It wraps a target element and places a count, dot, or custom badge over one of its corners. Use it for unread notifications, online status, cart quantities, and similar contextual indicators.
Basic usage
<BadgeIndicator count={3} tone="danger" variant="solid">
<Button iconLeft={<BellIcon />}>Notifications</Button>
</BadgeIndicator>The indicator is non-interactive (pointer-events: none) so clicks continue to reach the wrapped button or link.
Positions
Use position to choose the corner:
<BadgeIndicator position="top-right" count={3}>...</BadgeIndicator>
<BadgeIndicator position="top-left" dot>...</BadgeIndicator>
<BadgeIndicator position="bottom-right" count={8}>...</BadgeIndicator>
<BadgeIndicator position="bottom-left" dot>...</BadgeIndicator>The default is top-right, which is the usual notification-badge placement.
Counts, dots, and custom content
count displays a numeric or string value. Combine it with max to shorten large numbers and showZero when zero should remain visible. Use dot for a compact status indicator.
<BadgeIndicator count={128} max={99}>...</BadgeIndicator>
<BadgeIndicator count={0} showZero>...</BadgeIndicator>
<BadgeIndicator dot tone="success" pulse>...</BadgeIndicator>For complete control, pass a Badge or another React node through badge:
<BadgeIndicator badge={<Tag size="xs" tone="primary">New</Tag>}>
<Button>Inbox</Button>
</BadgeIndicator>Styling and state
All Badge presentation props are forwarded to the generated badge: tone, variant, size, shape, icon, loading, disabled, removable, onRemove, aria-label, and className-independent content options such as count, dot, max, and showZero.
pulse adds a subtle attention animation around the indicator. It automatically respects prefers-reduced-motion. Use hidden to keep the wrapped target visible while suppressing the indicator.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Element shown below the indicator. |
badge | ReactNode | — | Custom indicator content. When provided, it replaces the generated Badge. |
position | top-right | top-left | bottom-right | bottom-left | top-right | Corner where the indicator is anchored. |
hidden | boolean | false | Hides the indicator without removing the wrapped element. |
pulse | boolean | false | Adds a subtle attention pulse. |
className | string | — | Class applied to the wrapper. |
| Badge props | BadgeProps except children and className | — | count, dot, max, showZero, tone, variant, size, shape, icon, and interaction/state props. |
Badge vs BadgeIndicator
Use Badge when the badge participates in normal inline layout. Use BadgeIndicator when it must float over another element, especially at the upper-right corner. BadgeIndicator is a composition helper, not a replacement for the base Badge component.