Content & statusBrick 0.1.2

Notification Badge

NotificationBadge overlays a visual count or dot on exactly one child.

Live example

Built from the published package

Interactive

Choose with confidence

Know when Notification Badge is the right part

Use it when

Use it to add compact visual notification metadata to an icon, avatar, or other single element.

Choose another path when

Use Badge for inline labels. Do not use the indicator as the only accessible name or as an automatic live-region announcement.

Installation and imports

tsx

import { NotificationBadge } 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.

NotificationBadge and its public types are also exported from @flowstack-ui/brick. There is no separate notification-badge package subpath.

Quick start

tsx

<NotificationBadge count={3}>
  <button aria-label="Inbox, 3 unread">Inbox</button>
</NotificationBadge>

Visual recipes and states

Counts above max display as max+. Dot and single-digit indicators are circles; longer counts are pills. Zero hides unless showZero; invalid counts and invisible hide the indicator. Placement uses logical start/end.

Examples

tsx

<NotificationBadge dot overlap="circular">
  <Avatar alt="Ada Lovelace, online" fallback="AL" />
</NotificationBadge>

Public contract

API

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

Public exports are NotificationBadge, NotificationBadgeProps, NotificationBadgePlacement, NotificationBadgeOverlap, and NotificationBadgeSize. BadgeTone is shared with Badge.

Prop	Values	Default
`tone`	`neutral`, `accent`, `info`, `success`, `warning`, `danger`	`danger`
`size`	`sm`, `md`, `lg`	`md`
`placement`	`top-start`, `top-end`, `bottom-start`, `bottom-end`	`top-end`
`overlap`	`rectangular`, `circular`	`rectangular`
`invisible`	`boolean`	`false`

Count mode requires count: number and accepts max?: number (valid positive integer, otherwise 99) and showZero?: boolean (false). Dot mode requires dot: true and excludes count-only props. Count must be a finite non-negative integer to display. children must be one ReactElement; asChild and native color are excluded.

Shared responsibility

Accessibility

The visual indicator is aria-hidden. Put the count or notification meaning in the child’s accessible name or nearby status text and update it when the count changes.

Responsive behavior

The overlay follows its child's box and logical direction. The application owns child sizing, clipping, and responsive placement decisions.

Stable visual contract

Styling and tokens

Customization

Use tone, size, placement, and overlap first, then public tokens. Root className and style are escape hatches; the indicator remains implementation-owned.

Tokens and CSS hooks

Stable root/indicator hooks are .brick-notification-badge and .brick-notification-badge__indicator; slots are notification-badge and notification-badge-indicator. Public root attributes are data-tone, data-size, data-placement, data-overlap, and conditional data-invisible; the private indicator reflects data-variant and data-shape for its owned presentation. Public tokens are --brick-notification-badge-size, --brick-notification-badge-dot-size, --brick-notification-badge-inline-padding, --brick-notification-badge-outline-color, --brick-notification-badge-translate-inline, and --brick-notification-badge-translate-block.

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