Add this component

npx zentauri-ui add badge

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Static imports do not pull framer-motion. Use the animated entry only when you want motion and have framer-motion installed.

Display

Badges for compact labels

Use badges when you need concise metadata—counts, statuses, or lightweight tags—without pushing users into a separate detail view. Fits tables, filters, and React component props for Next.js dashboards.

BetaOutlineLiveBlocking

Badge variants playground

Pick an appearance, size, and shape to preview the badge live. Toggle Show output / Show code and the snippet updates to match the selected variant.


Featured

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

Badge API

Generated from the package prop types and variant definitions.

Badge

BadgeProps

Variants

PropTypeDefault
appearance
aquabluecrimsoncyandefaultdestructiveelectricemeraldforestghostglassgradient-blue+33
default
shape
dotpillsquare
pill
size
lgmdsm
md

Behavior

PropTypeDefault
closableboolean | undefinednone
closeLabelstring | undefinednone
liveRegionboolean | undefinednone
onCloseMouseEventHandler<HTMLButtonElement> | undefinednone

Content

PropTypeDefault
childrenReactNodenone
Inherited HTML props
PropTypeDefault
classNamestring | undefinednone
idstring | undefinednone
onClickMouseEventHandler<HTMLSpanElement> | undefinednone
styleCSSProperties | undefinednone
titlestring | undefinednone

BadgeVariant

BadgeVariantProps

Behavior

PropTypeDefault
appearance'default' | 'outline' | 'ghost' | 'blue' | 'cyan' | 'green' | 'lime' | 'mint' | 'ocean' | 'sapphire' | 'lavender' | 'ruby' | 'red' | 'slate' | 'zinc' | 'stone' | 'royal' | 'electric' | 'forest' | 'sunset' | 'magenta' | 'crimson' | 'aqua' | 'plum' | 'sky' | 'rose' | 'purple' | 'pink' | 'orange' | 'yellow' | 'teal' | 'indigo' | 'emerald' | 'gradient-blue' | 'gradient-green' | 'gradient-red' | 'gradient-yellow' | 'gradient-purple' | 'gradient-teal' | 'gradient-indigo' | 'gradient-pink' | 'gradient-orange' | 'glass' | 'secondary' | 'destructive' | null | undefinednone
shape'pill' | 'square' | 'dot' | null | undefinednone
size'md' | 'sm' | 'lg' | null | undefinednone

BadgeAnimated

BadgeAnimatedProps

animated

Behavior

PropTypeDefault
animationBadgeAnimation | undefinednone
appearance'default' | 'outline' | 'ghost' | 'blue' | 'cyan' | 'green' | 'lime' | 'mint' | 'ocean' | 'sapphire' | 'lavender' | 'ruby' | 'red' | 'slate' | 'zinc' | 'stone' | 'royal' | 'electric' | 'forest' | 'sunset' | 'magenta' | 'crimson' | 'aqua' | 'plum' | 'sky' | 'rose' | 'purple' | 'pink' | 'orange' | 'yellow' | 'teal' | 'indigo' | 'emerald' | 'gradient-blue' | 'gradient-green' | 'gradient-red' | 'gradient-yellow' | 'gradient-purple' | 'gradient-teal' | 'gradient-indigo' | 'gradient-pink' | 'gradient-orange' | 'glass' | 'secondary' | 'destructive' | null | undefinednone
closableboolean | undefinednone
closeLabelstring | undefinednone
liveRegionboolean | undefinednone
onCloseMouseEventHandler<HTMLButtonElement> | undefinednone
shape'pill' | 'square' | 'dot' | null | undefinednone
size'md' | 'sm' | 'lg' | null | undefinednone

Content

PropTypeDefault
childrenReactNodenone
Inherited HTML props
PropTypeDefault
classNamestring | undefinednone
idstring | undefinednone
onClickMouseEventHandler<HTMLSpanElement> | undefinednone
styleCSSProperties | undefinednone
titlestring | undefinednone
CSS variable overrides

