Badge - HapplyUI

A compound badge component with variants, colors, sizes, dot indicators, and polymorphic icon support.

Installation

bunx @happlyui/cli@latest add badge

Dependencies

npm packages

@radix-ui/react-slot

Registry dependencies

These are automatically installed when you add this component.

tv
happly-ui-utils
polymorphic
recursive-clone-children

Usage

import * as Badge from "@/components/ui/badge"

<Badge.Root variant="filled" color="blue">
  <Badge.Icon as={RiFlashlightFill} />
  Badge
</Badge.Root>

Examples

Filled Variant

The filled variant uses the color's 500 token as background with white text.

Badge

<Badge.Root variant="filled">Badge</Badge.Root>
<Badge.Root variant="filled" color="red">Badge</Badge.Root>
<Badge.Root variant="filled" color="blue">Badge</Badge.Root>

Light Variant

The light variant uses the color's 200 token as background and 950 for text.

Badge

<Badge.Root variant="light">Badge</Badge.Root>
<Badge.Root variant="light" color="red">Badge</Badge.Root>

Lighter Variant

The lighter variant uses the color's 50 token for background, 100 for the border, and 950 for text.

Badge

<Badge.Root variant="lighter">Badge</Badge.Root>
<Badge.Root variant="lighter" color="red">Badge</Badge.Root>

Stroke Variant

The stroke variant uses a neutral-200 border on a white background with the color's 500 text.

Badge

<Badge.Root variant="stroke">Badge</Badge.Root>
<Badge.Root variant="stroke" color="red">Badge</Badge.Root>

Colors

All 10 available color options across the design system.

Badge

<Badge.Root>Badge</Badge.Root>
<Badge.Root color="blue">Badge</Badge.Root>
<Badge.Root color="red">Badge</Badge.Root>
<Badge.Root color="green">Badge</Badge.Root>

Sizes

Badges come in small (default) and medium sizes, with both icon and dot sub-components.

Badge

<Badge.Root size="medium">Badge</Badge.Root>
<Badge.Root size="small">Badge</Badge.Root>

Square

Use the square prop for compact numeric badges.

789

<Badge.Root square color="red">2</Badge.Root>
<Badge.Root square size="medium" color="red">2</Badge.Root>

With Icon

Use Badge.Icon with the `as` prop for polymorphic icon rendering.

Badge

<Badge.Root>
  <Badge.Icon as={RiFlashlightFill} />
  Badge
</Badge.Root>

With Dot

Use Badge.Dot for a small status dot indicator.

Badge

<Badge.Root>
  <Badge.Dot />
  Badge
</Badge.Root>

Disabled

Disabled badges across all variants.

Badge

<Badge.Root variant="filled" color="red" disabled>Badge</Badge.Root>
<Badge.Root variant="stroke" color="blue" disabled>Badge</Badge.Root>

As Child

Use the asChild prop with Radix Slot to render as a different element.

<Badge.Root asChild>
  <button type="button">Badge</button>
</Badge.Root>

Group Default

Badge.Group defaults to gray lighter badges with a stroke toggle.

React

TypeScript

Tailwind

<Badge.Group
  maxVisible={3}
  items={[
    { label: 'React' },
    { label: 'TypeScript' },
    { label: 'Tailwind' },
    { label: 'Node.js' },
    { label: 'GraphQL' },
    { label: 'Docker' },
  ]}
/>

Group

Use Badge.Group to render a list of badges with a collapsible show more/less toggle.

React

TypeScript

Tailwind

<Badge.Group
  maxVisible={3}
  variant="lighter"
  items={[
    { label: 'React', color: 'blue' },
    { label: 'TypeScript', color: 'purple' },
    { label: 'Tailwind', color: 'sky' },
    { label: 'Node.js', color: 'green' },
    { label: 'GraphQL', color: 'pink' },
  ]}
/>

Group Expanded

Badge.Group without maxVisible shows all badges with no toggle.

Design

Code

Ship

<Badge.Group
  variant="filled"
  items={[
    { label: 'Design', color: 'purple' },
    { label: 'Code', color: 'blue' },
    { label: 'Ship', color: 'green' },
  ]}
/>

API Reference

Badge.Root

The main badge container component.

Prop	Type	Default	Description
`variant`	`'filled' \| 'light' \| 'lighter' \| 'stroke'`	`'filled'`	The visual style
`color`	`'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'`	`'gray'`	The color of the badge
`size`	`'small' \| 'medium'`	`'small'`	The size of the badge
`square`	`boolean`	`false`	Compact mode for numeric content
`disabled`	`boolean`	`false`	Disables the badge visually
`asChild`	`boolean`	`false`	Renders as child element using Radix Slot

Badge.Icon

Polymorphic icon container that receives variant props from Badge.Root.

Prop	Type	Default	Description
`as`	`React.ElementType`	`'div'`	The element or component to render as

Badge.Dot

A small dot indicator that inherits color from Badge.Root.

Prop	Type	Default	Description

Badge.Group

A composed component that renders a list of badges with an optional collapsible toggle.

Prop	Type	Default	Description
`items`	`BadgeGroupItem[]`	-	Array of badge items to render. Each item has label, and optional variant, color, size, icon, and dot.
`maxVisible`	`number`	-	Maximum badges visible before collapsing. Shows all when omitted.
`variant`	`'filled' \| 'light' \| 'lighter' \| 'stroke'`	`'lighter'`	Shared variant for all badges (overridden by per-item variant)
`color`	`'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'`	`'gray'`	Shared color for all badges (overridden by per-item color)
`size`	`'small' \| 'medium'`	`'small'`	Shared size for all badges (overridden by per-item size)
`toggleVariant`	`'filled' \| 'light' \| 'lighter' \| 'stroke'`	`'stroke'`	Variant for the show more/less toggle badge
`toggleColor`	`'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'`	`'gray'`	Color for the show more/less toggle badge