Badge

Basic

A compact inline label for categorization, status, filtering, and metadata. Supports 8 semantic variants, dot indicators, avatars, icons, dismissible mode, and optional pop animation.

<Badge>Default</Badge><Badge variant="primary">Primary</Badge><Badge variant="secondary">Secondary</Badge><Badge variant="success">Active</Badge><Badge variant="warning">Pending</Badge><Badge variant="danger">Blocked</Badge><Badge variant="info">Beta</Badge><Badge variant="outline">Outline</Badge>

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add badge

pnpm dlx @work-rjkashyap/unified-ui add badge

npx @work-rjkashyap/unified-ui add badge

bunx @work-rjkashyap/unified-ui add badge

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Badge,
	Avatar,
	Tag,
} from "@work-rjkashyap/unified-ui";

Basic Usage

<Badge>Label</Badge>
<Badge variant="primary">Feature</Badge>
<Badge variant="success" dot>Online</Badge>
<Badge variant="danger" dismissible onDismiss={handleDismiss}>Critical</Badge>

Variants

Eight semantic variants covering the full range of categorization and status needs.

<Badge>Default</Badge><Badge variant="primary">Primary</Badge><Badge variant="secondary">Secondary</Badge><Badge variant="success">Success</Badge><Badge variant="warning">Warning</Badge><Badge variant="danger">Danger</Badge><Badge variant="info">Info</Badge><Badge variant="outline">Outline</Badge>

Sizes

<Badge variant="primary" size="sm">Small</Badge><Badge variant="primary" size="md">Medium</Badge><Badge variant="primary" size="lg">Large</Badge>

Dot Indicator

Use the dot prop to display a colored status dot before the label. The dot color automatically matches the badge variant.

<Badge variant="success" dot>Online</Badge><Badge variant="danger" dot>Offline</Badge><Badge variant="warning" dot>Away</Badge><Badge variant="info" dot>Idle</Badge><Badge variant="primary" dot>Active</Badge>

With Icon

Pass an icon via the icon prop to display it before the label text.

import { Zap, Globe, Lock, GitBranch, Star } from "lucide-react";<Badge variant="primary" icon={<Zap className="size-3" />}>Pro</Badge><Badge variant="success" icon={<Globe className="size-3" />}>Published</Badge><Badge variant="warning" icon={<Lock className="size-3" />}>Private</Badge><Badge variant="info" icon={<GitBranch className="size-3" />}>main</Badge><Badge variant="default" icon={<Star className="size-3" />}>Featured</Badge>

With Avatar

Use the avatar prop to render an avatar image or initials before the label — common in user-mention chips.

<Badgevariant="secondary"avatar={<Avatar name="Rajeshwar Kashyap" size="xs" className="size-4" />}>@rjkashyap</Badge>

Removable / Dismissible

Set removable (or dismissible) to render a dismiss button. Provide an onRemove (or onDismiss) callback to handle dismissal. Both APIs are equivalent.

{/* Both "removable" and "dismissible" work identically */}<Badge variant="primary" removable onRemove={() => handleRemove("react")}>React</Badge><Badge variant="info" dismissible onDismiss={() => handleDismiss("ts")}>TypeScript</Badge>

Animated

Set animated to enable a subtle pop entrance animation using the popSubtle Framer Motion preset. This is useful for badges that appear dynamically. The animation respects prefers-reduced-motion.

<Badge variant="success" animated>Live</Badge><Badge variant="primary" animated icon={<Zap className="size-3" />}>Pro</Badge><Badge variant="danger" animated dot>Critical</Badge>

Disabled

Disabled badges have reduced opacity and no pointer events. Dismissible disabled badges keep the × button but it is non-functional.

<Badge variant="primary" disabled>Disabled</Badge><Badge variant="success" dismissible disabled>Can't Remove</Badge>

Polymorphic

Use the as prop to render the badge as a different element — like a link or button.

{
	/* As a link */
}
<Badge as="a" href="/category/react" variant="primary">
	React
</Badge>;

{
	/* As a button */
}
<Badge as="button" variant="outline" onClick={handleClick}>
	Filter
</Badge>;

Combined Features

Badges can combine dot, icon, avatar, and removable features together.

<Badge variant="success" dot size="sm">Active</Badge><Badge variant="danger" dot removable animated>Critical Alert</Badge><Badge variant="info" icon={<Star className="size-3" />} removable>Featured Tag</Badge><Badgevariant="secondary"size="lg"avatar={<Avatar name="RK" size="xs" className="size-4" />}dismissible>@rjkashyap</Badge>

Tag Input Pattern

Combine dismissible badges with an input for a tag entry UI.

function TagInput() {
	const [tags, setTags] = useState(["design-system", "react"]);
	const [input, setInput] = useState("");

	const addTag = () => {
		const trimmed = input.trim().toLowerCase();
		if (trimmed && !tags.includes(trimmed)) {
			setTags([...tags, trimmed]);
		}
		setInput("");
	};

	return (
		<div className="flex flex-wrap gap-2 p-2 border border-border rounded-md min-h-[40px]">
			{tags.map((tag) => (
				<Badge
					key={tag}
					variant="primary"
					size="sm"
					dismissible
					animated
					onDismiss={() => setTags(tags.filter((t) => t !== tag))}
				>
					{tag}
				</Badge>
			))}
			<input
				value={input}
				onChange={(e) => setInput(e.target.value)}
				onKeyDown={(e) => e.key === "Enter" && addTag()}
				placeholder="Add tag..."
				className="flex-1 min-w-[80px] outline-none bg-transparent text-sm"
			/>
		</div>
	);
}

Filter Chips

Badges work well as interactive filter toggles in list/table UIs.

const FILTERS = ["All", "Active", "Pending", "Archived"];
const [active, setActive] = useState("All");

<div className="flex gap-2 flex-wrap">
	{FILTERS.map((filter) => (
		<Badge
			key={filter}
			as="button"
			variant={active === filter ? "primary" : "default"}
			size="md"
			onClick={() => setActive(filter)}
			className="cursor-pointer"
		>
			{filter}
		</Badge>
	))}
</div>;

Migrating from Tag

The Tag component has been merged into Badge. The Tag export is still available as a backward-compatible alias that defaults to animated={true}.

// Before (Tag)
import { Tag } from "@work-rjkashyap/unified-ui";
<Tag variant="primary" dismissible onDismiss={fn}>
	React
</Tag>;

// After (Badge) — equivalent
import { Badge } from "@work-rjkashyap/unified-ui";
<Badge variant="primary" dismissible onDismiss={fn} animated>
	React
</Badge>;

Props

Motion

• Animated entrance — popSubtle preset: scales from 0.92 → 1 with a spring (stiffness: 400, damping: 25). Opt-in via animated prop.
• Respects prefers-reduced-motion — disables animation when reduced motion is preferred.

Accessibility

• Renders as a <span> element by default — non-interactive.
• The dot indicator is decorative (aria-hidden="true") — the text label conveys the meaning.
• The remove/dismiss button includes a configurable aria-label (defaults to "Remove").
• Dismiss button is focusable with tabIndex={0} and responds to Enter / Space.
• All semantic variant color combinations meet WCAG AA contrast ratios on their muted backgrounds.
• When using as="button" or as="a", the badge gains interactive semantics automatically.
• select-none prevents accidental text selection on double-click.
• Disabled state applies pointer-events-none and reduced opacity.

Design Tokens