Badge React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Badge from @/components/ui/badge.

import { Bell } from "lucide-react"
import { Badge, BadgeAnchor } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

export function OrderHeader({ unread, onOpenInbox }: { unread: number; onOpenInbox: () => void }) {
  return (
    <div className="flex items-center gap-3">
      <Badge tone="success" dot>Paid</Badge>
      <Badge tone="warning">Low stock</Badge>
      <BadgeAnchor offset={5} badge={<Badge variant="solid" tone="danger" size="sm" count={unread} aria-hidden />}>
        <Button variant="soft" size="icon" radius="full" aria-label={`Notifications, ${unread} unread`} onClick={onOpenInbox}>
          <Bell />
        </Button>
      </BadgeAnchor>
    </div>
  )
}

Props

• childrendefault "Nou"
  ReactNode

  The label. Long labels truncate with an ellipsis. Leave it empty (with no icons or count) and the badge becomes a status dot.

• variantdefault "soft"
  "solid" | "soft" | "outline"

  soft (a tinted pill) for statuses, solid for counts and the one label that must stand out, outline for filters and quiet tags.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Semantic color from the design tokens: success for paid or online, warning for low stock, danger for cancelled or failed, info for in progress. Pair color with the text, never color alone.

• colordefault ""
  string

  Any CSS color. Replaces the tone in every variant; text on a solid fill turns black or white by lightness. Leave empty to use the tone.

• sizedefault "md"
  "sm" | "md" | "lg"

  Height 20 / 24 / 28px with 11 / 12 / 13px text and 12 / 12 / 14px icons.

• radiusdefault "full"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape: 0 / 4 / 6 / 8px or a pill. Badges default to pills (a deliberate difference from controls); the square steps suit tag-like labels.

• dotdefault false
  boolean

  A leading status dot in the tone (in the text color on a solid badge).

• pulsedefault false
  boolean

  The dot pings, for live, recording or online. Implies dot. Decorative (hidden from screen readers); under reduced motion the dot stays still.

• maxdefault 99
  number

  Counts above it read "99+". Values below 1 fall back to 99. Only used with count.

• showZerodefault false
  boolean

  A count of 0 scales the badge away unless this is set. Try it on the bell: tap it to mark all as read.

• localedefault ""
  string

  Formats the count through Intl, e.g. "en-US" turns 1250 into 1,250 and "de-DE" into 1.250. Empty uses the reader's locale; pass one for server-rendered counts of 1000 or more so the grouping matches after hydration.

• removeLabeldefault "Remove"
  string

  aria-label of the remove button, e.g. "Remove the Brooklyn filter". Only used with onRemove.

• disableddefault false
  boolean

  Dims the badge (a count too) and hides the remove button. With asChild the link gets aria-disabled, leaves the tab order and ignores clicks.

• asChilddefault false
  boolean

  Renders your single child (an <a>, a router Link, a button) as the badge, with a hover tint, a press dip and a focus ring. asChild badges have no remove button, since a button inside a link is invalid. The demo swaps in a link.

• count
  number

  Shows this number instead of children and animates every change: the digits slide, the width follows on a spring and the badge bumps when it grows. Negative values clamp to 0, fractions round. The demo's bell drives it with the + and - buttons.

• leftIcon
  ReactNode

  An icon before the label. Unsized svgs follow the size (12 / 12 / 14px).

• rightIcon
  ReactNode

  An icon after the label, like an arrow on a link badge.

• onRemove
  () => void

  Shows a round x button that calls it on click, tap, Enter, Backspace or Delete. The click does not bubble, so a chip inside a clickable row removes itself without opening the row.

• classNames
  Partial<Record<"dot" | "icon" | "label" | "count" | "remove", string>>

  Extra classes for the inner parts: the status dot, each icon wrapper, the label, the count and the remove button.

• className
  string

  Extra classes for the badge itself, merged last. Override the tone vars here, e.g. [--tone-foreground:white].

Parts

FAQ

Used in

More React data display components