Badge

Compact status labels with tinted fills, dot variants, semantic colors, and optional dismiss controls.

Installation

npx shadcn@latest add @iconiq/badge

File Structure

Usage

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

export function BadgePreview() {
  return (
    <p className="flex flex-wrap items-center justify-center gap-x-2 gap-y-2 text-balance text-center font-medium text-lg leading-snug dark:text-neutral-100">
      <span>This update is</span>
      <Badge color="teal">Early Access</Badge>
      <span>and</span>
      <Badge color="blue" variant="dot">
        On Track
      </Badge>
      <span>.</span>
    </p>
  );
}

Props

Props
Description

Badge

children

Badge content rendered above the optional shimmer layer so labels stay readable while the default variant animates.

Type ReactNode

className

Appended directly to the root badge element. Useful for radius, spacing, or local border overrides.

Type string·Default ""

variant

Chooses between the animated filled badge and the quieter outlined badge with a leading status dot.

Type "default" | "dot"·Default "default"

size

Controls height, horizontal padding, gap, and label size for denser or roomier badge treatments.

Type "sm" | "md" | "lg"·Default "md"

color

Picks a preset palette token or semantic alias (`success`, `warning`, `error`, `info`). Each token sets matched background and foreground tones for light and dark mode.

Type BadgeColorProp·Default "gray"

icon

Optional leading icon rendered before the label on the default variant only. Ignored when `variant="dot"` or when `onDismiss` is provided.

Type ReactNode

onDismiss

When provided on the default variant, renders a dismiss button after the label for removable filter chips. Ignored when `variant="dot"` or when `icon` is provided.

Type () => void

dismissLabel

Accessible label for the dismiss button when `onDismiss` is enabled.

Type string·Default "Remove"

animate

Controls the default variant mount fade/scale entrance and the dot variant status pulse. Use with `shimmer={false}` on the default variant when you want a one-time entrance without the looping sweep. Automatically disabled when `prefers-reduced-motion` is set.

Type boolean·Default true

shimmer

Controls the default variant shimmer sweep independently of the mount entrance. Automatically disabled when `prefers-reduced-motion` is set.

Type boolean·Default true

asChild

Merges badge styles onto the child element, such as an anchor, via Radix Slot.

Type boolean·Default false

waveColor

Optional shimmer midpoint override for the default variant. When omitted, the sweep derives a subtle tone from the current text color.

Type string

badgeVariants

variant

Chooses between the filled badge and dot badge recipes.

Type "default" | "dot"·Default "default"

size

Controls height, padding, gap, and label size.

Type "sm" | "md" | "lg"·Default "md"

color

Resolved palette token passed to `getBadgeColorVariables()` when reusing badge color tokens outside the component.

Type BadgeColor

interactive

Adds pointer cursor and focus ring styles for clickable badge roots.

Type boolean·Default false

className

Optional classes merged after the generated recipe classes.

Type string

badgeColors

keys

Named palette tokens such as gray, blue, green, amber, red, and purple.

Type BadgeColor

Visual behavior

The default variant keeps the spring-in shimmer treatment, while the dot variant adds a subtle status pulse. Motion respects reduced-motion preferences.

The default badge fades and scales from 0.95 to 1 on mount over 0.3 seconds when `animate` is true.

Its shimmer travels from left to right over 2 seconds, waits 1.5 seconds, then repeats indefinitely when `shimmer` is true.

The dot variant omits the shimmer layer, sizes its leading status dot to match the chosen badge size, and gives it a gentle repeating blink.

All entrance, shimmer, and dot pulse animations are skipped when `prefers-reduced-motion` is enabled.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: motion, class-variance-authority, @radix-ui/react-slot.

Requires the local `cn` helper from `@/lib/utils`, which is included in a standard shadcn setup.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

This update isEarly Accessand ready to ship.