Badge CSS variables

Override these badge variables on :root, a theme selector, or a component wrapper.

209 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-badge-default-bg: oklch(20.8% 0.042 265.755);
  --zui-badge-default-fg: oklch(98.4% 0.003 247.858);
  --zui-badge-default-shadow: 0 1px 2px rgba(15,23,42,0.08);
  --zui-badge-secondary-bg: oklch(92.9% 0.013 255.508);
  --zui-badge-secondary-fg: oklch(20.8% 0.042 265.755);
  --zui-badge-destructive-bg: oklch(64.5% 0.246 16.439);
  --zui-badge-outline-border: #0000001a;
  --zui-badge-outline-bg: #0000000d;
  --zui-badge-outline-fg: oklch(20.8% 0.042 265.755);
  --zui-badge-ghost-bg: transparent;
  --zui-badge-ghost-fg: oklch(37.2% 0.044 257.287);
  --zui-badge-glass-border: #00000026;
  --zui-badge-glass-bg: #0000001a;
  --zui-badge-glass-fg: oklch(20.8% 0.042 265.755);
  --zui-badge-blue-bg: #2563eb;
  --zui-badge-blue-fg: #ffffff;
  --zui-badge-cyan-bg: #0891b2;
  --zui-badge-cyan-fg: #083344;
  --zui-badge-green-bg: #16a34a;
  --zui-badge-green-fg: #ffffff;
  --zui-badge-lime-bg: #65a30d;
  --zui-badge-lime-fg: #1a2e05;
  --zui-badge-mint-bg: #10b981;
  --zui-badge-mint-fg: #064e3b;
  --zui-badge-ocean-bg: #0284c7;
  --zui-badge-ocean-fg: #082f49;
  --zui-badge-sapphire-bg: #1d4ed8;
  --zui-badge-sapphire-fg: #ffffff;
  --zui-badge-lavender-bg: #8b5cf6;
  --zui-badge-lavender-fg: #ffffff;
  --zui-badge-ruby-bg: #be123c;
  --zui-badge-ruby-fg: #ffffff;
  --zui-badge-red-bg: #dc2626;
  --zui-badge-red-fg: #ffffff;
  --zui-badge-slate-bg: #475569;
  --zui-badge-slate-fg: #ffffff;
  --zui-badge-zinc-bg: #52525b;
  --zui-badge-zinc-fg: #ffffff;
  --zui-badge-stone-bg: #57534e;
  --zui-badge-stone-fg: #ffffff;
  --zui-badge-royal-bg: #4338ca;
  --zui-badge-royal-fg: #ffffff;
  --zui-badge-electric-bg: #0ea5e9;
  --zui-badge-electric-fg: #ffffff;
  --zui-badge-forest-bg: #166534;
  --zui-badge-forest-fg: #ffffff;
  --zui-badge-sunset-bg: #ea580c;
  --zui-badge-sunset-fg: #ffffff;
  --zui-badge-magenta-bg: #c026d3;
  --zui-badge-magenta-fg: #ffffff;
  --zui-badge-crimson-bg: #b91c1c;
  --zui-badge-crimson-fg: #ffffff;
  --zui-badge-aqua-bg: #0f766e;
  --zui-badge-aqua-fg: #ffffff;
  --zui-badge-plum-bg: #7e22ce;
  --zui-badge-plum-fg: #ffffff;
  --zui-badge-emerald-bg: oklch(69.6% 0.17 162.48);
  --zui-badge-emerald-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-indigo-bg: oklch(39.8% 0.195 277.366);
  --zui-badge-indigo-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-purple-bg: oklch(43.8% 0.218 303.724);
  --zui-badge-purple-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-pink-bg: oklch(45.9% 0.187 3.815);
  --zui-badge-pink-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-rose-bg: oklch(64.5% 0.246 16.439);
  --zui-badge-rose-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-sky-bg: oklch(68.5% 0.169 237.323);
  --zui-badge-sky-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-teal-bg: oklch(70.4% 0.14 182.503);
  --zui-badge-teal-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-yellow-bg: oklch(79.5% 0.184 86.047);
  --zui-badge-yellow-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-orange-bg: oklch(70.5% 0.213 47.604);
  --zui-badge-orange-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-blue-from: oklch(42.4% 0.199 265.638);
  --zui-badge-gradient-blue-to: oklch(43.8% 0.218 303.724);
  --zui-badge-gradient-blue-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-green-from: oklch(44.8% 0.119 151.328);
  --zui-badge-gradient-green-to: oklch(45.3% 0.124 130.933);
  --zui-badge-gradient-green-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-red-from: oklch(44.4% 0.177 26.899);
  --zui-badge-gradient-red-to: oklch(45.9% 0.187 3.815);
  --zui-badge-gradient-red-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-yellow-from: oklch(47.6% 0.114 61.907);
  --zui-badge-gradient-yellow-to: oklch(47% 0.157 37.304);
  --zui-badge-gradient-yellow-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-purple-from: oklch(43.8% 0.218 303.724);
  --zui-badge-gradient-purple-to: oklch(45.9% 0.187 3.815);
  --zui-badge-gradient-purple-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-teal-from: oklch(43.7% 0.078 188.216);
  --zui-badge-gradient-teal-to: oklch(45% 0.085 224.283);
  --zui-badge-gradient-teal-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-indigo-from: oklch(39.8% 0.195 277.366);
  --zui-badge-gradient-indigo-to: oklch(43.8% 0.218 303.724);
  --zui-badge-gradient-indigo-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-pink-from: oklch(45.9% 0.187 3.815);
  --zui-badge-gradient-pink-to: oklch(45.5% 0.188 13.697);
  --zui-badge-gradient-pink-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-gradient-orange-from: oklch(47% 0.157 37.304);
  --zui-badge-gradient-orange-to: oklch(44.4% 0.177 26.899);
  --zui-badge-gradient-orange-fg: oklch(96.8% 0.007 247.896);
  --zui-badge-ring-offset: oklch(98.4% 0.003 247.858);
  --zui-badge-ring-focus: oklch(44.6% 0.043 257.281);
  --zui-badge-close-button-ring-focus: #00000066;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-badge-default-bg-dark: oklch(98.4% 0.003 247.858);
  --zui-badge-default-fg-dark: oklch(12.9% 0.042 264.695);
}

