CounterBadge

CounterBadge shows a count (notifications, unread messages) or a dot signalling something new.

Hidden when count = 0 (unless showZero); above overflowCount it shows "99+". In dot mode the dot is always shown. Screen readers don't read the visible number; they read a label such as “5 notifications” instead, which you can change with the label prop.

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { CounterBadge } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Appearance & color

filled (default) / ghost × brand, danger, important, informative.

Size & shape

small, medium, large, extra-large; shape circular (default) or rounded.

Overflow, zero & dot

overflowCount defaults to 99; showZero still shows 0; dot is only a dot.

On an icon button

Position the badge absolutely in the top-end corner (logical: -inset-e-1) so it flips in RTL.

Usage

Use danger for things that need urgent attention and brand for ordinary counts.
Set a suitable overflowCount so the badge doesn't grow too wide.
Set label when the items counted aren't notifications, so screen readers say the right unit.

Don't

Don't use CounterBadge for text labels. Use Badge.
Don't show 0 unless the zero itself means something.

Props

Prop · Type	Default	Description
countnumber	Default: 0	The count.
overflowCountnumber	Default: 99	Above this value it shows "N+".
showZeroboolean	Default: false	Still shown when count = 0.
dotboolean	Default: false	Shows only a dot (always visible).
appearance"filled" \| "ghost"	Default: "filled"	Solid background or text only.
color"brand" \| "danger" \| "important" \| "informative"	Default: "brand"	important = inverted background (foreground-1).
shape"circular" \| "rounded"	Default: "circular"	Shape.
size"small" \| "medium" \| "large" \| "extra-large"	Default: "medium"	Same as Badge.
labelstring	Default: —	Screen reader label; defaults to “{count} notifications”.

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.counterBadge

Key · Type	Default (English)	messagesVi
dotstring Nhãn cho trình đọc màn hình khi `dot`.	Default (English)`"New notifications"`	messagesVi`"Có thông báo mới"`
count(count: number) => string Nhãn cho trình đọc màn hình theo số đếm.	Default (English)(count) => (count === 1 ? "1 notification" : `${count} notifications`)	messagesVi(count) => `${count} thông báo`
overflow(overflowCount: number) => string Nhãn cho trình đọc màn hình khi count vượt `overflowCount`.	Default (English)(overflowCount) => `More than ${overflowCount} notifications`	messagesVi(overflowCount) => `Hơn ${overflowCount} thông báo`