Badge

The Badge component is a compact UI element used to display short information such as status, category, count, or label.

Badges are non-interactive by default, lightweight, and fully aligned with the PyColors design system tokens.

Import

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

Usage

Default

<Badge>Default</Badge>

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

export default function Demo() {
  return <Badge>Default</Badge>;
}

Badges inherit their colors from semantic tokens and adapt automatically to light and dark mode.

Variants

Use variants to convey meaning or status.

DefaultSecondaryMutedOutlineSuccessWarningDestructive

<div className="flex gap-2">
  <Badge>Default</Badge>
  <Badge variant="secondary">Secondary</Badge>
  <Badge variant="muted">Muted</Badge>
  <Badge variant="outline">Outline</Badge>
  <Badge variant="success">Success</Badge>
  <Badge variant="warning">Warning</Badge>
  <Badge variant="destructive">Destructive</Badge>
</div>

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

export default function BadgeVariantsExample() {
  return (
    <div className="flex gap-2">
      <Badge>Default</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="muted">Muted</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="success">Success</Badge>
      <Badge variant="warning">Warning</Badge>
      <Badge variant="destructive">Destructive</Badge>
    </div>
  );
}

Sizes

SmallDefaultLarge

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

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

export default function BadgeSizesExample() {
  return (
    <div className="flex gap-2">
      <Badge size="sm">Small</Badge>
      <Badge size="md">Default</Badge>
      <Badge size="lg">Large</Badge>
    </div>
  );
}

Available sizes

Size	Description
sm	Compact metadata
md	Default badge size
lg	Emphasized or prominent

With icon

Badges can include icons when necessary (status, type, etc.).

Active

<Badge variant="success">
  <CheckIcon className="size-3" />
  Active
</Badge>

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

export default function BadgeWithIcon() {
  return (
    <Badge variant="success">
      <svg className="size-3" viewBox="0 0 24 24">
        <path d="M5 13l4 4L19 7" />
      </svg>
      Active
    </Badge>
  );
}

As child (Slot)

You can render a badge as another component (for example, a link).

Docs

<Badge asChild>
  <a href="/docs">Docs</a>
</Badge>

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

export default function BadgeAsChild() {
  return (
    <Badge asChild>
      <a href="/docs">Docs</a>
    </Badge>
  );
}

API

Props

Prop	Type	Default	Description
variant	BadgeVariant	"default"	Visual style
size	BadgeSize	"md"	Badge size
asChild	boolean	false	Render via Radix Slot
className	string	—	Additional Tailwind classes

The Badge extends standard HTML span props:

React.HTMLAttributes<HTMLSpanElement>

TypeScript types

export type BadgeVariant =
  | "default"
  | "secondary"
  | "muted"
  | "outline"
  | "success"
  | "warning"
  | "destructive";

export type BadgeSize =
  | "sm"
  | "md"
  | "lg";

Accessibility

Badges are decorative by default and should not replace buttons.
Do not rely on color alone to convey meaning.
When clickable, use asChild with a semantic element (a, button).
Icons must be supplementary and not the sole indicator.

Design guidelines

Use muted or outline for metadata and low-emphasis labels.
Use success, warning, and destructive only for status indicators.
Avoid overusing badges—prefer clarity over decoration.
Keep badge text short (1–2 words whenever possible).

Colors

Semantic color roles used by badges.

Typography

Text scale and weight for compact UI labels.

Button

Use buttons for actions, not badges.

Patterns

Status labels and real-world usage patterns.

Colors

Typography

Button

Patterns

On this page