Feedback

NotificationBell

A bell that rings itself — count, hover pill, sound, and a modal.

A notification bell that shows an unread count, expands into a dark "Notifications" pill on hover, and periodically rings (a damped bell-wobble) while there are unread items — pausing when its modal is open and ringing on every new arrival. Ships its own chime (opt-in, swappable) and opens a centered, focus-trapped modal whose body is a headless slot you fill with rows and badges. Counts cap at 9+, light / dark / auto themes, reduced-motion safe.

Installation

Add the package. A self-contained bell button — an unread badge, a hover pill that names itself, a periodic ring, an opt-in chime, and a centered portal modal with a headless body. It ships its own CSS and its own default sound, so there's nothing else to wire up.

pnpm add @roy-ui/ui

Import

import { NotificationBell } from '@roy-ui/ui';

// or just this component:
import { NotificationBell } from '@roy-ui/ui/notification-bell';

Usage

At rest it's a circular bell with a rose count badge. Hover or focus it and it animates open into a dark pill that spells out its label and count. Click it and a centered modal opens over a dimmed backdrop — and its body is entirely yours: children is a headless slot, so you render the rows, badges, and empty states however you like.

Bell with a modal list

Pass a count for the badge and a title for the modal header. Everything inside children is the modal body — map your own notifications into whatever markup fits. Close it with the button, Escape, or a click on the backdrop; focus returns to the bell.

tsx

const notifications = [
  { id: 1, who: 'Ava', text: 'mentioned you in Design Review', when: '2m' },
  { id: 2, who: 'Build', text: 'pipeline #418 passed', when: '14m' },
  { id: 3, who: 'Noah', text: 'requested your review', when: '1h' },
];

<NotificationBell count={notifications.length} title="Notifications">
  <ul className="my-feed">
    {notifications.map((n) => (
      <li key={n.id} className="my-feed__row">
        <strong>{n.who}</strong> {n.text}
        <span className="my-feed__when">{n.when}</span>
      </li>
    ))}
  </ul>
</NotificationBell>

Ring & sound

While count > 0 the bell rings on a timer — a short, damped wobble every ringInterval milliseconds (1700 by default). It also rings once immediately whenever count goes up, so a fresh notification always announces itself, and it pauses entirely while the modal is open. Sound is a separate, opt-in layer that is OFF by default — the bell rings silently unless you set sound, because browsers block autoplay until the user interacts with the page. So leaving sound out (or sound={false}) is how you mute it. Point soundSrc at your own file to replace the chime, use volume (0–1) to set the level, and set ring to false to keep the badge but stop the motion.

Silent by default — no sound

Out of the box the bell makes no sound. Hit “Send notification” and watch it shake (and the badge climb) with zero audio. This is the muted state; you do not need to disable anything.

tsx

// No sound prop → silent. The bell still rings (shakes) on new arrivals.
<NotificationBell count={unread} title="Notifications">
  {/* …rows… */}
</NotificationBell>

// Being explicit is equivalent:
<NotificationBell count={unread} sound={false}>{/* … */}</NotificationBell>

Opt in to the chime

