Download the PHP package caiquebispo/notification-bell without Composer

Laravel Notification Bell

An elegant, framework-agnostic Laravel package for managing notifications with Livewire, featuring per-user preferences, full dark mode support, zero-build self-contained assets, and a robust delivery pipeline.

Highlights

Zero build, zero publish

The package ships its own self-contained CSS (prefixed nb-), served directly from vendor/ through a package route. No Tailwind, no Bootstrap, no npm run build, no vendor:publish needed — install via Composer, drop the component in your layout, done. It looks right in any project: Tailwind, Bootstrap, or plain CSS.

End-user control

Each user manages their own experience through a preferences panel inside the bell:

• Toggle popup toasts and sounds (with volume control)
• Mute notification categories individually
• "Do not disturb" snooze (1h / 4h / 8h / 24h)
• Daily quiet hours (e.g. 22:00–08:00, midnight-crossing supported)
• Pin important notifications to the top
• Archive instead of delete
• Undo accidental deletions (soft delete + undo toast)
• Clear all notifications in the current tab, with an elegant inline confirmation (no native browser dialogs anywhere)

Robust delivery pipeline

• Deduplication — repeated dedup_key within a time window is dropped
• Rate limiting — per-user per-minute cap against notification floods
• Scheduling & expiry — scheduled_at / expires_at respected automatically
• Smart grouping — N notifications sharing a group_key collapse into one expandable item
• Laravel events — NotificationCreated, NotificationRead, NotificationArchived, NotificationDeleted
• Broadcasting — real-time via Echo/Reverb/Pusher with automatic polling fallback
• REST API — optional JSON endpoints for mobile apps and SPAs
• Soft deletes — nothing is lost by accident; cleanup purges for real
• Test suite — PHPUnit + Testbench covering models, dispatcher, preferences, Livewire component and API

Installation

Add the trait to your User model:

Include the component in your layout (Livewire 3 bundles Alpine.js — nothing else to install):

That's it. The component injects its own stylesheet automatically. If you prefer loading it in the <head>:

Optional publishing

Publishing is optional — only for deep customization:

Theming

Customize the look through config — applied via CSS variables, no build step:

Type colors come from the types section, so custom types get proper colors automatically:

Dark mode (theme.mode):

• auto (default) — follows the host page's explicit markers only: .dark, [data-theme="dark"], or [data-bs-theme="dark"] (Bootstrap). A light site stays light even for users whose OS is in dark mode.
• system — additionally follows the OS prefers-color-scheme when no marker is present.
• dark / light — force one look regardless of the host.

Per-instance overrides

User preferences

Enabled by default. Users open the gear icon inside the bell to control toasts, sound, volume, muted categories, snooze and quiet hours. Persisted in the notification_preferences table.

Programmatic access:

Categories

Group notifications above the type level. Users can mute categories they don't care about:

A notification sent to a user who muted its category is silently skipped.

Creating notifications

Action buttons

Delivery guards

Events

React in your app without coupling to the package:

Broadcasting (real-time)

With Laravel Echo (Reverb/Pusher) configured in the host app, the bell listens over websockets. Register the channel authorization in your routes/channels.php:

If Echo is absent, the component keeps working via polling.

REST API

For mobile apps and SPAs:

All endpoints operate strictly on the authenticated user's own notifications.

History page

A full-page notification center at /notifications/history with search, filters (status, type, category, period), pin/archive actions and incremental loading. Linked from the bell's "View all" footer. Disable with 'features' => ['history_page' => false].

Admin panel

Comprehensive management panel at /notifications (configurable): create/edit/delete, filters, send to one or all users, bulk actions, stats — fully redesigned with self-contained CSS.

Localization

Ships with English (default) and Brazilian Portuguese. By default the component follows app()->getLocale(), falling back to English. To force a language regardless of the app locale:

Or per component instance:

This applies to every text in the bell, history page and admin panel — including relative dates ("há 4 meses" instead of "4 months ago"). To customize the strings:

Sounds

Generated with the Web Audio API (no audio files) — unique tones per type — or bring your own file:

Browsers may block audio until the user interacts with the page (standard autoplay policy).

Artisan commands

Schedule cleanup in routes/console.php (or Kernel.php on older versions):

Queues

Notifications are processed through Laravel queues by default. Run a worker:

Or bypass per call with 'queue' => false in the options array.

Testing

The suite uses Orchestra Testbench with in-memory SQLite — no app scaffolding required.

Deploy safety

The package is designed to never take a production page down:

• Migrations are idempotent and reconciling — partial previous runs, pre-existing tables or re-runs never fail the deploy; missing columns are added individually.
• Schema-readiness guard — between composer update and php artisan migrate, the bell detects the outdated schema and renders empty (logging a warning) instead of throwing a QueryException on every page. It recovers automatically on the first request after the migration runs.
• Queued deliveries hitting a stale schema fail and retry through the queue — no notification is silently lost.

Feature toggles

Every user-facing capability can be turned off individually:

Upgrading from 1.x

• If you had published the config before, re-publish it with php artisan vendor:publish --tag="notification-bell-config" --force to see the new keys (locale, theme, preferences, categories, deduplication, rate_limit, api...). An old published config keeps working — missing keys fall back to the package defaults.
• New migrations add columns (category, group_key, dedup_key, image_url, pinned_at, archived_at, scheduled_at, expires_at, deleted_at) and the notification_preferences table — just run php artisan migrate.
• Notification::delete() is now a soft delete. Cleanup routines purge trashed rows.
• The helper signature is backward compatible; new capabilities live in the trailing $options array.
• The old Tailwind-dependent views were replaced by self-contained CSS. If you had published the views, re-publish or port your customizations to theme.item_view / theme.bell_icon.

License

MIT License - see the LICENSE file for details.