Badge
Badges label status, category, or lightweight metadata without becoming primary actions.
Overview and decision boundary
Use Badge to label status, category, or lightweight metadata without creating another action.
Do not use badges as buttons or navigation targets.
import { Badge } from "@nerio-ui/ui";<Badge>Review needed</Badge><Badge tone="success">Published</Badge>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add badgeimport { Check, CircleAlert } from '@nerio-ui/adapters/icons';import { Badge } from '@nerio-ui/ui';Usage
import { Check, CircleAlert } from '@nerio-ui/adapters/icons';import { Badge } from '@nerio-ui/ui';<Badge tone="success" leadingIcon={Check}>Published</Badge><Badge tone="warning" trailingIcon={CircleAlert}>Review needed</Badge>Variants
| Tone | Soft (default) | Strong |
|---|---|---|
neutral | Routine metadata. | Rarely needed; reserve for elevated neutral status. |
primary-soft / accent | Selected or brand-associated metadata. | A compact brand moment that must stand out. |
info | Informational context. | Information that needs immediate scanning. |
success | A confirmed or completed state. | A completion state that is especially important. |
warning | A state that needs review. | A time-sensitive warning that needs attention. |
danger | A blocked or failed state. | A high-salience failure or risk that needs action. |
| Size | Use |
|---|---|
md | Default size for standalone status and metadata labels. |
sm | Compact size with reduced typography for an embedded Badge inside Button or another compact control. |
lg | Larger size for elevated standalone metadata that needs more visual presence. |
Anatomy
| Slot | Purpose |
|---|---|
root | Inline status container with tone and tokenized density. |
leading-icon | Optional decorative icon before the visible label. |
label | Short text that supplies the status or metadata meaning. |
trailing-icon | Optional decorative icon after the visible label. |
States
| State | Behavior |
|---|---|
Default | Badge is static metadata, not an interactive control. |
Loading | Spinner replaces the leading icon and exposes aria-busy. |
Soft | Default low-emphasis treatment for every tone. |
Strong | High-salience treatment for urgent warnings, blocking failures, or critical risk. |
Size | md is the default standalone size; sm is for compact embedded metadata and lg adds emphasis. |
Comfortable / compact | Density tokens adjust height and padding without changing the API. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Use concise text that does not rely on color alone.
- Avoid using Badge as a button or link.
- Use tone for semantic color.
- Optional icons are decorative, so text must carry the status meaning.
- Use leadingIcon or trailingIcon for visual context; the label remains the accessible status name.
- Use sm when the Badge is embedded inside a compact control such as Button.
- Use strong emphasis only when a warning, danger, or other status needs elevated attention.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Values | Purpose |
|---|---|---|
tone | neutral | primary-soft | accent | info | success | warning | danger | Sets semantic color treatment. |
emphasis | soft | strong | Soft is default; strong increases visual urgency. |
size | sm | md | lg | md is default; use sm inside compact controls and lg for elevated standalone metadata. |
leadingIcon | IconComponent | Places a decorative icon before the label. |
trailingIcon | IconComponent | Places a decorative icon after the label. |
loading | boolean | Shows a Spinner before the label and sets aria-busy. |
variant | neutral | info | success | danger | Deprecated compatibility alias for tone. |
icon | IconComponent | Deprecated compatibility alias for leadingIcon. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | badge installs 6 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | None. |
Package dependencies | clsx, react |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Badge to label status, category, or lightweight metadata without creating another action.
Do / do not
Do
Use concise, stable labels such as Draft, Published, Shared, or Blocked.
Do not
Use Badge as a button, link, or the only way to convey an important state.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Sizing | --n-badge-height / --n-badge-height-sm / --n-badge-height-lg / --n-badge-font-size-sm / --n-badge-padding-inline-sm / --n-badge-padding-inline-lg / --n-badge-gap-sm / --n-badge-gap-lg | Controls default, compact, and elevated Badge dimensions. |
Shape | --n-badge-radius | Controls the semantic pill radius. |
Surface | --n-badge-background / --n-badge-foreground | Default Badge treatment. |
Primary soft | --n-badge-background-primary-soft / --n-badge-foreground-primary-soft | Soft brand treatment. |
Accent | --n-badge-background-accent / --n-badge-foreground-accent | Soft accent treatment. |
Soft statuses | --n-badge-background-info / --n-badge-foreground-info / --n-badge-background-success / --n-badge-foreground-success / --n-badge-background-warning / --n-badge-foreground-warning / --n-badge-background-danger / --n-badge-foreground-danger | Soft semantic status treatments. |
Strong neutral | --n-badge-background-strong / --n-badge-foreground-strong | High-salience neutral treatment. |
Strong tones | --n-badge-background-strong-primary / --n-badge-background-strong-info / --n-badge-background-strong-success / --n-badge-background-strong-warning / --n-badge-background-strong-danger | High-salience semantic status treatments. |
Details | --n-badge-icon-size / --n-spinner-size-sm | Icon and loading indicator sizing. |