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.

Neutral24FeaturedPublishedReview neededSharedPublishingDeployment blocked

1import { Check, CircleAlert, Info } from "@nerio-ui/adapters/icons";2import { Badge } from "@nerio-ui/ui";34<Badge>Neutral</Badge>5<Badge size="sm" tone="info">24</Badge>6<Badge size="lg" tone="success">Featured</Badge>7<Badge tone="success" leadingIcon={Check}>Published</Badge>8<Badge tone="warning" leadingIcon={CircleAlert}>Review needed</Badge>9<Badge tone="info" leadingIcon={Info} trailingIcon={Check}>Shared</Badge>10<Badge tone="primary-soft" loading>Publishing</Badge>11<Badge tone="danger" emphasis="strong" leadingIcon={CircleAlert}>Deployment blocked</Badge>

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm dlx nerio add badge23import { Check, CircleAlert } from '@nerio-ui/adapters/icons';4import { Badge } from '@nerio-ui/ui';

Usage

PublishedSharedDeployment ready

1import { Check, CircleAlert } from '@nerio-ui/adapters/icons';2import { Badge } from '@nerio-ui/ui';34<Badge tone="success" leadingIcon={Check}>Published</Badge>5<Badge tone="warning" trailingIcon={CircleAlert}>Review needed</Badge>

Variants

PublishedReviewBlockedAction neededDeployment blocked

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.

242424

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

Badge
┌───────────────────────────────────────────────┐
│ leadingIcon │            label │ trailingIcon │
└───────────────────────────────────────────────┘

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

PublishedNeeds reviewBlockedPublishing

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; variant remains a deprecated compatibility alias.
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.

API

SharedReview needed24

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

Use concise, stable labels such as Draft, Published, Shared, or Blocked.

Use Badge as a button, link, or the only way to convey an important state.

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.