NumberBadge

A self-anchoring count badge for avatars and icons with animated counts and 99+ overflow.

import { IconBell } from "@tabler/icons-react"

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"

Installation


bunx --bun shadcn@latest add @ondo-ui/number-badge

This installs NumberBadge along with badge, number-count, and the @number-flow/react dependency.

Usage

import { NumberBadge } from "@/components/compositions/number-badge"

<NumberBadge value={5}>
  <Avatar>{/* … */}</Avatar>
</NumberBadge>

NumberBadge wraps its children (the anchor) and overlays the count in a corner. Pass a value above max to get 99+; a value of 0 hides the badge unless showZero is set.

Examples

Overflow and hide-on-zero

value above max (default 99) renders as 99+; a value of 0 hides the badge. Step past both thresholds to see it.

"use client"

import * as React from "react"

Variants and placement

NumberBadge supports every Badge variant and all four placement corners.

default

secondary

destructive

outline

ghost

top-right

top-left

bottom-right

bottom-left

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
import { NumberBadge } from "@/components/compositions/number-badge"

API reference

NumberBadge accepts every Badge prop (except children, repurposed as the anchor), plus:

Prop	Type	Default	Description
`value`	`number`	—	Required count. `> max` shows `{max}+`.
`max`	`number`	`99`	Overflow cap.
`showZero`	`boolean`	`false`	Render the badge when `value` is `0`.
`placement`	`"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"`	`"top-right"`	Corner over `children`.
`variant`	`Badge` variants	`"default"`	Passed to `Badge`.
`children`	`React.ReactNode`	—	Anchor element the badge floats over.
`className`	`string`	—	Merged onto the overlaid `Badge`.