---
title: "StatusBadge"
description: "Maps an order status to a Badge tone with a decorative dot. The caller supplies the text: colour is never the only signal."
kind: block
id: C-059
category: erp
registry: "status-badge"
docs: "https://koten.codehive.com.co/blocks/erp/status-badge"
markdown: "https://koten.codehive.com.co/md/blocks/erp/status-badge.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/status-badge.json"
language: en
---

# StatusBadge · 状態

> Block C-059 in the Koten UI catalog.

Maps an order status to a Badge tone with a decorative dot. The caller supplies the text: colour is never the only signal.

> 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/status-badge.json

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

## Files

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

## Composition

This block composes Koten primitives. Read the source files above before changing its anatomy.

## Examples

### Status map

Five order statuses with their semantic tone and required text.

```tsx
<StatusBadge status="pending" label="Pending" />
<StatusBadge status="preparing" label="Preparing" />
<StatusBadge status="shipped" label="Shipped" />
<StatusBadge status="cancelled" label="Cancelled" />
<StatusBadge status="returned" label="Returned" />
```

### Inside a row

The badge shares a row with the order number without breaking alignment.

```tsx
<div className="flex items-center justify-between border border-rule px-2 py-1">
  <span className="font-mono text-2xs text-muted">KURA-10428</span>
  <StatusBadge status="preparing" label="Preparing" />
</div>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `status` | `"pending" \| "preparing" \| "shipped" \| "cancelled" \| "returned"` | `—` | Selects the tone from orderStatusTones; the map is not inferred from the text. |
| `label` | `ReactNode` | `—` | Visible and accessible text; required. |
| `className` | `string` | `—` | Adds to the component's base classes. |

## Accessibility

- The dot is decorative (aria-hidden) and the text is required: colour never communicates alone.
- The tone comes from status; do not pass an arbitrary tone for a new state without extending the map.
- Inside a row the badge is not interactive: do not use it as a filter button.

## Sources

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