Skip to content
Browse documentation

A bell that behaves like one: each notification hits it, a burst rings harder, and the clapper lags behind on its own.

Used forApp headersChat and support toolsDashboardsLive events

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/notification-bell.json

Registered the namespace? Then it’s shadcn add @hairline/notification-bell. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • App headers

    The bell beside the avatar, with the unread count from your own API.

  • Chat and support tools

    A burst of messages looks like a burst, not like one message.

  • Dashboards

    A dot when something needs attention and a number is too much.

  • Live events

    Change ringKey to ring for an alert without changing the count.

What it handles for you

A keyframed wiggle looks the same for one message or ten, and it jumps back to the start when another arrives. This handles the things around the ring too.

Instead of wiring upcss bell shake keyframesbadge count hand-rolledframer-motion bell
  1. Bursts add up

    A push goes in the direction the bell is already moving, so messages arriving mid-swing ring it harder, up to a limit where it never spins over.

  2. A clapper with real lag

    It follows the bell's speed through its own spring, so it moves late and keeps going after the bell turns.

  3. Only arrivals ring

    A count going down never rings. Marking everything read rolls the number and shrinks the badge away holding its last digits.

  4. Numbers that fit

    The count rolls in the direction it moved and the badge widens with it; past max it reads 99+.

  5. Screen readers

    The button is named with the count, and a status region outside it announces changes.

  6. Your click

    It is a real button: pass onClick and any button prop, and open your own inbox from it.

Overview

Most notification bells play the same little wiggle every time, and a second message restarts it. This one is a weight on a hinge. Each new notification pushes it by an amount sized to how many came, on top of whatever swing it already has, so a burst visibly rings harder. Nothing animates the clapper: it reads the bell's speed and falls behind on a softer spring of its own. The badge jumps with each hit and leans against the swing, and the count rolls the way it moved.

States

ring
A push of 210 to 360 degrees per second, by how many came (up to five). The swing dies away over about two seconds.
burst
A hit during a swing adds to it, capped at 480 degrees per second.
read
The count falling rolls the number down without ringing; at zero the badge shrinks to nothing.
hover
A small nudge under a mouse, so it plainly hangs loose.
dot
A dot instead of the number, with the same ring and the same jump.
reduced motion
The count changes in place and the bell stays still.

Usage

usage.tsx
import { NotificationBell } from "@/components/notification-bell";<NotificationBell count={unread} onClick={openInbox} />

Works with

With your own live count

The bell only needs a number. Anything that updates it, polling or a socket, rings it.

example.tsx
"use client";import { useEffect, useState } from "react";import { NotificationBell } from "@/components/notification-bell";export function InboxBell({ onOpen }: { onOpen: () => void }) {  const [unread, setUnread] = useState(0);  useEffect(() => {    const events = new EventSource("/api/notifications/stream");    events.onmessage = (event) => setUnread(JSON.parse(event.data).unread);    return () => events.close();  }, []);  return <NotificationBell count={unread} onClick={onOpen} />;}

Props

count= 0
number
Unread notifications. Going up rings the bell.
max= 99
number
Above this the badge reads 99+.
variant= "count"
"count" | "dot"
A dot hides the number.
size= 44
number
Diameter in px; everything scales from it.
label= "Notifications"
string
The button's name; the count is added to it.
ringKey
string | number
Change it to ring without changing the count.
...button props
ButtonHTMLAttributes
onClick, disabled and the rest go on the button.

Accessibility and motion

  • Reduced motion: no swing, no jump, no nudge. The count still updates and is still announced.
  • Colours come from your theme. The button has a small real shadow, on the object only, so it still sits inside any header.
  • Use the Notification inbox when you also want the list; this is the bell alone, for a list of your own.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

The CLI also installs Number roll.

Source

