Badge — Atom UI

When to Use

Use Badge for short information attached to nearby content, such as an unread count or a compact status word. Badge is not interactive and does not announce changes automatically. Use Button for an action, Progress for completion, or an appropriate live-region pattern when an update must be announced.

Features

The behavior Atom owns before your product adds appearance.

Renders a native span by default.
Keeps the explicit @flowstack-ui/atom/badge subpath server-safe.
Keeps text content in the accessibility tree.
Passes native span props through to the rendered element.
Supports asChild and render.
Adds no role, interaction, or live-region behavior automatically.

Import

tsx

import { Badge } from "@flowstack-ui/atom";

Anatomy

tsx

<Badge.Root />

API Reference

Root

Renders an inline span around badge content. It provides a stable data slot without changing the meaning or announcement behavior of its children.

Prop	Type	Default
`asChild`	`boolean`	`false`
`render`	`RenderProp`	-

Data attribute	Values
`[data-slot]`	`"badge"`

Examples

Unread Count

tsx

import { Badge } from "@flowstack-ui/atom/badge";

export function UnreadCount() {
  return (
    <span>
      Unread messages <Badge.Root>3</Badge.Root>
    </span>
  );
}

Text Status

tsx

import { Badge } from "@flowstack-ui/atom";

export function AccountStatus() {
  return (
    <p>
      Account status: <Badge.Root>Active</Badge.Root>
    </p>
  );
}

Accessibility

WAI-ARIA defines no dedicated Badge pattern. Badge text is announced as normal inline content, so make sure a number or status has enough nearby context to be understood. Do not rely on aria-label to name the default generic span, and do not communicate meaning through color alone.

When a visual notification count is attached to a control, include the count in that control's accessible name or other appropriate owning context. A sibling Badge does not automatically become part of a button's name.

Root does not add aria-live. If a changing count must be announced, apply the appropriate live-region behavior deliberately based on the urgency and frequency of the update.

Changelog

Unreleased

0.24.0

Added source-led Agent Knowledge for passive contextual labels and counts, owning-control context, noninteraction, and deliberate live announcement boundaries.

0.3.3

Kept the pure-render primitive and explicit Badge subpath server-safe.
Corrected numeric Badge accessibility guidance to use meaningful surrounding or owning-control context instead of naming a generic span.

0.1.0

Initial Atom release.