badge

A versatile badge component for labels, statuses, and more.

Features

Supports multiple styles, sizes, and borders with Tailwind theming
Built-in hover, focus, and ring states for accessibility
Icon-ready with circular icon mode and smart sizing
Lightweight, ref-forwarding, and easily composable
Powered by @gentleduck/variants for scalable, consistent design

Philosophy

A badge is metadata made visible. It labels, categorizes, and quantifies without demanding interaction. We deliberately keep badges non-interactive by default - if you need a clickable label, compose it with a button. This constraint keeps the component's purpose clear and its accessibility story simple.

How It's Built

Loading diagram...

Installation

npx @gentleduck/cli add badge

npx @gentleduck/cli add badge

Usage

import { Badge } from '@/components/ui/badge'

<Badge variant="secondary">Badge</Badge>

Examples

Badge is a flexible and customizable React component used to display small status indicators with Tooltip, ..etc.

import { Badge } from '@/components/ui/badge'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'

const MyBadge = () => {
  return (
    <Tooltip>
      <TooltipTrigger asChild>
        <Badge aria-label="Badge" className="rounded-full" size="icon" variant="outline">
          <Info />
        </Badge>
      </TooltipTrigger>
      <TooltipContent>Info Badge</TooltipContent>
    </Tooltip>
  )
}

Default

Secondary

Destructive

Warning

Dashed

Outline

Icon

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and the badge follows it. No dir prop or rtl: classes needed.

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionBadge for a smooth pop-in entrance animation powered by motion. The badge scales and fades in with a bouncy spring on mount.

Requires the motion package. Use MotionBadge instead of Badge. Same props except asChild is not supported.

API Reference

Badge

Prop	Type	Default	Description
`variant`	`'default' \| 'secondary' \| 'destructive' \| 'warning' \| 'dashed' \| 'outline' \| 'nothing'`	`'default'`	Visual style of the badge
`size`	`'default' \| 'sm' \| 'lg' \| 'icon'`	`'default'`	Size of the badge
`border`	`'default' \| 'primary' \| 'secondary' \| 'destructive' \| 'warning'`	`'default'`	Border style variant
`asChild`	`boolean`	`false`	If `true`, renders using a `Slot` instead of a `span` element
`className`	`string`	`--`	Additional class names to apply
`...props`	`Omit<React.HTMLProps<HTMLSpanElement>, 'size'>`	-	Additional props to spread to the span element

MotionBadge

Pops in with a scale-and-fade animation on mount using the popIn preset and a springBouncy transition. asChild is not supported. Requires the motion package.

Prop	Type	Default	Description
`...props`	`Omit<BadgeProps, 'asChild'>`	-	All props from `Badge` except `asChild`