Skip to main content

Badge

A simple, accessible badge component for displaying status, counts, or labels. Supports links, buttons, and numeric indicators with overflow handling.

Usage​

Basic usage​

import { Badge } from '@nofinite/nui';

<Badge>Beta</Badge>;

With typical interaction​

<Badge onClick={() => console.log("clicked")} pill>
  5
</Badge>

<Badge href="/profile" variant="primary">
  View
</Badge>

Variants​

<Badge variant="default">Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="danger">Danger</Badge>

Available variants:

  • default – Neutral badge, standard background and border.
  • primary – Emphasizes important badges, primary theme color.
  • success – Indicates positive state (e.g., success, online).
  • warning – Indicates caution or alert.
  • danger – Indicates error or critical state.

Guidelines:

  • Use primary for actionable badges or links.
  • Use success, warning, or danger for semantic state indicators.
  • Use default for general labels.

Sizes​

<Badge size="sm">Small</Badge>
<Badge size="md">Medium</Badge>
<Badge size="lg">Large</Badge>

Available sizes:

  • sm – Smaller font and padding
  • md – Default
  • lg – Larger font and padding

Sizes can be combined with variants and shape modifiers:

<Badge variant="success" size="lg" pill>
  99+
</Badge>

States​

<Badge disabled>Disabled</Badge>
<Badge dot ariaLabel="Online" />
<Badge loading>Loading</Badge>
  • disabled – Interaction is blocked and visually muted (if implemented).
  • dot – Small indicator without visible content, requires ariaLabel.
  • loading – Optional state for pending interactions (implementation-dependent).

Native Props / Composition​

The Badge supports standard HTML attributes depending on the rendered element (<span>, <a>, or <button>):

<Badge
  className="my-badge"
  title="Tooltip"
  aria-label="5 notifications"
  onClick={() => console.log('clicked')}
>
  5
</Badge>

Props​

PropTypeDefaultDescription
variant"default" | "primary" | "success" | "warning" | "danger"defaultVisual style of the badge
size"sm" | "md" | "lg"mdBadge size
pillbooleanfalseRenders the badge with fully rounded corners
dotbooleanfalseRenders a small circular indicator without visible content
countnumber—Numeric value for the badge; used with overflow handling
maxnumber—Maximum count before displaying as "max+"
hrefstring—Renders the badge as an anchor element
onClick() => void—Renders the badge as a button
ariaLabelstring—Custom accessible label; auto-generated if omitted for numbers
iconLeftReact.ReactNode—Optional icon before content
iconRightReact.ReactNode—Optional icon after content
childrenReact.ReactNode—Content inside the badge
classNamestring""Additional CSS classes
titlestring—Native title tooltip
...restReact.HTMLAttributes<HTMLElement>—Forwarded native attributes

Behavior Notes​

  • Automatically renders as <span>, <a> (when href is provided), or <button> (when onClick is provided).
  • Numeric badges automatically generate an accessible label (e.g., "5 notifications").
  • Dot badges hide content visually but remain accessible via ariaLabel.
  • The pill prop renders the badge with fully rounded corners.
<Badge count={120} max={99} pill>
  120
</Badge>

Accessibility​

  • Renders as <span> by default, <a> with href, or <button> with onClick.
  • Keyboard focus is enabled for interactive variants.
  • Automatically generates aria-label for numeric badges.
  • Always provide ariaLabel for dot-only or icon-only badges.
<Badge dot ariaLabel="Online status" />

Layout​

  • Uses inline-flex by default.
  • Maintains consistent spacing between icons and content.
  • Use BadgeGroup to manage multiple badges with overflow handling:
<BadgeGroup
  max={3}
  items={[
    <Badge>React</Badge>,
    <Badge>Next.js</Badge>,
    <Badge>TypeScript</Badge>,
    <Badge>Node</Badge>,
  ]}
/>
  • Supports className and style for layout customization.

Best Practices​

Do​

  • Use badges for short labels, counts, and status indicators.
  • Use dot for presence or notification indicators.
  • Group multiple badges using BadgeGroup for consistent spacing.
  • Provide ariaLabel for numeric-only or icon-only badges.

Don’t​

  • Avoid long or descriptive text inside badges.
  • Do not use badges as primary action buttons unless explicitly interactive.
  • Do not hide critical information behind unlabeled dot indicators.