Badge

Compact status labels with default and dot variants.

Installation

npx shadcn@latest add @iconiq/badge

Props

Badge

Compact label pill with a shimmer-enabled default variant, a quieter dot variant, and preset color tokens.

childrenReactNode

Required

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

classNamestring

Default ""

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

variant"default" | "dot"

Default "default"

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

size"sm" | "md" | "lg"

Default "md"

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

colorBadgeColor

Default "gray"

Picks a preset palette token. The default variant turns it into a tinted fill, while the dot variant uses it for the status dot and border tint.

waveColorstring

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

The component now spreads remaining span props, so ids, data attributes, and click handlers can be attached directly.

badgeVariants

CVA recipe exported alongside Badge for reusing badge styling on custom elements.

variant"default" | "dot"

Default "default"

Chooses between the filled badge and dot badge recipes.

size"sm" | "md" | "lg"

Default "md"

Controls height, padding, gap, and label size.

colorBadgeColor

Default "gray"

Preset palette token applied by the badge recipe.

classNamestring

Optional classes merged after the generated recipe classes.

badgeColors

Preset color token map used by Badge and badgeVariants for palette-consistent fills and dot treatments.

keysBadgeColor

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

Use the exported BadgeColor type when you want compile-time checks for supported palette tokens.

Visual behavior

The default variant keeps the original spring-in shimmer treatment, while the dot variant adds a subtle status pulse.

The default badge fades and scales from 0.95 to 1 on mount over 0.3 seconds.

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

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.

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.