# Badge

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

> For the complete documentation index, see [llms.txt](/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](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="badge" />




<ComponentPreview name="badge" title="badge.tsx">
<Component />
</ComponentPreview>



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 [#installation]


<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>



<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>




<TabsContent value="cli">
```bash
npx frakment add badge
```
</TabsContent>




<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>



```bash
npm install class-variance-authority
```


<Step>
Copy and paste the following code into your project.
</Step>




<ComponentSource name="badge" title="components/ui/badge.tsx" />




<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>



## Usage [#usage]

```tsx title="badge.tsx"
import { Badge } from "@/components/ui/badge";
```

```tsx title="badge.tsx"
<Badge>New</Badge>
```

## Anatomy [#anatomy]

A badge is a single-part component. It has a bordered surface and a text label. Icons placed inside are automatically sized.


<ComponentPreview name="badge-anatomy" title="badge-anatomy.tsx" src="examples/badge-anatomy.tsx">
<j />
</ComponentPreview>



- **Surface** — background and border, following the variant
- **Text** — 12px, medium weight, nowrap
- **Icon** — 12px, auto-sized by `[&>svg]:size-3`

## Variants [#variants]


<ComponentPreview name="badge-variants" title="badge-variants.tsx" src="examples/badge-variants.tsx">
<a />
</ComponentPreview>



## With Icon [#with-icon]

Any icon placed inside a badge is automatically sized to 12px.

### Icon before text [#icon-before-text]

The most common pattern. Icon on the left, label on the right.


<ComponentPreview name="badge-with-icon-left" title="badge-with-icon-left.tsx" src="examples/badge-with-icon-left.tsx">
<o />
</ComponentPreview>



```tsx title="example.tsx"
import { CheckIcon } from "lucide-react";

<Badge>
  <CheckIcon />
  Verified
</Badge>;
```

### Icon only [#icon-only]

A badge with just an icon. Provide an `aria-label` so screen readers can announce the intent.


<ComponentPreview name="badge-icon-only" title="badge-icon-only.tsx" src="examples/badge-icon-only.tsx">
<E />
</ComponentPreview>



```tsx title="badge.tsx"
<Badge aria-label="Verified" iconOnly>
  <CheckIcon />
</Badge>
```

## With Spinner [#with-spinner]

Render a spinner beside the label to indicate an in-progress state.


<ComponentPreview name="badge-with-spinner" title="badge-with-spinner.tsx" src="examples/badge-with-spinner.tsx">
<p />
</ComponentPreview>



```tsx title="example.tsx"
<Badge variant="secondary">
  <Spinner borderWidth={1} />
  Generating
</Badge>;
```

## Link [#link]

Use `as` to render the badge as an anchor. Hover states (`[a&]:hover:*`) apply only when the badge renders as an interactive element.


<ComponentPreview name="badge-as-link" title="badge-as-link.tsx" src="examples/badge-as-link.tsx">
<g />
</ComponentPreview>



```tsx title="badge.tsx"
<Badge as="a" href="/changelog">View release</Badge>
```

## Counts [#counts]

Badges are often used to display counts. Pair `secondary` with a number for compact lists, or use icons to indicate the count type.


<ComponentPreview name="badge-counts" title="badge-counts.tsx" src="examples/badge-counts.tsx">
<F />
</ComponentPreview>



```tsx title="badge.tsx"
<Badge variant="secondary">12 issues</Badge>
<Badge variant="secondary">
  <StarIcon />
  2.4k
</Badge>
```

## Custom Colors [#custom-colors]

Override the surface colors with custom classes. Pass `bg-*` and `text-*` utilities to `className`.


<ComponentPreview name="badge-custom-colors" title="badge-custom-colors.tsx" src="examples/badge-custom-colors.tsx">
<v />
</ComponentPreview>



```tsx title="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 [#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-list]


<ComponentPreview name="badge-deploy-list" title="badge-deploy-list.tsx" src="examples/badge-deploy-list.tsx">
<C />
</ComponentPreview>



```tsx title="div.tsx"
<div className="flex items-center justify-between">
  <span>Deploy v1.2.0</span>
  <Badge>
    <CheckIcon />
    Success
  </Badge>
</div>
```

### Issue list [#issue-list]


<ComponentPreview name="badge-issue-list" title="badge-issue-list.tsx" src="examples/badge-issue-list.tsx">
<w />
</ComponentPreview>



### Inline with text [#inline-with-text]

Badges can sit next to headings or inline text to mark status without breaking flow.


<ComponentPreview name="badge-inline-text" title="badge-inline-text.tsx" src="examples/badge-inline-text.tsx">
<T />
</ComponentPreview>



## API Reference [#api-reference]

### Badge [#badge]


<PropsTable rows={[{"name":"variant","type":"default | secondary | outline | destructive","default":"default","description":"The visual style of the badge."},{"name":"as","type":"React.ElementType","description":"Renders a different root element or component. Defaults to span."},{"name":"iconOnly","type":"boolean","default":"false","description":"Renders a square badge with no horizontal padding. Use when the badge wraps only an icon."},{"name":"className","type":"string","description":"Additional class names applied to the badge. Use utility classes to override colors."}]} />



## Variants [#variants-1]

| Variant | Use case |
| :-- | :-- |
| `default` | Standard status |
| `secondary` | Lower emphasis |
| `outline` | Bordered, transparent |
| `destructive` | Error label |

## Accessibility [#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 [#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.
## Related Components [#related-components]

- [Marker](/docs/components/marker) — inline status row
- `Kbd` — keyboard hint