Badge

Usage

Basic Count Badge

Display a count badge on any element. The badge center sits exactly on the corner of the child element.

<Badge count={5} aria-label="5 notifications">
  <Avatar user={user} />
</Badge>

<Badge count={12} aria-label="12 messages">
  <Button label="Messages" />
</Badge>

Empty Badge (Dot Indicator)

Omit count and icon to render a small dot indicator. Useful for presence or unread status.

{/* Empty badge - just a dot indicator */}
<Badge status="danger" aria-label="Unread">
  <Icon icon="mail" />
</Badge>

<Badge status="success" aria-label="Online">
  <Avatar user={user} />
</Badge>

Icon Badge

Display an icon instead of a count.

<Badge icon="bell" status="danger" aria-label="New alerts">
  <Button>Notifications</Button>
</Badge>

Positioning

Position the badge on any corner. The badge center aligns with the corner point.

<Badge count={1} position="top-right" aria-label="...">
  <Avatar user={user} />
</Badge>

<Badge count={2} position="top-left" aria-label="...">
  <Avatar user={user} />
</Badge>

<Badge count={3} position="bottom-right" aria-label="...">
  <Avatar user={user} />
</Badge>

<Badge count={4} position="bottom-left" aria-label="...">
  <Avatar user={user} />
</Badge>

{/* Center - useful when badge is the main focus */}
<Badge count={5} position="center" aria-label="...">
  <Avatar user={user} />
</Badge>

Shapes

Use the shape prop to control the badge shape. Without a shape prop, the badge renders as a pill that expands to fit content.

{/* Pill shape (default) - expands to fit content */}
<Badge count={123} aria-label="123 items">...</Badge>

{/* Circle */}
<Badge count={3} shape={0} aria-label="3 items">...</Badge>

{/* Triangle */}
<Badge count={3} shape={3} aria-label="3 items">...</Badge>

{/* Square */}
<Badge count={3} shape={4} aria-label="3 items">...</Badge>

{/* Pentagon */}
<Badge count={3} shape={5} aria-label="3 items">...</Badge>

Empty Shapes (Dot Indicators)

Shapes can also be used without content to create shaped dot indicators.

{/* Empty shaped badges - no count or icon */}
<Badge status="danger" shape={0} aria-label="Alert">...</Badge>
<Badge status="danger" shape={3} aria-label="Alert">...</Badge>
<Badge status="danger" shape={4} aria-label="Alert">...</Badge>

Hollow Empty Shapes

Empty shapes with the hollow variant for subtle indicators.

Count Overflow

When a shape is specified, counts over 9 display as "9+" in a circle. Pill shapes expand to show the full number.

Variants

Use the variant prop to switch between solid and hollow styles. Both variants can display counts, icons, or be empty.

{/* Solid - filled background */}
<Badge count={5} variant="solid" status="info" aria-label="5">
  <Avatar user={user} />
</Badge>

{/* Hollow - outlined style */}
<Badge count={5} variant="hollow" status="info" aria-label="5">
  <Avatar user={user} />
</Badge>

Status Colors

Badge integrates with the Status system for semantic coloring.

Hollow Variant with Status

In Containers

Badge automatically matches its outer border color to the container background using ContainerContext. This provides visual separation between the badge and its surroundings.

<Container>
  <Badge count={3} status="danger" aria-label="3 items">
    <Avatar user={user} />
  </Badge>
</Container>

<Container status="info">
  <Badge count={5} status="danger" aria-label="5 items">
    <Avatar user={user} />
  </Badge>
</Container>

Visibility Control

Use the show prop to control badge visibility. Note that count=0 displays "0" and does not auto-hide.

{/* Hidden badge */}
<Badge count={5} show={false} aria-label="5 notifications">
  <Avatar user={user} />
</Badge>

{/* count=0 displays "0" */}
<Badge count={0} aria-label="0 items">
  <Avatar user={user} />
</Badge>

Clickable Badge

Add an onClick handler to make the badge itself interactive, separate from the wrapped children. Supports keyboard navigation (Enter/Space).

<Badge count={3} aria-label="3 messages" onClick={() => openMessages()}>
  <Icon icon="chat" />
</Badge>

Props

* Required prop

Theme Variables

Badge appearance can be customized via theme variables in themeDetails:

// In theme.stylex.ts
export const themeDetails = stylex.defineVars({
  // Badge sizing
  badgeSize: themeSizing.spaceM,
  badgeDotSize: `calc(${themeSizing.spaceXS} * 2)`,
  badgeFontSize: themeSizing.font0,

  // Badge padding
  badgePaddingInline: `calc(${themeSizing.spaceXS} * 0.75)`,
  badgePaddingBlock: `calc(${themeSizing.spaceXS} * 0.25)`,

  // Badge borders
  badgeBorderWidth: `calc(${themeSizing.spaceXS} * 0.5)`,
  badgeInnerBorderWidth: `calc(${themeSizing.spaceXS} * 0.4)`,

  // Badge icon
  badgeIconSize: `calc(${themeSizing.spaceM} * 0.65)`,
});

Accessibility