# Notification bell

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

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.

## Install

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

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

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`
- Docs and live preview: https://hairlineui.com/ui/notification-bell
- Registry item (source): https://hairlineui.com/r/notification-bell.json

## Usage

```tsx
import { NotificationBell } from "@/components/notification-bell";

<NotificationBell count={unread} onClick={openInbox} />
```

## With your own live count

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

```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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | `0` | Unread notifications. Going up rings the bell. |
| `max` | `number` | `99` | Above this the badge reads 99+. |
| `variant` | `"count" \| "dot"` | `"count"` | A dot hides the number. |
| `size` | `number` | `44` | Diameter in px; everything scales from it. |
| `label` | `string` | `"Notifications"` | 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. |

## 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.

## What it handles

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.

- **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.
- **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.
- **Only arrivals ring**: A count going down never rings. Marking everything read rolls the number and shrinks the badge away holding its last digits.
- **Numbers that fit**: The count rolls in the direction it moved and the badge widens with it; past max it reads 99+.
- **Screen readers**: The button is named with the count, and a status region outside it announces changes.
- **Your click**: It is a real button: pass onClick and any button prop, and open your own inbox from it.

## Replaces

css bell shake keyframes, badge count hand-rolled, framer-motion bell

## Where it fits

- **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.

## Notes

- 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.

License: MIT (https://hairlineui.com/license#components)
