Content & statusBrick 0.1.12

Badge

Badge is a compact passive label for categories, status, or short metadata.

Live example

Built from the published package

Interactive

DraftReadyBrick

Choose with confidence

Know when Badge is the right part

Use it when

Use it for short labels whose meaning is understandable in surrounding content.

Choose another path when

Do not use Badge as a button, form control, live status announcer, or overlay count. Use NotificationBadge for a count or dot attached to another element.

Installation and imports

tsx

import { Badge } from "@flowstack-ui/brick/badge";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/badge.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Quick start

tsx

<Badge>Draft</Badge>

Visual recipes and states

Variant changes fill and boundary, tone changes semantic color, size changes the complete label, and shape selects rounded, pill, or exact-square circle geometry. Circle is for one passive icon or single character with nearby context; use IconButton for actions and Status for dot-and-label state. Badge is passive and has no interactive state.

The xl size supplies a deliberate passive icon well for empty states and similar noninteractive illustrations. It is not an action target.

Examples

tsx

<Badge variant="outline" tone="success">Ready</Badge>

<Badge aria-label="Verified" shape="circle" tone="accent">
  <Icon aria-hidden size="xs">{checkIcon}</Icon>
</Badge>

Badge applies its public gap token when children include an icon and label:

tsx

<Badge tone="accent" shape="pill">
  <Icon size="xs">{icon}</Icon>
  Built for business
</Badge>

When a separately configured Text child is necessary, inherit Badge's foreground so the selected Badge recipe continues to own contrast:

tsx

<Badge tone="accent" shape="pill">
  <Icon size="xs">{icon}</Icon>
  <Text tone="inherit" variant="caption">Built for business</Text>
</Badge>

Prefer plain label text when no separate Text recipe is needed. Do not use default-tone Text inside Badge, add literal spaces around children, or select Badge only to imitate an editorial eyebrow.

The neutral solid recipe remains a neutral surface with the normal foreground; it does not switch to the inverse black/white pair between appearances.

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Badge's public exports are Badge, BadgeProps, BadgeVariant, BadgeTone, BadgeSize, and BadgeShape. The shared badge subpath also exports the separately documented Notification Badge family.

Prop	Values	Default
`variant`	`soft`, `solid`, `outline`	`soft`
`tone`	`neutral`, `accent`, `info`, `success`, `warning`, `danger`	`neutral`
`size`	`sm`, `md`, `lg`, `xl`	`md`
`shape`	`rounded`, `pill`, `circle`	`rounded`

Atom/native span props are inherited except native color.

Shared responsibility

Accessibility

Badge contributes its text to normal reading order. Do not rely on tone alone or use it as the only announcement of an asynchronous change.

Responsive behavior

Badge sizes to its content, keeps its short label on one line, and does not own responsive layout. Use ordinary Text for explanatory or prose-length content; surrounding layout or a deliberate scroll owner contains the Badge's intrinsic width.

Stable visual contract

Styling and tokens

Customization

Prefer recipe props, then semantic and public Badge tokens. Use className and style for scoped exceptions while maintaining contrast.

Tokens and CSS hooks

Stable hooks are .brick-badge, Atom slot badge, and data-variant, data-tone, data-size, data-shape. Public tokens are --brick-badge-background, --brick-badge-foreground, --brick-badge-border-color, --brick-badge-min-block-size, --brick-badge-inline-padding, --brick-badge-block-padding, --brick-badge-gap, --brick-badge-font-size, --brick-badge-radius, --brick-badge-tone-solid, --brick-badge-tone-on-solid, --brick-badge-tone-soft, --brick-badge-tone-on-soft, --brick-badge-tone-border, and --brick-badge-tone-text.

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground