Skip to main content
Skip to Content

Anchors a count, label, or status dot to the corner of another element

12New

Installation

  1. Install the package

    terminal
    npm install @hashintel/ds-components
  2. 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 hide to 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.

3

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.

9999+999+

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.

New

Colors

Give each color one meaning per surface — red for needs-attention counts, green for presence — and keep it consistent.

33333333

Shape

The pill is round by default; square gives it a small corner radius that sits better against rectangular anchors like tiles and thumbnails.

55

Position

position picks the corner the badge overhangs: top-left, top-right (default), bottom-left, bottom-right.

2222

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).

44

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 max rather 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.

app.tsx
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

PropTypeDescription
children
ReactNode
content
ReactNode
shape
"square" |⁠ "round"
default: "round"
color
ChipColor
default: "grey"
position
"top-left" |⁠ "top-right" |⁠ "bottom-left" |⁠ "bottom-right"
default: "top-right"
alignTo
"circle"
hide
boolean
max
number
default: 99

BaseBadge

PropTypeDescription
children
ReactNode
content
ReactNode
position
"top-left" |⁠ "top-right" |⁠ "bottom-left" |⁠ "bottom-right"
default: "top-right"
alignTo
"circle"
hide
boolean

Was this page helpful?

On this page