# Badge

Page: /docs/components/badge

{/* Figma: Meridian → Badge (docs 43:2, component set 18:168). Spec: docs/design-system/meridian/badge.md */}

A status, colored by meaning: New, Live, Coming soon, Sold out. Read-only, never removable. On the site it marks new products, live webinars and changelog entries, and the statuses in product shots. A value someone chose is a Tag.

```tsx
import { Badge } from "@commenda/meridian/ui/badge";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function BadgeTones() {
	return (
		<Stage>
			<Labelled label="neutral">
				<Badge label="Coming soon" tone="neutral" />
			</Labelled>
			<Labelled label="info">
				<Badge label="New" tone="info" />
			</Labelled>
			<Labelled label="success">
				<Badge label="Live" tone="success" />
			</Labelled>
			<Labelled label="warning">
				<Badge label="Few seats left" tone="warning" />
			</Labelled>
			<Labelled label="error">
				<Badge label="Closed" tone="error" />
			</Labelled>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Badge } from "@commenda/meridian/ui/badge";

<Badge label="Live" tone="success" />;
```

## Tones [#tones]

Five tones, each a meaning. Neutral is the most common: a state that needs nothing from anyone.

```tsx
import { Badge } from "@commenda/meridian/ui/badge";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function BadgeTones() {
	return (
		<Stage>
			<Labelled label="neutral">
				<Badge label="Coming soon" tone="neutral" />
			</Labelled>
			<Labelled label="info">
				<Badge label="New" tone="info" />
			</Labelled>
			<Labelled label="success">
				<Badge label="Live" tone="success" />
			</Labelled>
			<Labelled label="warning">
				<Badge label="Few seats left" tone="warning" />
			</Labelled>
			<Labelled label="error">
				<Badge label="Closed" tone="error" />
			</Labelled>
		</Stage>
	);
}
```

## With a dot or a status icon [#with-a-dot-or-a-status-icon]

A dot when color alone would be too quiet, as in a dense list. A status icon when the badge belongs to a lifecycle, so it matches the row’s status icon in a product shot.

```tsx
import { Badge } from "@commenda/meridian/ui/badge";

export function BadgeIndicators() {
	return (
		<div className="not-prose my-4 flex flex-col gap-5 rounded-xl border border-fd-border bg-white p-8">
			<div className="flex flex-wrap items-center gap-3">
				<span className="w-24 text-[12px] text-fd-muted-foreground">Dot</span>
				<Badge label="Draft" tone="neutral" indicatorConfig={{ type: "dot" }} />
				<Badge label="In review" tone="info" indicatorConfig={{ type: "dot" }} />
				<Badge label="Filed" tone="success" indicatorConfig={{ type: "dot" }} />
				<Badge label="Due soon" tone="warning" indicatorConfig={{ type: "dot" }} />
				<Badge label="Overdue" tone="error" indicatorConfig={{ type: "dot" }} />
			</div>
			<div className="flex flex-wrap items-center gap-3">
				<span className="w-24 text-[12px] text-fd-muted-foreground">Status icon</span>
				<Badge label="To do" tone="neutral" indicatorConfig={{ type: "status", status: "to-do" }} />
				<Badge
					label="In progress"
					tone="info"
					indicatorConfig={{ type: "status", status: "in-progress" }}
				/>
				<Badge
					label="In review"
					tone="info"
					indicatorConfig={{ type: "status", status: "in-review" }}
				/>
				<Badge
					label="Completed"
					tone="success"
					indicatorConfig={{ type: "status", status: "completed" }}
				/>
				<Badge
					label="Rejected"
					tone="error"
					indicatorConfig={{ type: "status", status: "failed" }}
				/>
			</div>
		</div>
	);
}
```

## Sizes [#sizes]

sm 20 with Label/12 Strong is the default, in lists, cards and product shots. md 24 with Label/13 Strong sits next to page and section titles.

```tsx
import { Badge } from "@commenda/meridian/ui/badge";

export function BadgeSizes() {
	return (
		<div className="not-prose my-4 flex flex-col gap-5 rounded-xl border border-fd-border bg-white p-8">
			{(["sm", "md"] as const).map((size) => (
				<div key={size} className="flex flex-wrap items-center gap-3">
					<span className="w-24 text-[12px] text-fd-muted-foreground">
						{size === "sm" ? "sm 20" : "md 24"}
					</span>
					<Badge size={size} label="Live" tone="success" />
					<Badge size={size} label="New" tone="info" indicatorConfig={{ type: "dot" }} />
				</div>
			))}
		</div>
	);
}
```

## Badge and Tag [#badge-and-tag]

Same height and corner, different jobs. A Tag is a value someone chose: neutral, has a hairline, can be removed. A Badge is a status: colored by meaning, no border, read-only.

```tsx
import { Badge } from "@commenda/meridian/ui/badge";
import { Tag } from "@commenda/meridian/ui/tag";
import { USFlag } from "@commenda/pathfinder/flags";

const noop = () => {};

export function BadgeVsTag() {
	return (
		<div className="not-prose my-4 flex flex-col gap-5 rounded-xl border border-fd-border bg-white p-8">
			<div className="flex flex-wrap items-center gap-3">
				<span className="w-24 text-[12px] text-fd-muted-foreground">Tag</span>
				<Tag label="Sales tax" removeConfig={{ onRemove: noop }} />
				<Tag
					label="United States"
					leadingIcon={<USFlag size={12} />}
					removeConfig={{ onRemove: noop }}
				/>
			</div>
			<div className="flex flex-wrap items-center gap-3">
				<span className="w-24 text-[12px] text-fd-muted-foreground">Badge</span>
				<Badge label="Live" tone="success" />
				<Badge label="Few seats left" tone="warning" />
			</div>
		</div>
	);
}
```

## Anatomy [#anatomy]

Height 20 (sm) or 24 (md), radius 4 (sm) or 6 (md), padding 6 (sm) or 8 (md), gap 6 between the dot or icon and the label. The tone’s 100 fill with its 800 or 900 text (soft-pearl 200 and 900 for neutral). Every pair passes AA contrast.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "error"` |  |
| `size` | `"md" \| "sm"` |  |
| `indicatorConfig` | `{ type: "dot"; } \| { type: "status"; status: StatusKind; }` |  |
| `className` | `string` |  |
| `id` | `string` |  |

**`indicatorConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `type` (required) | `"dot"` |  |

**`indicatorConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `type` (required) | `"status"` |  |
| `status` (required) | `"to-do" \| "scheduled" \| "in-progress" \| "in-review" \| "completed" \| "canceled" \| "blocking" \| "blocked-by" \| "failed" \| "needs-attention"` |  |

## Best practices [#best-practices]

- Use a Badge for a status; use a Tag for a value someone picked, and a Button or link for anything clickable. Badges are never interactive.
- Keep labels to one or two words in sentence case: "New", not "NEW" or "This is a new product".
- One tone per meaning across the site. New is always info, Live is always success.
- Never rely on color alone: the label carries the meaning. Add a dot or status icon in dense lists.
- Use one Badge per card. Two badges compete and neither reads.
- Source: Pathfinder Badge. Meridian keeps it as is.