"use client";import * as React from "react";import { NumberRoll } from "./number-roll";import { INTERACTION_FOCUS, INTERACTION_PRESS, MATERIAL_LIFT, createSpring, useInteractionReducedMotion, type Spring } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * NOTIFICATION BELL: a bell that behaves like one * *   ring     a new notification hits the bell: it takes a push *            sized by how many came, added to whatever swing it *            already has, so a burst rings harder instead of *            starting over *   clapper  nothing animates it: it reads the bell's speed and *            falls behind on a softer spring of its own *   badge    jumps with each hit and leans against the swing; the *            count rolls up or down *   read     the count falling never rings; at zero the badge *            shrinks away * * Reduced motion: the count changes in place and the bell stays still. * ───────────────────────────────────────────────────────── */export interface NotificationBellProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {  /** Unread notifications. Going up rings the bell. */  count?: number;  /** Above this the badge says "99+". */  max?: number;  /** "dot" hides the number. */  variant?: "count" | "dot";  /** Diameter in px. */  size?: number;  /** The button's name; the count is added to it. */  label?: string;  /** Change this to ring without changing the count. */  ringKey?: string | number;}// A heavy thing on a light hinge: it keeps swinging for a while. Speeds are degrees per second.const SWING = { stiffness: 150, damping: 3.4 };const CLAPPER = { stiffness: 210, damping: 8 };const BADGE = { stiffness: 420, damping: 15 };const HIT = 210;const HIT_MOST = 360;const FASTEST = 480;const CLAPPER_LAG = 0.058;const CLAPPER_MOST = 24;const BADGE_LEAN = 0.11;const BELL = "M12 2.2a1.35 1.35 0 0 0-1.33 1.59C7.87 4.42 6 6.87 6 9.9v2.72c0 1.1-.46 2.16-1.27 2.91l-.52.48c-.84.78-.29 2.19.86 2.19h13.86c1.15 0 1.7-1.41.86-2.19l-.52-.48A3.97 3.97 0 0 1 18 12.62V9.9c0-3.03-1.87-5.48-4.67-6.11A1.35 1.35 0 0 0 12 2.2Z";const clamp = (n: number, limit: number) => Math.max(-limit, Math.min(limit, n));const ROLL_FORMAT: Intl.NumberFormatOptions = { maximumFractionDigits: 0, useGrouping: false };export function NotificationBell({ count = 0, max = 99, variant = "count", size = 44, label = "Notifications", ringKey, className = "", style, onPointerEnter, ...props }: NotificationBellProps) {  const reduced = useInteractionReducedMotion();  const total = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;  const bodyRef = React.useRef<SVGGElement>(null);  const clapperRef = React.useRef<SVGGElement>(null);  const badgeRef = React.useRef<HTMLSpanElement>(null);  const shineId = React.useId();  const springs = React.useRef<{ swing: Spring; clapper: Spring; badge: Spring } | null>(null);  // The badge keeps its last number while it shrinks away, so it never empties on the way out.  const [shown, setShown] = React.useState(total);  if (total > 0 && total !== shown) setShown(total);  const previous = React.useRef(total);  React.useLayoutEffect(() => {    const paint = () => {      const s = springs.current;      if (!s) return;      const swing = s.swing.get();      bodyRef.current?.setAttribute("transform", `rotate(${swing.toFixed(2)} 12 3.4)`);      // The clapper hangs from the bell: while the bell moves one way, it's left behind the other way.      s.clapper.set(clamp(-s.swing.getVelocity() * CLAPPER_LAG, CLAPPER_MOST));      clapperRef.current?.setAttribute("transform", `rotate(${s.clapper.get().toFixed(2)} 12 17)`);      const badge = badgeRef.current;      if (badge) {        const scale = Math.max(0, s.badge.get());        badge.style.transform = `translate3d(${(-swing * BADGE_LEAN).toFixed(2)}px, 0, 0) scale(${scale.toFixed(3)})`;        badge.style.opacity = `${Math.min(1, scale * 2.5)}`;      }    };    const s = {      swing: createSpring(0, SWING, paint, 0.02),      clapper: createSpring(0, CLAPPER, paint, 0.02),      badge: createSpring(previous.current > 0 ? 1 : 0, BADGE, paint, 0.002),    };    springs.current = s;    paint();    return () => {      s.swing.stop();      s.clapper.stop();      s.badge.stop();      springs.current = null;    };  }, []);  const hit = React.useCallback((strength: number) => {    const s = springs.current;    if (!s) return;    const moving = s.swing.getVelocity();    // With the swing it's moving in, so a second hit adds to it; capped so a flood doesn't spin the bell over.    const along = moving === 0 ? (s.swing.get() > 0 ? -1 : 1) : Math.sign(moving);    s.swing.push(clamp(moving + along * strength, FASTEST) - moving);  }, []);  React.useEffect(() => {    const s = springs.current;    const delta = total - previous.current;    previous.current = total;    if (!s) return;    if (reduced) {      s.badge.jump(total > 0 ? 1 : 0);      return;    }    s.badge.set(total > 0 ? 1 : 0);    if (delta <= 0) return;    hit(HIT + (HIT_MOST - HIT) * (Math.min(delta, 5) / 5));    s.badge.push(Math.min(delta, 5) * 0.9 + 2.4);  }, [total, reduced, hit]);  const lastRing = React.useRef(ringKey);  React.useEffect(() => {    if (lastRing.current === ringKey) return;    lastRing.current = ringKey;    if (!reduced) hit(HIT);  }, [ringKey, reduced, hit]);  const dot = variant === "dot";  const name = total > 0 ? `${label}, ${total} unread` : label;  const over = shown > max;  const badgeSize = size * (dot ? 0.24 : 0.42);  return (    <span className="relative inline-flex">      <button        type="button"        aria-label={name}        {...props}        onPointerEnter={(event) => {          onPointerEnter?.(event);          // A nudge under the mouse, so it plainly hangs loose.          if (event.pointerType === "mouse" && !reduced && Math.abs(springs.current?.swing.getVelocity() ?? 0) < 40) hit(46);        }}        className={`relative grid cursor-pointer place-items-center rounded-full bg-[linear-gradient(to_bottom,var(--background),color-mix(in_oklab,var(--foreground)_4%,var(--background)))] text-foreground ${MATERIAL_LIFT} ${INTERACTION_PRESS} ${INTERACTION_FOCUS} ${className}`}        style={{ width: size, height: size, ...style }}      >        <svg viewBox="0 0 24 24" aria-hidden="true" className="overflow-visible [contain:layout]" style={{ width: size * 0.58, height: size * 0.58 }}>          <defs>            {/* Polished metal: a band of light down the left of the dome, falling away to the right. */}            <linearGradient id={shineId} x1="0" x2="1" y1="0" y2="0.18">              <stop offset="0.08" stopColor="var(--background)" stopOpacity="0.06" />              <stop offset="0.3" stopColor="var(--background)" stopOpacity="0.5" />              <stop offset="0.5" stopColor="var(--background)" stopOpacity="0.12" />              <stop offset="1" stopColor="var(--background)" stopOpacity="0" />            </linearGradient>          </defs>          <g ref={bodyRef}>            {/* Behind the body, so only the part below the rim shows. */}            <g ref={clapperRef}>              <path d="M12 16.5v3.1" stroke="currentColor" strokeWidth="1.1" strokeLinecap="round" />              <circle cx="12" cy="20.6" r="1.95" fill="var(--primary)" />            </g>            <path fill="currentColor" d={BELL} />            <path fill={`url(#${shineId})`} d={BELL} />            {/* The rim: a bright lip along the flare, so the mouth of the bell reads as a separate edge. */}            <path d="M5.2 16.3c1.6.5 3.9.8 6.8.8s5.2-.3 6.8-.8" fill="none" stroke="var(--background)" strokeOpacity="0.34" strokeWidth="0.7" strokeLinecap="round" />          </g>        </svg>      </button>      <span        ref={badgeRef}        aria-hidden="true"        className="pointer-events-none absolute grid origin-center place-items-center rounded-full bg-primary font-semibold leading-none text-primary-foreground will-change-transform"        style={{          right: dot ? size * 0.15 : size * 0.02,          top: dot ? size * 0.13 : size * -0.04,          height: badgeSize,          minWidth: badgeSize,          padding: dot ? 0 : `0 ${size * 0.08}px`,          fontSize: size * 0.235,          boxShadow: "0 0 0 2px var(--background)",          transform: "scale(0)",        }}      >        {!dot && <NumberRoll value={Math.min(shown, max)} format={ROLL_FORMAT} suffix={over ? "+" : ""} duration={620} />}      </span>      <span role="status" className="sr-only">        {total > 0 ? `${total} unread` : ""}      </span>    </span>  );}export default NotificationBell;

Registry item: /r/notification-bell.json