Question 1

What is a shadcn badge?

Accepted Answer

A shadcn badge is a small inline pill component for labels, statuses, counts, and tags — the little rounded elements you see next to navigation items ("3 new"), beside titles ("Beta"), or inside tables ("Active", "Expired"). It's built on the shadcn/ui Badge primitive (four semantic variants driven by class-variance-authority) and styled with Tailwind CSS. Each example in this gallery is a single self-contained TSX file — copy, paste, and ship.

Question 2

Are these badge examples free?

Accepted Answer

Yes. Every badge example on shadcn.io is free to copy and use in personal or commercial projects. There's no gated source, no attribution requirement, and no runtime dependency on shadcn.io. Browse any example, view the code, run the installer, and move on.

Question 3

How is a Badge different from a Button or a Chip?

Accepted Answer

A Badge is a display element — it labels or describes adjacent content and is usually not interactive. A Button is an action trigger — users click it to do something. A Chip is typically a removable tag (think multi-select filter inputs) with an attached dismiss icon. If your element is clickable and performs an action, use a Button with small styling. If it toggles a filter, use a Toggle or a Chip (in shadcn/ui, combine Badge + a Dismiss icon).

Question 4

When should I use a Badge versus an Alert or a Toast?

Accepted Answer

Badges label inline: attach them to a specific piece of content ("Post — Draft", "User — Premium", "Feature — New"). Alerts banner a whole page section with status information. Toasts float above the page for transient confirmation. Pick by scope: a badge attaches to ONE thing, an alert attaches to a REGION, a toast announces a TRANSIENT event.

Question 5

Which badge variant should I pick?

Accepted Answer

Standard (solid primary) for neutral status labels that need moderate emphasis ("New", "Beta"). Secondary (muted background) for low-priority tags that shouldn't compete with surrounding content (categories, subtle meta). Outline (transparent background, border) when the badge sits on a colored surface and you want it to feel lighter. Destructive (red) for errors, expired states, or negative statuses. Mix sparingly — four competing variants in one list becomes visual noise.

Question 6

How do I add an icon inside a badge?

Accepted Answer

See the badge-with-icon examples. Drop a Lucide React icon (or any SVG) as the first child of Badge, sized h-3 w-3, followed by a small gap (`gap-1` or `gap-1.5`), then the label text. Icon-on-right uses the same pattern with the icon as the last child instead. Keep icons monochrome and at the same color as the text — multicolored icons inside a badge tend to muddy the visual.

Question 7

How do I build a count badge (the little red 3 on a bell icon)?

Accepted Answer

Use the circular-badge-with-count example. Absolute-position a small Badge (size-5, rounded-full, bg-destructive) at the top-right corner of a parent container (`relative`) that holds your anchor element. Set `-top-1 -right-1` offsets so the badge sits just outside the anchor's bounding box. Use numeric text with `tabular-nums` so single/double-digit counts don't wiggle; render "9+" instead of "12" when the count exceeds 9 for tighter badges.

Question 8

Should badges be clickable / wrap in <a>?

Accepted Answer

Sometimes — see the badge-with-link example. Wrap Badge in `<Link>` (from next/link) and give the badge `hover:bg-accent` to hint interactivity. Use this for tag-filter links or category hops. DO NOT nest an interactive Button inside a Badge — that's confusing semantically (button inside label). If you need real click behavior ("dismiss this tag"), use a Chip pattern with a dedicated dismiss button inside the badge, not the whole badge as a button.

Question 9

How do I install a badge example?

Accepted Answer

Run the `npx shadcn@latest add` command shown under the Installation heading on any example's detail page. The shadcn CLI copies the example's TSX source into your project at `components/examples/badge/…`, plus the shadcn/ui Badge primitive if you don't already have it. Badge is a thin component — the install is fast and the customisation surface is all CSS variables.

Question 10

How do I add a custom badge variant (e.g. "success")?

Accepted Answer

Edit `components/ui/badge.tsx` — it uses class-variance-authority (cva) under the hood. Add a new entry to the `variants.variant` object: `success: "border-transparent bg-emerald-500 text-white hover:bg-emerald-500/80"`. Then use it via `Saved`. For CSS-variable-driven theming, define `--success` / `--success-foreground` in your globals.css and reference them with `bg-success text-success-foreground` so dark mode works automatically.

Question 11

How do I size badges for different contexts?

Accepted Answer

The default badge size works for most inline usage. For dense data tables, override to `text-[10px] px-1.5 py-0`. For hero labels ("NEW FEATURE" in a landing page), scale up with `text-sm px-3 py-1`. The Badge primitive doesn't ship a `size` prop — you customise via className. Keep a consistent size per context so the visual rhythm of the page stays predictable.

Question 12

Can I animate a badge (e.g. pulse for unread)?

Accepted Answer

Yes — Tailwind's `animate-pulse` works out of the box on the badge element for an attention-grabbing pulse. For a more controlled effect, wrap the badge with a `motion/react` component and animate scale + opacity on mount. For the "ping" effect (a ring that radiates outward from a notification dot), pair `animate-ping` on an absolutely-positioned span behind the badge. Reserve animations for genuinely time-sensitive status — perpetual pulsing becomes annoying fast.

Question 13

Which libraries do badge examples depend on?

Accepted Answer

shadcn/ui Badge (the styled wrapper generated into your project by the CLI), Tailwind CSS (styling), class-variance-authority (the variant API), and Lucide React (icons). TypeScript is assumed. React 19 is the baseline. No state library — badges are pure render. Some examples add motion/react for entrance flourishes; that's optional.

Question 14

Are badge examples accessible for screen reader users?

Accepted Answer

Mostly yes — Badge renders as a plain `

` or `` with text content, which SR users read as part of the surrounding flow. For badges that convey status ("Active", "Expired"), the label text itself is the semantic. For purely decorative badges ("NEW" visual flair), use `aria-hidden="true"` so SR users skip them. For count badges, include the unit so the number makes sense ("3 new notifications", not just "3") — use `aria-label` or visually-hidden text.

Question 15

Can I use these badge examples with React Server Components?

Accepted Answer

Yes — Badge is pure render, so it works cleanly as a Server Component. No interactive state, no event handlers. The wrapper patterns (count badges with an anchor element) are also pure render unless the anchor itself is interactive (a button opening a notifications panel), in which case only that anchor needs a client boundary.

Question 16

Do these examples work with Tailwind CSS v3 and v4?

Accepted Answer

Both. shadcn.io is authored on Tailwind v4, so the examples use the v4 class names and design tokens. If you're on Tailwind v3, the classes still apply — Tailwind v4 introduced opt-in features but kept the utility naming compatible. The variant tokens (primary, secondary, destructive, muted) are declared identically under both versions, just in different config locations.

React Badge Examples for shadcn/ui

Browse every badge example

Frequently Asked Questions