For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Badge

Displays a badge or a component that looks like a badge.

Web
Frakment
BadgeSecondaryDestructiveOutline
badge.tsx
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

Usage

badge.tsx
import { Badge } from "@/components/ui/badge";
badge.tsx
<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.

Text onlyWith iconv1.2.0
badge-anatomy.tsx
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

DefaultSecondaryDestructiveOutline
badge-variants.tsx
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.

VerifiedBookmark
badge-with-icon-left.tsx
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>
  );
}
example.tsx
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.

badge-icon-only.tsx
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.tsx
<Badge aria-label="Verified" iconOnly>
  <CheckIcon />
</Badge>

With Spinner

Render a spinner beside the label to indicate an in-progress state.

DeletingGenerating
badge-with-spinner.tsx
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>
  );
}
example.tsx
<Badge variant="secondary">
  <Spinner borderWidth={1} />
  Generating
</Badge>;

Use as to render the badge as an anchor. Hover states ([a&]:hover:*) apply only when the badge renders as an interactive element.

badge-as-link.tsx
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.tsx
<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.

12 issues2.4k+8
badge-counts.tsx
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.tsx
<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.

SuccessWarningDangerInfo
badge-custom-colors.tsx
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.tsx
<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

Deploy v1.2.0Success
Deploy v1.2.1Building
Deploy v1.2.2Failed
badge-deploy-list.tsx
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.tsx
<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

Bug

Add dark mode toggle

#141 · opened 3 days ago

Feature

Update installation docs

#140 · opened 5 days ago

Docs
badge-issue-list.tsx
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

StatusBeta
badge-inline-text.tsx
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

PropTypeDefaultDescription
variant
defaultsecondaryoutlinedestructive
defaultThe visual style of the badge.
asReact.ElementType—Renders a different root element or component. Defaults to span.
iconOnlybooleanfalseRenders a square badge with no horizontal padding. Use when the badge wraps only an icon.
classNamestring—Additional class names applied to the badge. Use utility classes to override colors.

Variants

VariantUse case
defaultStandard status
secondaryLower emphasis
outlineBordered, transparent
destructiveError label

Accessibility

  • Badges are not interactive unless as wraps an interactive element such as <a> or <button>. Do not attach onClick handlers 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-label so screen readers can announce the intent. Without it, the badge is read as "graphic" or skipped entirely.
  • Color alone must not convey state. The destructive variant 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 destructive variant 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 an href, 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.
  • Marker — inline status row
  • Kbd — keyboard hint