Badge

Show an unread count. Flag a status. Indicate new content.

import { Badge } from '@dashforge/tw';
import { Bell } from 'lucide-react';

<Badge content={3} color="danger">
  <Bell />
</Badge>

Quick Start

<Badge content={12}><Bell /></Badge>
<Badge dot color="success"><Avatar src="/u/jane.png" /></Badge>
<Badge content={150} max={99} color="primary"><Inbox /></Badge>
<Badge invisible={count === 0} content={count}><Cart /></Badge>

Examples

Content vs dot (with overflow)

Two modes — number content with max overflow, or boolean dot indicator:

import { Badge, IconButton } from '@dashforge/tw';
import { Bell } from 'lucide-react';

<Badge content={3} color="danger">
  <IconButton aria-label="Notifications (3 unread)"><Bell /></IconButton>
</Badge>

<Badge content={150} max={99} color="warning">
  <IconButton aria-label="Notifications (150 unread)"><Bell /></IconButton>
</Badge>

<Badge dot color="success">
  <IconButton aria-label="Online"><Bell /></IconButton>
</Badge>

Max overflow

When content exceeds max, the badge renders {max}+ instead. Defaults: max={99}.

<Badge content={150} max={99} color="primary"><Bell /></Badge>
{/* renders "99+" */}

<Badge content={9999} max={999}><Bell /></Badge>
{/* renders "999+" */}

showZero

By default, content === 0 hides the badge. Pass showZero to keep it visible:

<Badge content={0} showZero color="info"><Bell /></Badge>
{/* renders "0" */}

Invisible

Toggle visibility imperatively without unmounting:

<Badge content={count} invisible={count === 0}>
  <Cart />
</Badge>

This is different from showZero — invisible accepts an arbitrary boolean (e.g. tied to a feature flag or visibility toggle).

Placement (4 corners)

import { Avatar, Badge, Stack } from '@dashforge/tw';

<Stack direction="row" gap={4}>
  <Badge content={3} placement="top-right"><Avatar name="A" size="lg" /></Badge>
  <Badge content={3} placement="top-left"><Avatar name="A" size="lg" /></Badge>
  <Badge content={3} placement="bottom-right"><Avatar name="A" size="lg" /></Badge>
  <Badge content={3} placement="bottom-left"><Avatar name="A" size="lg" /></Badge>
</Stack>

Overlap — rectangular vs circular

The overlap prop tunes badge positioning to the anchor's shape. Default is rectangular (suits square/rectangular anchors like buttons, icons, cards). Use circular when the anchor is a circular shape (most importantly <Avatar>) — applies a 14% inset so the badge sits naturally on the circle edge.

import { Avatar, Badge, IconButton } from '@dashforge/tw';
import { Bell } from 'lucide-react';

{/* rectangular — for square anchors like buttons */}
<Badge content={3} overlap="rectangular">
  <IconButton aria-label="Notifications"><Bell /></IconButton>
</Badge>

{/* circular — adds 14% inset, tuned for Avatar */}
<Badge content={3} overlap="circular">
  <Avatar name="A" size="lg" />
</Badge>

With ring (Avatar pattern)

Default withRing is true — adds ring-neutral-50 around the badge for separation from the anchor (useful when the badge sits on a similarly-colored background, e.g. an Avatar with primary tone).

<Badge content={3} color="danger" withRing>
  <Avatar src="/u/jane.png" />
</Badge>

Disable for flush badges:

<Badge content={3} withRing={false}><Bell /></Badge>

Bridge integration

{/* Hide the unread badge from users without inbox access */}
<Badge content={unreadCount}
  access={{ requires: 'inbox.view', when: 'denied:hide' }}
>
  <Inbox />
</Badge>

{/* Show only when feature flag is on */}
<Badge content={pendingApprovals}
  visibleWhen={(engine) => engine.getValue('flags.approvals') === true}
>
  <Inbox />
</Badge>

Standalone variant

<Badge> is wrapper-only — it expects a child to anchor to. For an inline standalone pill (e.g. a tag in a Table cell), use <Chip> instead.

Theme defaults

Configure <Badge> defaults application-wide.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Badge: {
      defaults: { color: 'danger', placement: 'top-right', overlap: 'rectangular' },
    },
  },
});

Configurable axes (BadgeVariantProps):

Non-visual axes (content, dot, max, showZero, invisible, access, visibleWhen) are not theme-configurable — state and data-driven per-instance.

Precedence chain (lowest → highest):

1. Internal component defaults (baked-in fallback).
2. theme.components.Badge.defaults (application-wide).
3. Instance prop (<Badge color="primary" placement="bottom-right" />) — wins over theme.
4. sx — appended to the badge indicator and wins over conflicting classes via tailwind-merge.

TypeScript: theme.components.Badge.defaults autocompletes to the four axes above.

Reactivity: useComponentDefaults('Badge') subscribes to the theme store — patchTheme re-renders every mounted instance inheriting the changed axis.

API

Props

Slots & slotProps

<Badge> is a small compound component with 2 named slots. Each slot accepts a { className?: string } override via slotProps:

<Badge
  content={7}
  slotProps={{
    root: { className: 'inline-block' },
    badge: { className: 'text-[10px] font-mono' },
  }}
>
  <IconButton aria-label="Notifications"><BellIcon /></IconButton>
</Badge>

Use sx for a class override on the badge indicator itself (shortcut for slotProps.badge.className); use slotProps when you also need to reach the positioning wrapper.

A11y

• The badge has aria-hidden="true" — it's purely decorative on top of the anchor.
• Put the semantic count on the anchor's aria-label. Example:

<Badge content={unread} color="danger">
  <IconButton aria-label={`Notifications (${unread} unread)`}>
    <Bell />
  </IconButton>
</Badge>

Screen readers will announce "Notifications (3 unread), button" — the badge is just visual emphasis.

Notes

• ring-neutral-50 instead of ring-white — the neutral palette auto-inverts via CSS var swap, so ring-neutral-50 works in both light and dark mode without dark: override. See Design decisions.
• overlap="circular" exists for Avatar: rectangular anchors look fine with default overlap, but Avatars need a slight inset (14%) so the badge sits on the circle edge — that's what the circular value does.
• For an inline pill (e.g. status next to a record), use <Chip>, not Badge. Badge requires a child to anchor to.