, or inside a .",
"name": "as",
"type": "\"div\" | \"span\""
},
{
"defaultValue": "\"default\"",
"description": "STRUCTURAL emphasis only (fill/border style) — NOT colour. Use `tone` for semantic colour. `dashed` = dashed border.",
"name": "variant",
"type": "\"default\" | \"secondary\" | \"outline\" | \"dashed\""
},
{
"description": "SEMANTIC colour intent (BadgeTone = ToneProp + `primary`). This is the colour knob — success/warning/destructive/info/etc. `primary` is a SOFT brand pill (tinted brand fill + brand text) for the dashboard role-pill pattern; for a SOLID brand fill use `variant=\"default\"`. Keep variant for structure, tone for meaning.",
"name": "tone",
"type": "\"default\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"muted\" | \"neutral\""
},
{
"defaultValue": "\"default\"",
"description": "Corner radius from the tokens — `default` (badge radius), `pill` (fully rounded), `sharp` (square). Use the prop instead of a `rounded-*` className.",
"name": "shape",
"type": "\"default\" | \"pill\" | \"sharp\""
},
{
"defaultValue": "false",
"description": "Lining, fixed-width figures — for a chip whose content is a COUNT sitting in a column with other counts (a queue length per row, an unread tally per tab). Proportional figures make a `1` narrower than a `0`, so the digits do not line up and the chips jitter. The same axis Text, TableCell and StatCard already carry. Off by default: tabular figures are wider, and a chip carrying WORDS should not pay for them. Prefer it over `` — that composition works, but it asks the call site to know the chip's own type step.",
"name": "tabular",
"type": "boolean"
},
{
"description": "The entity's OWN colour as a CSS colour — DATA, not a semantic tone: a status colour, an issue type, a tag, whatever a person picked in a settings screen. A third axis beside `variant` (structure) and `tone` (meaning), and it wins over both. The chip is WASHED rather than filled (`--badge-tint-fill` into `--badge-tint-surface`, label from `--badge-tint-foreground`) because no foreground clears WCAG AA against every colour a picker can produce — near-black and white measure equal at luminance 0.2029, both 4.15:1. Washed, the ratio is a function of the tokens instead: 8.52:1 worst case across the sRGB cube, both themes.",
"name": "color",
"type": "string"
},
{
"description": "Lifecycle key. Known keys auto-map to tone + icon + i18n label; unknown keys fall back to neutral.",
"name": "status",
"type": "string"
},
{
"description": "Leading icon override. Pass null to suppress the auto status icon.",
"name": "icon",
"type": "React.ComponentType<{ className?: string }> | null"
},
{
"description": "Badge label. When omitted with status, Badge renders the translated lifecycle label or raw status. LONG LABEL CONTRACT (gh#1101): the chip is `max-inline-size: 100%` of its container and never wraps; the label ellipsizes and, when it was cut, opens the full text in the same tooltip as `Text ellipsis={{ tooltip: true }}` — on pointer hover of the label and on keyboard focus of the nearest focusable control around the chip (a row link, a treeitem, a cell button), only while it is actually cut; the chip never becomes a tab stop (gh#1105). A caller's own `title` on the Badge turns the tooltip off. So a Badge in a fixed-width DataTable cell or a narrow Card stays inside it with no extra props; `` also works. Do not reach for `Text break=\"anywhere\"` to make a chip wrap.",
"name": "children",
"type": "ReactNode"
},
{
"description": "antd Tag `closable` + `onClose` — draws a × on the chip and calls this when the user activates it. Omit for a plain badge (no ×). Accessible name quotes the string label via `navigation.filterBar.removeFilter`.",
"name": "onRemove",
"type": "() => void"
},
{
"description": "The × button's full accessible name, verbatim — antd 5.15+ `closable={{ 'aria-label' }}` (gh#706). Without it the name quotes the chip's label: a string `children`, or the label's RENDERED TEXT when `children` is a link or other node (so a row of saved-filter link chips never shares one bare \"Delete\"). Use it when the chip text alone doesn't say what removing does.",
"name": "removeLabel",
"type": "string"
}
],
"related": [
"Button — use instead of Badge when the chip must be interactive (clickable, toggleable). Badge carries no button role or keyboard handler; a naked `onClick` on Badge is inaccessible."
],
"rules": [
35
],
"storyPath": "data-display/badge.tsx",
"subParts": [
"StatusBadge"
],
"tagline": "Plain or lifecycle badge. Use `variant` for static chips, or `status` to auto-map lifecycle keys to semantic tone + icon. Labels never wrap: a label wider than its container ellipsizes, and its full text opens in a tooltip on hover or on keyboard focus of the control around the chip (gh#1101, gh#1105).",
"usage": [
"DO pick the correct variant semantically: `success` (approved/paid), `warning` (pending/overdue), `destructive` (rejected/error), `secondary` (neutral category), `outline` (subtle label), `default` (primary accent). Never force a colour just for aesthetics — agents and screen readers read the variant as intent.",
"DO use `status` for entity lifecycle statuses (active, draft, pending, cancelled, failed, scheduled, etc.) so the component resolves the correct tone, icon, and i18n label.",
"DO pass `variant` explicitly for localized labels or categorical tiers, and pass `icon={null}` when a lifecycle glyph would be misleading.",
"Badge renders as a `` by default (HTMLAttributes
) — pass `as=\"span\"` when it sits inside a , or , where a
is invalid HTML. With `onRemove`, the chip draws its own × (antd Tag closable); without it the chip is non-interactive. Do not add a naked `onClick` without an accessible role.",
"With `onRemove`, the × is part of the chip (antd Tag closable) — do not bolt a separate Button beside the label. Pass a string `children` label so the remover's accessible name quotes the chip.",
"Without `onRemove`, Badge is a leaf — pass plain text or a short ReactNode as children. Do NOT nest another Badge or interactive controls inside it.",
"Use semantic tokens for any className overrides (`text-muted-foreground`, `bg-destructive`) — never raw Tailwind palette classes like `bg-green-500`.",
"DO pass `color` — never an inline `backgroundColor` — when the colour belongs to the RECORD rather than to its meaning (a status an administrator coloured, an issue type, a tag). A hand-filled chip has to choose a foreground, and no choice is readable for every colour a picker can produce; `color` moves the ground instead and keeps the label on the surface's own foreground."
],
"useCases": [
"Category or tier labels on table rows — e.g. plan tier (`Pro `), document type (`Invoice `), or locale tag (`EN `).",
"Approval or review state in an accounting list where the value is not a lifecycle key in Badge's STATUS_MAP — e.g. a custom approval tier like `承認済 ` or `要確認 `.",
"Inline count or highlight next to a heading or nav item — e.g. `3 ` beside 'Overdue invoices' to draw attention to a non-zero count.",
"Feature flags or experiment variant labels on admin records — e.g. `A/B ` alongside a campaign row to indicate it is in a split test.",
"Read-only metadata chips inside a Descriptions.Item or Card header where a lifecycle icon would be visually heavy — e.g. currency code, payment method, or region tag.",
"A status or category an administrator coloured themselves, in an issue tracker or a CRM — `{status.name} `. The colour comes out of a picker and is stored on the row, so it cannot be mapped to a tone."
]
}