---
title: "Badge"
description: "A short metadata label for states, counts and tags. Tone supplies color and appearance controls weight; the text always carries the meaning."
kind: component
id: C-003
registry: "badge"
docs: "https://koten.codehive.com.co/components/badge"
markdown: "https://koten.codehive.com.co/md/components/badge.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/badge.json"
language: en
---

# Badge · 印

> Component C-003 in the Koten UI catalog.

A short metadata label for states, counts and tags. Tone supplies color and appearance controls weight; the text always carries the meaning.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/badge.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/badge.json
```

## Files

- `@/components/ui/badge.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Examples

### Tones

Seven tones in the default soft appearance; sale and new are fixed across themes.

```tsx
<Badge>Neutral</Badge>
<Badge tone="info">Info</Badge>
<Badge tone="success" dot>In stock</Badge>
<Badge tone="warning" dot>Low stock</Badge>
<Badge tone="danger">Cancelled</Badge>
<Badge tone="sale">Sale</Badge>
<Badge tone="new">New</Badge>
```

### Appearances

soft uses the tone border and text, solid inverts the background and outline leaves it transparent.

```tsx
<Badge tone="success" appearance="soft" dot>In stock</Badge>
<Badge tone="success" appearance="solid" dot>In stock</Badge>
<Badge tone="success" appearance="outline" dot>In stock</Badge>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `tone` | `neutral \| info \| success \| warning \| danger \| sale \| new` | `neutral` | sale always uses shu and new always ai, regardless of theme; the rest follow the theme roles. |
| `appearance` | `soft \| solid \| outline` | `soft` | solid uses the tone as background with text-solid-fg on top; outline paints no background. |
| `dot` | `boolean` | `false` | Adds a decorative dot with aria-hidden; it never replaces the text. |

## Accessibility

- State is never conveyed by color alone: there is always visible text.
- The dot is decorative and carries aria-hidden, so it does not duplicate information.
- Badge uses text-2xs as metadata; do not use it for paragraphs or primary content.
- Text tones meet AA on paper and surface according to the token test.

## Sources

- Catalog page: https://koten.codehive.com.co/components/badge
- Markdown: https://koten.codehive.com.co/md/components/badge.md
- Repository: https://github.com/codehive-colombia/koten