Loading…

Notification Badge

beta

A dot, rolling count or presence badge pinned to the corner of an icon, button or avatar.

Feedback
1 file
1 npm package
Accessibility notes

Playground

Installation

The CLI installs badge and number-flow as well, because this component imports them. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add notification-badge

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { NotificationBadge } from "@/components/ui/notification-badge";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Status
Inline

API

Generated from the component's own types, so a prop cannot appear here without existing.

<NotificationBadge>

Prop	Type	Default
`badgeClassName` Classes for the badge itself; `className` goes to the wrapper.	`string`	—
`count` The number shown by the `count` variant.	`number`	`0`
`label` Screen-reader text for the badge. Defaults to "3 notifications", "More than 99 notifications", "New" for a dot and the status name for a status.	`string`	—
`live` Announce changes politely. Off by default: most badges should not interrupt.	`boolean`	`false`
`max` Counts above this show as "max+".	`number`	`99`
`ping` A ring that pulses outward from the badge. Not rendered under reduced motion.	`boolean`	`false`
`position`	`"top-end" \| "top-start" \| "bottom-end" \| "bottom-start" \| "inline"`	`"top-end"`
`showZero` Show the `count` variant at zero instead of hiding it.	`boolean`	`false`
`status` Presence for the `status` variant.	`NotificationBadgeStatus`	`"online"`
`tone` Badge colour for `dot` and `count`. `status` takes its colour from the status.	`BadgeProps["variant"]`	`"default"`
`variant`	`"dot" \| "count" \| "status"`	`"dot"`
`children` The element the badge is pinned to. Without it the badge renders inline.	`ReactNode`	—

Plus every attribute of <span> except children.

Accessibility

Colour never carries the meaning alone: every badge has screen-reader text ("3 notifications", "More than 99 notifications", "New", "Online"…), overridable with `label`, while the visible digits are aria-hidden. A hidden count badge (zero, without showZero) is aria-hidden and empty. Changes are only announced when `live` is set. The text follows the wrapped element in reading order, so a wrapped icon button should still have its own name. The ping ring is not rendered under reduced motion, and the pop-in snaps.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

badgeClassName

Classes for the badge itself; className goes to the wrapper.

string

—

count

The number shown by the count variant.

number

0

label

Screen-reader text for the badge. Defaults to "3 notifications", "More than 99 notifications", "New" for a dot and the status name for a status.

string

—

live

Announce changes politely. Off by default: most badges should not interrupt.

boolean

false

max

Counts above this show as "max+".

number

99

ping

A ring that pulses outward from the badge. Not rendered under reduced motion.

boolean

false

position

"top-end" | "top-start" | "bottom-end" | "bottom-start" | "inline"

"top-end"

showZero

Show the count variant at zero instead of hiding it.

boolean

false

status

Presence for the status variant.

NotificationBadgeStatus

"online"

tone

Badge colour for dot and count. status takes its colour from the status.

BadgeProps["variant"]

"default"

variant

"dot" | "count" | "status"

"dot"

children

The element the badge is pinned to. Without it the badge renders inline.

ReactNode

—