Badge

Badge presents short status, label, or count information that helps people scan an interface.

Purpose

Badge presents short status, label, or count information that helps people scan an interface. It does not replace explanatory copy.

Status variants

DefaultQueuedActiveReviewBlockedDraft

import { Badge } from "@/components/ui/badge";

export function Example() {
  return <Badge variant="success">Active</Badge>;
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/badge

Import

import { Badge } from "@/components/ui/badge";

Need the machine-readable source metadata? View registry JSON.

Usage

Badge is for compact status and metadata. Keep the label short and pair color with text.

import { Badge } from "@/components/ui/badge";

export function Example() {
  return <Badge variant="success">Active</Badge>;
}

Examples

Variants, semantic status colors, sizes, icons and link rendering are props of the same primitive.

Variants

DefaultSecondaryOutlineDestructive

<Badge>Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="outline">Outline</Badge>
<Badge variant="destructive">Destructive</Badge>

Semantic status

InfoSuccessWarningError

<Badge variant="info">Info</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="error">Error</Badge>

Sizes

SmallDefaultLargeExtra large

<Badge size="sm">Small</Badge>
<Badge>Default</Badge>
<Badge size="lg">Large</Badge>
<Badge size="xl">Extra large</Badge>

With icon

Verified

<Badge variant="outline">
  <CheckIcon aria-hidden="true" />
  Verified
</Badge>

As link

With render, the badge becomes a real link and keeps the badge hover and focus styles.

Docs

<Badge render={<Link href="/docs" />} variant="outline">
  Docs
  <ExternalLinkIcon aria-hidden="true" />
</Badge>

Count badge

<Badge aria-label="7 unread items" className="rounded-full">
  7
</Badge>

Status dot

Published

<Badge variant="success">
  <span aria-hidden="true" className="size-1.5 rounded-full bg-success" />
  Published
</Badge>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

variant accepts "default", "secondary", "outline", "destructive", "error", "info", "success", or "warning".
size accepts "sm", "default", "lg", or "xl"; without a local value, Badge inherits the nearest SiteplaneUIProvider controlSize.
Use render to make a Badge a semantic link or button without nesting interactive elements.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

A static Badge does not animate.
Interactive badges inherit their link or Button states; do not add local motion values.

Accessibility

Keep Badge text short and explicit.
Do not communicate status through color or a status dot alone.
Interactive badges need correct link or button semantics, visible focus, and an accessible name.
Treat icons and dots as decorative when the text conveys the same meaning.

Implementation Guidance

Use existing variants and sizes instead of inventing local badge colors.
Do not use Badge for long explanatory text.
Use render when the badge itself is interactive.