What it does

Badges inherit typography scales tuned for dense interfaces.

Combine with icons sparingly to preserve scan speed.

Composition and API

Prefer compound subcomponents instead of one oversized prop bag. Export a small, documented API for your design system.

Avoid relying on color alone; pair hue changes with text for state clarity.

Common use cases

  • Highlight unread counts on navigation tabs.
  • Tag environments (staging vs production) in admin headers.
  • Annotate data grid rows with processing states.
  • Mark beta features in settings panels.

Accessibility

Keyboard order, focus rings, and ARIA attributes should match production usage. Test with your supported browsers and assistive technologies when semantics are non-trivial.

This preview page exposes a single h1 in the hero for a clean outline.

Next.js integration notes

Colocate examples under the App Router, keep server and client boundaries explicit, and avoid pulling interactive overlays into unexpected server layouts.

Set NEXT_PUBLIC_SITE_URL so canonical and Open Graph URLs resolve on deploy.

FAQ

Does the Badge component work with Next.js App Router?

Yes. Import it like any other React component; keep interactive subtrees in client components when you need hooks or browser APIs, and leave static structure in server components where possible.

Can I customize badge with Tailwind CSS?

Zentauri UI exposes class-friendly variants and slots so you can extend styles with Tailwind utilities without fighting inline styles.

Is this Badge implementation accessible by default?

Primitives follow sensible defaults, but accessibility depends on how you label controls, manage focus, and wire keyboard handlers in your app. Validate critical flows with keyboard-only use and screen readers.