Badge

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

Badges are lightweight, semantic, and fully aligned with the PyColors design system tokens. They are designed for metadata, not actions.

Import

import { Badge } from "@pycolors/ui"

Basic usage

Default

<Badge>Default</Badge>

import { Badge } from "@pycolors/ui";

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

  <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>

import { Badge } from "@pycolors/ui";

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">Error</Badge>
    </div>
  );
}

Available variants

Variant	Description
default	Primary or neutral label
secondary	Secondary emphasis
muted	Low-contrast metadata
outline	Neutral bordered label
success	Positive or completed state
warning	Caution or attention required
destructive	Error or critical state

Sizes

SmallDefaultLarge

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

import { Badge } from "@pycolors/ui";

export default function BadgeSizes() {
  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 needed (status, type, category).

Active

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

import { Badge } from "@pycolors/ui";

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)

Use asChild to render a badge as another element (for example, a link).

Docs

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

import { Badge } from "@pycolors/ui";

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.

Colors

Typography

Button

On this page