Add sound to play the bundled chime on each ring. It stays quiet until you have clicked somewhere on the page (the browser's autoplay rule), then “Send notification” both shakes and dings. Swap the sound with soundSrc and set the level with volume.

tsx

<NotificationBell
  count={unread}
  ring                 // wobble while there are unread items (default true)
  ringInterval={1700}  // ms between rings (the default cadence)
  sound                // opt-in: play a chime on each ring
  soundSrc="/sounds/ping.mp3" // optional: override the bundled chime
  volume={0.5}         // 0–1
>
  {/* …rows… */}
</NotificationBell>

Theming

theme is 'light' | 'dark' | 'auto' (the default 'auto' follows prefers-color-scheme). Every surface — the resting button, the hover pill, the badge, and the modal card and backdrop — is a CSS variable, so you can re-brand any piece without touching the markup.

Light

Dark

Variables

.royui-bell {
  --royui-bell-accent: #f43f5e;     /* count badge */
  --royui-bell-pill-bg: #16181d;    /* dark hover pill */
  --royui-bell-pill-fg: #ffffff;
  --royui-bell-surface: #ffffff;    /* resting button */
}
.royui-bell-modal {
  --royui-modal-surface: #ffffff;   /* modal card */
  --royui-modal-backdrop: rgba(15,17,21,0.42);
}

Props

Nothing is required — an empty bell renders with a zero badge. Pass count to drive the badge and ring, and children to fill the modal.

Prop	Type	Default	Description
`count`	`number`	`0`	Unread count shown in the badge and used to drive the ring.
`max`	`number`	`9`	Cap the badge; anything higher reads as `${max}+` (12 → "9+").
`label`	`string`	`'Notifications'`	Text shown inside the dark hover/focus pill.
`ring`	`boolean`	`true`	Whether the bell wobbles while there are unread items.
`ringInterval`	`number`	`1700`	Milliseconds between rings while count > 0.
`sound`	`boolean`	`false`	Opt-in: play a chime on each ring (off due to autoplay rules).
`soundSrc`	`string`	`—`	Override the bundled chime with your own audio file.
`volume`	`number`	`0.5`	Chime volume, 0–1.
`title`	`ReactNode`	`'Notifications'`	Heading shown in the modal header.
`children`	`ReactNode`	`—`	Headless modal body slot — you render the rows.
`footer`	`ReactNode`	`—`	Optional content pinned to the bottom of the modal.
`open`	`boolean`	`—`	Controlled open state.
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state.
`onOpenChange`	`(open: boolean) => void`	`—`	Fires when the modal opens or closes.
`closeOnBackdrop`	`boolean`	`true`	Close the modal when the dimmed backdrop is clicked.
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Follow the system or force a side.
`className`	`string`	`—`	Extra class on the bell root.

NotificationBell

A bell that rings itself — count, hover pill, sound, and a modal.

Usage

const notifications = [ { id: 1, who: 'Ava', text: 'mentioned you in Design Review', when: '2m' }, { id: 2, who: 'Build', text: 'pipeline #418 passed', when: '14m' }, { id: 3, who: 'Noah', text: 'requested your review', when: '1h' }, ]; <NotificationBell count={notifications.length} title="Notifications"> <ul className="my-feed"> {notifications.map((n) => ( <li key={n.id} className="my-feed__row"> <strong>{n.who}</strong> {n.text} <span className="my-feed__when">{n.when}</span> </li> ))} </ul> </NotificationBell>

Ring & sound

// No sound prop → silent. The bell still rings (shakes) on new arrivals. <NotificationBell count={unread} title="Notifications"> {/* …rows… */} </NotificationBell> // Being explicit is equivalent: <NotificationBell count={unread} sound={false}>{/* … */}</NotificationBell>

<NotificationBell count={unread} ring // wobble while there are unread items (default true) ringInterval={1700} // ms between rings (the default cadence) sound // opt-in: play a chime on each ring soundSrc="/sounds/ping.mp3" // optional: override the bundled chime volume={0.5} // 0–1 > {/* …rows… */} </NotificationBell>

.royui-bell { --royui-bell-accent: #f43f5e; /* count badge */ --royui-bell-pill-bg: #16181d; /* dark hover pill */ --royui-bell-pill-fg: #ffffff; --royui-bell-surface: #ffffff; /* resting button */ } .royui-bell-modal { --royui-modal-surface: #ffffff; /* modal card */ --royui-modal-backdrop: rgba(15,17,21,0.42); }

Prop

Type

Default

Description

count

number

0

Unread count shown in the badge and used to drive the ring.

max

number

9

Cap the badge; anything higher reads as `${max}+` (12 → "9+").

label

string

'Notifications'

Text shown inside the dark hover/focus pill.

ring

boolean

true

Whether the bell wobbles while there are unread items.

ringInterval

number

1700

Milliseconds between rings while count > 0.

sound

boolean

false

Opt-in: play a chime on each ring (off due to autoplay rules).

soundSrc

string

—

Override the bundled chime with your own audio file.

volume

number

0.5

Chime volume, 0–1.

title

ReactNode

'Notifications'

Heading shown in the modal header.

children

ReactNode

—

Headless modal body slot — you render the rows.

footer

ReactNode

—

Optional content pinned to the bottom of the modal.

open

boolean

—

Controlled open state.

defaultOpen

boolean

false

Uncontrolled initial open state.

onOpenChange

(open: boolean) => void

—

Fires when the modal opens or closes.

closeOnBackdrop

boolean

true

Close the modal when the dimmed backdrop is clicked.

theme

'light' | 'dark' | 'auto'

'auto'

Follow the system or force a side.

className

string

—

Extra class on the bell root.