Anchors a count, label, or status dot to the corner of another element
Installation
-
Install the package
terminal npm install @hashintel/ds-components -
Import the component
app.tsx import { Badge, Button } from "@hashintel/ds-components"; export const NotificationsBell = () => ( <Badge content={3} color="red"> <Button variant="subtle" iconName="bell" tooltip="Notifications" /> </Badge> );
When to use
- Do: Use Badge to count new or unseen items on an icon, button, or navigation item — unread notifications, pending drafts, flagged entities.
- Do: Use a dot (omit
content) when "something changed" matters more than how many — presence on an avatar, unseen activity on a tab. - Do: Use
hideto clear the badge once its items have been seen, keeping the anchor in place.
When not to use
- Don't: Don't use Badge for standalone labels, statuses, or tags that aren't attached to another element — use Chip.
- Don't: Don't use Badge for page or section-level messages — use Banner.
- Don't: Don't make the badge the click target — it ignores pointer events; put the action on the anchor.
- Don't: Avoid badging several sibling items at once — competing badges cancel each other's urgency.
Examples
Basic
Wrap the anchor as children and pass the badge's own content as content. The default badge is grey, round, and overhangs the top-right corner.
Dot
Omit content to collapse the badge to a small solid dot — for "something changed" when the count doesn't matter. Dots are always round, no matter what shape is set to.
Capping counts
Numeric content above max (default 99) renders as {max}+, so stale counts stay honest and short. Strings pass through untouched.
Text and icon content
content takes any React node — a short word, an icon, or both. Prefer counts; reserve words for genuinely new things ("New"), and keep them to one word.
Colors
Give each color one meaning per surface — red for needs-attention counts, green for presence — and keep it consistent.
Shape
The pill is round by default; square gives it a small corner radius that sits better against rectangular anchors like tiles and thumbnails.
Position
position picks the corner the badge overhangs: top-left, top-right (default), bottom-left, bottom-right.
Circular anchors
A circular anchor's bounding-box corner is empty, so a corner badge floats off the shape (left). Set alignTo="circle" to pull it onto the circle's edge (right).
Behavior
- The badge is centered on its corner, but its inner edge never crosses the anchor's midline — long content like "Processing" grows away from the anchor, not across it.
- The badge ignores pointer events; hovers and clicks land on the anchor beneath it.
Content
- Keep badge text to a count or one short word — "3", "99+", "New". Longer strings overhang the anchor by at least half their width.
- Cap counts with
maxrather than showing exact large numbers — "99+" reads faster and stays truthful as counts drift. - Clear the badge (
hide) once the user has seen what it announces — a badge that never clears stops meaning anything.
Accessibility
Badge renders no ARIA of its own, so its meaning must live on the anchor.
What Badge provides
- Plain inline
<span>s: the pill's text sits in the accessibility tree directly after the anchor, so a screen reader hears "Inbox", then "3". - Dot badges render no text at all — they are invisible to assistive technology.
What you must do
- Fold the badge's meaning into the anchor's accessible name —
aria-label="Notifications, 3 unread"on the anchor explains what a bare "3" can't. - Never convey state through a dot or its color alone — mirror it in the accessible name ("Alex Leon (online)"), for screen readers and color-blind users.
Styling
For a fully custom overlay, use BaseBadge which positions arbitrary content on a corner of children and leaves its appearance to you.
import { Avatar, BaseBadge, LoadingSpinner } from "@hashintel/ds-components";
export const SyncingIntegration = () => (
<BaseBadge
content={<LoadingSpinner size="xxs" />}
position="bottom-right"
alignTo="circle"
>
<Avatar alt="GitHub integration (syncing)" placeholder={{ icon: "plug" }} />
</BaseBadge>
);API reference
Badge
| Prop | Type | Description |
|---|---|---|
| children | ReactNode | The element the badge attaches to. |
| content | ReactNode | The badge's own content. Omit to render a small dot with no content. |
| shape | "square" | "round" default: "round" | |
| color | ChipColor default: "grey" | |
| position | "top-left" | "top-right" | "bottom-left" | "bottom-right" default: "top-right" | Which corner of the anchor the badge overhangs. |
| alignTo | "circle" | Set to "circle" to align the badge to a circular anchor (e.g. a round avatar). |
| hide | boolean | When true, the badge is not rendered — only the anchor (children) shows. |
| max | number default: 99 | Caps numeric content: a value above max renders as {max}+ (e.g. content={100} with max={99} shows "99+"). Ignored for non-numeric content. |
BaseBadge
| Prop | Type | Description |
|---|---|---|
| children | ReactNode | The element the overlay attaches to (e.g. an icon). |
| content | ReactNode | The overlay placed on the chosen corner of children. |
| position | "top-left" | "top-right" | "bottom-left" | "bottom-right" default: "top-right" | Which corner of the anchor the overlay overhangs. |
| alignTo | "circle" | Set to "circle" to align the overlay to a circular anchor (e.g. a round avatar). |
| hide | boolean | When true, the overlay is not rendered — only the anchor shows. |
Was this page helpful?