# Badge

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import { Badge } from "@/components/starwind/badge";
---

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

```
  </div>
  <div slot="react">
```tsx
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>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx 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.

```astro
---
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.

```astro
---
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

```astro
---
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.

```astro
---
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`.

```astro
---
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>
```

## Framework Availability
Badge is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Badge
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `appearance` | `"solid" \| "soft" \| "outline" \| "text" \| "frosted"` | No | - | Styled variant | Selects whether the Badge uses solid, soft, outlined, text, or frosted chrome. |
| `eyebrow` | `boolean` | No | `false` | Styled variant | Applies uppercase tracking for compact eyebrow labels. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `tone` | `"neutral" \| "primary" \| "primary-accent" \| "secondary" \| "secondary-accent" \| "info" \| "success" \| "warning" \| "error"` | No | - | Styled variant | Selects the semantic color family used by composed Badge appearances. |
| `variant` | `"default" \| "primary" \| "secondary" \| "outline" \| "ghost" \| "info" \| "success" \| "warning" \| "error"` | No | `"default"` | Styled variant | Selects the component's visual variant. |
- Inherits a attributes. Omits `type`.
- Inherits div attributes.

## 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.