Badge

---
import { Badge } from "@/components/starwind/badge";
---

<Badge tone="primary-accent" appearance="soft">Introducing Starwind UI v3</Badge>

import { Badge } from "@/components/starwind/badge";

export function Example() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge tone="primary-accent" appearance="soft">Introducing Starwind UI v3</Badge>
    </div>
  );
}

Installation

pnpx starwind@latest add badge

npx starwind@latest add badge

yarn dlx starwind@latest add badge

Usage

Use tone to choose the semantic color and appearance to choose how strongly that color is presented. They can be combined independently, giving you more control than the original variant prop.

Tone and appearance

The available tones are neutral, primary, primary-accent, secondary, secondary-accent, info, success, warning, and error. Each tone supports solid, soft, outline, text, and frosted appearances.

---
import { Badge } from "@/components/starwind/badge";
---

<Badge tone="primary" appearance="solid">Primary</Badge>
<Badge tone="primary-accent" appearance="soft">Primary accent</Badge>
<Badge tone="success" appearance="outline">Success</Badge>
<Badge tone="warning" appearance="text">Warning</Badge>
<Badge tone="info" appearance="frosted">Info</Badge>

Providing either tone or appearance opts into the composable styling API. When one is omitted, the component uses neutral for the tone or soft for the appearance.

Eyebrow

Use eyebrow for compact labels that need an uppercase treatment with wider letter spacing. It can be combined with every tone, appearance, and size.

---
import { Badge } from "@/components/starwind/badge";
---

<Badge tone="primary-accent" appearance="text" size="sm" eyebrow>Small eyebrow</Badge>
<Badge tone="primary-accent" appearance="text" size="md" eyebrow>Medium eyebrow</Badge>
<Badge tone="primary-accent" appearance="text" size="lg" eyebrow>Large eyebrow</Badge>

Size and icons

---
import { Badge } from "@/components/starwind/badge";
import Mail from "@tabler/icons/outline/mail.svg";
---

<Badge tone="primary-accent" appearance="soft" size="sm"><Mail />Small</Badge>
<Badge tone="primary-accent" appearance="soft" size="md"><Mail />Medium</Badge>
<Badge tone="primary-accent" appearance="soft" size="lg"><Mail />Large</Badge>

Link

Provide an href to render the Badge as an <a> element. Link badges receive hover styles suited to their selected appearance.

---
import { Badge } from "@/components/starwind/badge";
---

<Badge href="#link" tone="primary" appearance="solid">Primary</Badge>
<Badge href="#link" tone="secondary" appearance="solid">Secondary</Badge>
<Badge href="#link" tone="primary-accent" appearance="soft">Primary accent</Badge>
<Badge href="#link" tone="success" appearance="outline">Success</Badge>

Legacy variants

The variant prop is still supported to avoid breaking changes. For new usage, prefer tone and appearance, which separate semantic color from visual emphasis. If tone or appearance is provided, the composable styling API takes precedence over variant.

---
import { Badge } from "@/components/starwind/badge";
---

<Badge variant="default">Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="outline">Outline</Badge>
<Badge variant="ghost">Ghost</Badge>
<Badge variant="info">Info</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="error">Error</Badge>

API Reference

Changelog

v1.5.0

• Added contract-generated Astro and React implementations.
• Added tone, appearance, and eyebrow treatments while preserving the legacy variant API for backwards compatibility.

v1.4.3

• Refactor tailwind variants functions into separate variants.ts file

v1.4.0

• Add automatic styling for SVGs within badges

v1.3.0

• Style and focus state updates

v1.2.0

• Add a data-slot attribute to all components to enable global styling updates

v1.1.1

• Adjust component to use type VariantProps from tailwind-variants. This provides greater type safety and cleans up component frontmatter.

v1.1.0

• tailwind-variants now implemented. This uses tailwind-merge under the hood to merge Tailwind classes without style conflicts, allowing you to override any existing classes using the “class” prop.