Badge
Compact label for status, categories, counts, and tags—with variants, semantic colors, and optional actions.
Installation
The component is exported from @by/experience-system. Add the package with your package manager:
pnpm add @by/experience-systemIn this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.
Composition
Use the following composition to build a Badge:
Badge
└── (children — text, icons, inline buttons, or a single element when `asChild`)With asChild, the root uses Radix Slot, which merges props onto the single child (for example an a or button) instead of rendering a span. For numeric indicators on top of another control, see Badge overlay.
Usage
import { Badge } from '@by/experience-system';Badge is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router.
<Badge variant="fill" color="accent">
New
</Badge>Pair variant and color for semantic tone (for example color="error" with variant="fill" for destructive or error tagging). Icons from @by/icons inherit size and color; use data-icon="inline-start" or data-icon="inline-end" on trailing or leading SVGs for spacing, and data-button="inline-end" on compact Button actions inside the badge.
Examples
Overview
A filled accent badge and a dismissible pattern with an icon Button. The live preview at the top of this page uses the same example (badge-usage).
Variants and colors
variant controls surface style (fill, soft, outline, ghost, link). color selects semantic and priority palettes.
Core colors
Priority Colors
Sizes
sm, md, and lg adjust height, padding, and default icon size.
With icon
Leading icons with aria-hidden when the text carries the meaning.
Link
Use variant="link" with an anchor (and optional trailing icon). Ensure the real target href and focus order in production.
API Reference
Badge uses Radix Slot when asChild is set; otherwise it renders a span. The tables below describe the Experience System surface. For merge behavior and accessibility when composing with asChild, see Radix Slot.
Badge
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
variant | fill | outline | soft | ghost | link | outline |
color | accent | neutral | error | success | warning | info | priorityNeutral | priorityLow | priorityMedium | priorityHigh | priorityCritical | neutral |
size | sm | md | lg | md |
className | string | — |
Also accepts standard span HTML attributes except color (replaced by the Experience System color prop above).
| Data attribute | Values |
|---|---|
data-slot | badge |
data-color | mirrors the color prop when set |
data-size | mirrors the size prop when set |
Accessibility
Treat Badge as supporting text, not a primary heading. Decorative icons should use aria-hidden. Inline Button actions need an accessible name (aria-label on the control). When variant="link", use a real a with a meaningful href (or an app router Link) and avoid # placeholders in production. For asChild, ensure the child element exposes correct roles and keyboard behavior. See Radix Slot.
Source in the repo: packages/experience-system/src/components/Badge/Badge.tsx and variants.ts. Agent-oriented contracts: packages/experience-system/src/components/Badge/Badge.instructions.md.
Registry examples
This @by-es item is a registry-only composite — live preview, installation steps, and source live on the dedicated page. See Registry for components.json setup and REGISTRY_TOKEN.
Chip list
Chip-like filter list built with Badge, removable actions, and an overflow count—useful for filter chips beside menus or dialogs.
→ See /system/components/chip-list.