- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
import { cva, type VariantProps } from "class-variance-authority";
import type * as React from "react";
import { cn } from "@/lib/utils";
const badgeVariants = cva(
"focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 text-xs leading-none font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] data-[icon-only]:aspect-square data-[icon-only]:px-0 [&_[data-slot=spinner]]:size-2.5 [&_[data-slot=spinner][data-variant=default]]:border [&>svg]:pointer-events-none [&>svg]:size-3",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
destructive:
"bg-destructive focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90 text-white",
outline:
"border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
secondary:
"bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
},
},
}
);
type BadgeProps = Omit<React.ComponentProps<"span">, "ref"> &
VariantProps<typeof badgeVariants> & {
as?: React.ElementType;
iconOnly?: boolean;
ref?: React.Ref<HTMLSpanElement>;
} & Record<string, unknown>;
function Badge({
className,
variant = "default",
as,
iconOnly = false,
...props
}: BadgeProps) {
const Comp = as ?? "span";
return (
<Comp
className={cn(badgeVariants({ variant }), className)}
data-icon-only={iconOnly ? "" : undefined}
data-inline
data-slot="badge"
{...props}
/>
);
}
export { Badge, badgeVariants };Badge renders a compact label for statuses, categories, counts, or inline metadata. It sits inside headings, table cells, list items, and alongside other content without disrupting the flow.
Installation
$ bunx --bun frakment add badge$ npx frakment add badge$ pnpm dlx frakment add badge$ yarn dlx frakment add badge
Install the following dependencies:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Copy and paste the following code into your project.
import { cva, type VariantProps } from "class-variance-authority";
import type * as React from "react";
import { cn } from "@/lib/utils";
const badgeVariants = cva(
"focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 text-xs leading-none font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-[3px] data-[icon-only]:aspect-square data-[icon-only]:px-0 [&_[data-slot=spinner]]:size-2.5 [&_[data-slot=spinner][data-variant=default]]:border [&>svg]:pointer-events-none [&>svg]:size-3",
{
defaultVariants: {
variant: "default",
},
variants: {
variant: {
default: "bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
destructive:
"bg-destructive focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90 text-white",
outline:
"border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
secondary:
"bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
},
},
}
);
type BadgeProps = Omit<React.ComponentProps<"span">, "ref"> &
VariantProps<typeof badgeVariants> & {
as?: React.ElementType;
iconOnly?: boolean;
ref?: React.Ref<HTMLSpanElement>;
} & Record<string, unknown>;
function Badge({
className,
variant = "default",
as,
iconOnly = false,
...props
}: BadgeProps) {
const Comp = as ?? "span";
return (
<Comp
className={cn(badgeVariants({ variant }), className)}
data-icon-only={iconOnly ? "" : undefined}
data-inline
data-slot="badge"
{...props}
/>
);
}
export { Badge, badgeVariants };Update the import paths to match your project setup.
Usage
import { Badge } from "@/components/ui/badge";<Badge>New</Badge>Anatomy
A badge is a single-part component. It has a bordered surface and a text label. Icons placed inside are automatically sized.
import { CheckIcon, PackageIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeAnatomy() {
return (
<div className="flex flex-wrap items-center justify-center gap-3">
<Badge>Text only</Badge>
<Badge>
<CheckIcon />
With icon
</Badge>
<Badge variant="outline">
<PackageIcon />
v1.2.0
</Badge>
</div>
);
}- Surface — background and border, following the variant
- Text — 12px, medium weight, nowrap
- Icon — 12px, auto-sized by
[&>svg]:size-3
Variants
import { Badge } from "@/components/ui/badge";
export function BadgeVariants() {
return (
<div className="flex flex-wrap gap-2">
<Badge>Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Destructive</Badge>
<Badge variant="outline">Outline</Badge>
</div>
);
}With Icon
Any icon placed inside a badge is automatically sized to 12px.
Icon before text
The most common pattern. Icon on the left, label on the right.
import { BadgeCheck, Bookmark } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeWithIconLeft() {
return (
<div className="flex flex-wrap gap-2">
<Badge variant="secondary">
<BadgeCheck data-icon="inline-start" />
Verified
</Badge>
<Badge variant="outline">
Bookmark
<Bookmark data-icon="inline-end" />
</Badge>
</div>
);
}import { CheckIcon } from "lucide-react";
<Badge>
<CheckIcon />
Verified
</Badge>;Icon only
A badge with just an icon. Provide an aria-label so screen readers can announce the intent.
import { CheckIcon, ClockIcon, XIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeIconOnly() {
return (
<div className="flex flex-wrap items-center justify-center gap-3">
<Badge aria-label="Verified" iconOnly>
<CheckIcon />
</Badge>
<Badge aria-label="Pending" iconOnly variant="secondary">
<ClockIcon />
</Badge>
<Badge aria-label="Failed" iconOnly variant="destructive">
<XIcon />
</Badge>
</div>
);
}<Badge aria-label="Verified" iconOnly>
<CheckIcon />
</Badge>With Spinner
Render a spinner beside the label to indicate an in-progress state.
import { Badge } from "@/components/ui/badge";
import { Spinner } from "@/components/ui/spinner";
export function BadgeWithSpinner() {
return (
<div className="flex flex-wrap gap-2">
<Badge variant="destructive">
<Spinner borderWidth={1} />
Deleting
</Badge>
<Badge variant="secondary">
Generating
<Spinner borderWidth={1} />
</Badge>
</div>
);
}<Badge variant="secondary">
<Spinner borderWidth={1} />
Generating
</Badge>;Link
Use as to render the badge as an anchor. Hover states ([a&]:hover:*) apply only when the badge renders as an interactive element.
import { ArrowUpRightIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeAsLink() {
return (
<Badge as="a" href="#link">
Open Link <ArrowUpRightIcon />
</Badge>
);
}<Badge as="a" href="/changelog">View release</Badge>Counts
Badges are often used to display counts. Pair secondary with a number for compact lists, or use icons to indicate the count type.
import { StarIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeCounts() {
return (
<div className="flex flex-wrap items-center justify-center gap-3">
<Badge variant="secondary">12 issues</Badge>
<Badge variant="secondary">
<StarIcon />
2.4k
</Badge>
<Badge variant="outline">+8</Badge>
</div>
);
}<Badge variant="secondary">12 issues</Badge>
<Badge variant="secondary">
<StarIcon />
2.4k
</Badge>Custom Colors
Override the surface colors with custom classes. Pass bg-* and text-* utilities to className.
import { Badge } from "@/components/ui/badge";
export function BadgeCustomColors() {
return (
<div className="flex flex-wrap items-center justify-center gap-3">
<Badge className="border-transparent bg-emerald-100 text-emerald-800 dark:bg-emerald-900 dark:text-emerald-100">
Success
</Badge>
<Badge className="border-transparent bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-100">
Warning
</Badge>
<Badge className="border-transparent bg-rose-100 text-rose-800 dark:bg-rose-900 dark:text-rose-100">
Danger
</Badge>
<Badge className="border-transparent bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-100">
Info
</Badge>
</div>
);
}<Badge className="bg-emerald-100 text-emerald-800 dark:bg-emerald-900 dark:text-emerald-100">
Success
</Badge>Note: Frakment's default theme is monochrome. Custom colors are opt-in and useful for status indicators that must be readable at a glance, such as deploy status or alerts.
In Context
Badges are designed to be composed. They sit inside headings, table cells, list items, and inline text without disrupting the flow.
Deploy list
import { CheckIcon, XIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { Spinner } from "@/components/ui/spinner";
export function BadgeDeployList() {
return (
<div className="w-full max-w-md space-y-3">
<div className="border-border flex items-center justify-between rounded-lg border p-3">
<span className="text-sm font-medium">Deploy v1.2.0</span>
<Badge>
<CheckIcon />
Success
</Badge>
</div>
<div className="border-border flex items-center justify-between rounded-lg border p-3">
<span className="text-sm font-medium">Deploy v1.2.1</span>
<Badge variant="secondary">
<Spinner borderWidth={1} />
Building
</Badge>
</div>
<div className="border-border flex items-center justify-between rounded-lg border p-3">
<span className="text-sm font-medium">Deploy v1.2.2</span>
<Badge variant="destructive">
<XIcon />
Failed
</Badge>
</div>
</div>
);
}<div className="flex items-center justify-between">
<span>Deploy v1.2.0</span>
<Badge>
<CheckIcon />
Success
</Badge>
</div>Issue list
Registry fails to install
#142 · opened 2 days ago
Add dark mode toggle
#141 · opened 3 days ago
Update installation docs
#140 · opened 5 days ago
import { Badge } from "@/components/ui/badge";
export function BadgeIssueList() {
return (
<div className="w-full max-w-md space-y-2">
<div className="border-border flex items-start justify-between gap-3 rounded-lg border p-3">
<div>
<p className="text-sm font-medium">Registry fails to install</p>
<p className="text-muted-foreground text-xs">
#142 · opened 2 days ago
</p>
</div>
<Badge variant="destructive">Bug</Badge>
</div>
<div className="border-border flex items-start justify-between gap-3 rounded-lg border p-3">
<div>
<p className="text-sm font-medium">Add dark mode toggle</p>
<p className="text-muted-foreground text-xs">
#141 · opened 3 days ago
</p>
</div>
<Badge variant="outline">Feature</Badge>
</div>
<div className="border-border flex items-start justify-between gap-3 rounded-lg border p-3">
<div>
<p className="text-sm font-medium">Update installation docs</p>
<p className="text-muted-foreground text-xs">
#140 · opened 5 days ago
</p>
</div>
<Badge variant="secondary">Docs</Badge>
</div>
</div>
);
}Inline with text
Badges can sit next to headings or inline text to mark status without breaking flow.
Frakmentv1.0
import { CircleAlertIcon, SparklesIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
export function BadgeInlineText() {
return (
<div className="flex flex-col items-center gap-4">
<h2 className="flex items-center gap-2 text-lg font-semibold">
Frakment
<Badge>
<SparklesIcon />
v1.0
</Badge>
</h2>
<div className="text-muted-foreground flex items-center gap-2 text-sm">
Status
<Badge variant="outline">
<CircleAlertIcon />
Beta
</Badge>
</div>
</div>
);
}API Reference
Badge
| Prop | Type | Default | Description |
|---|---|---|---|
variant | defaultsecondaryoutlinedestructive | default | The visual style of the badge. |
as | React.ElementType | — | Renders a different root element or component. Defaults to span. |
iconOnly | boolean | false | Renders a square badge with no horizontal padding. Use when the badge wraps only an icon. |
className | string | — | Additional class names applied to the badge. Use utility classes to override colors. |
Variants
| Variant | Use case |
|---|---|
default | Standard status |
secondary | Lower emphasis |
outline | Bordered, transparent |
destructive | Error label |
Accessibility
- Badges are not interactive unless
aswraps an interactive element such as<a>or<button>. Do not attachonClickhandlers to a plain<Badge>— use<Button>instead. - When a badge conveys essential information, ensure that information is also present in the surrounding text so screen reader users are not forced to encounter it as a standalone fragment.
- For icon-only badges, provide an
aria-labelso screen readers can announce the intent. Without it, the badge is read as "graphic" or skipped entirely. - Color alone must not convey state. The
destructivevariant pairs color with text or an icon. When adding custom colors, always include a text label or an icon with an accessible name. - For badges that indicate a loading state, pair the spinner with a text label such as "Generating" so screen readers can announce what is happening.
- Do not use the
destructivevariant for emphasis. It communicates a failure or prohibition — using it for non-error cases dilutes its meaning.
Best Practices
- Use badges for metadata, not actions. If a badge needs to be clickable, wrap it with
as="a"and anhref, or use a<Button>instead. - Keep labels short. Badges are compact by design. Anything longer than 3 words should be a tag, not a badge.
- Prefer monochrome by default. Reserve custom colors for status indicators that must be readable at a glance.
- Pair color with icon or text. Never rely on color alone to convey state — this is a WCAG requirement and also helps users with color vision deficiencies.
- Compose with other components. Badges work best inside
Button,Table,Card, or alongside headings. They are not standalone UI elements.
Related Components
- Marker — inline status row
Kbd— keyboard hint