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'

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

<Badge variant="secondary">Badge</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>
  )
}

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

Direction is resolved through the shared primitives direction module. Use a local dir="rtl" override when the component exposes it, or set DirectionProvider at app/root level for global RTL/LTR behavior.

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 fade-up entrance animation powered by motion. The badge slides up with blur and opacity 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

Fades up with blur on mount using the fadeUp preset and contentTransition (250ms expo-out). asChild is not supported. Requires the motion package.

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