Laravel Sonner Laravel Package

Product Decisions This Supports

• Build vs. buy for in-app notifications. This package replaces a hand-rolled toast component (or a generic third-party JS toast library) with a faithful, React-free port of Sonner 2.0.8 — stacked toasts, hover-to-expand, swipe-to-dismiss, pause-on-hover/hidden-tab timers, six positions, RTL, light/dark/system themes, rich colors, and an Alt+T hotkey. The decision to build is now hard to justify unless the UX needs to diverge from Sonner.
• One notification API across the stack. toast() helper, Sonner facade, a browser API that mirrors Sonner (toast.success(), toast.promise(), toast.dismiss(), toast.getToasts()), a <x-sonner /> Blade component, and a sonner:toast event for Alpine/Livewire dispatches. That means one design language whether the trigger is a controller, a Blade view, an Alpine handler, or a Livewire action — a real reduction in per-feature front-end decisions.
• Livewire-era UX roadmap. Livewire 3/4 toasts land in the same response as the action (no flash-then-render round trip), survive wire:navigate, and wait for the next page after a redirect. This unblocks "instant feedback" patterns in Livewire-heavy admin and dashboard surfaces without adding a JS framework.
• Platform upgrade sequencing. Laravel 12 and 13 support (PHP 8.3+) removes a hard blocker if your roadmap includes a framework upgrade, and a line in php artisan about gives support/ops a cheap way to confirm what's deployed.
• Security posture for user-facing messaging. The XSS fix is a product decision, not just a patch: toast text is now set via textContent, and the queue is serialized as JSON with <, >, &, and quotes escaped. Any feature that surfaces user-supplied strings (validation messages, imported names, API error passthrough) in a toast is now safe by default. Treat this as a reason to prioritize the upgrade over the feature work it displaces.
• Config-over-code defaults. config/sonner.php plus full prop parity on <x-sonner /> means design/PM can tune position, theme, and duration without engineering tickets — useful for A/B-ing notification prominence.
• Adoption cost is the dependency, not the integration. v1.0.0 is the first release, and it is a breaking change from the pre-release dev-main: the UsesSonner Livewire trait and the PHP promise() method are gone (use toast.promise() in JS instead), and dark-theme rich-color error/warning toasts are now neutral rather than Sonner's dark red/olive. If anything internal was built against dev-main, budget a short migration rather than assuming a drop-in.

When to Consider This Package

Adopt when most of these hold:

• The stack is Laravel 12 or 13 on PHP 8.3+, with Blade and/or Livewire 3/4 and optionally Alpine.
• You want Sonner's specific interaction model (stacking, swipe, hover-pause, hotkey, RTL) but do not want a React/Node build step in the app.
• You have a Content Security Policy and need a nonce-aware inline script/style — this package threads Laravel's CSP nonce through both.
• You are consolidating inconsistent notification patterns (flash messages, custom jQuery toasts, per-team widgets) into one component.
• You are shipping user-generated or third-party-sourced strings into notifications and want safe-by-default rendering.
• Accessibility and internationalization are on the acceptance criteria — hotkey, RTL, and theme handling are already implemented rather than backlog items.

Look elsewhere or defer when:

• The front end is already React, Vue, or Inertia and already imports Sonner directly — you would be adding a parallel implementation of a component you have.
• You need durable notifications, not ephemeral toasts: an in-app inbox, read/unread state, per-user preferences, digests, email/SMS/push channels. That is Laravel's Notification system plus a persistence layer, not this package. Same for analytics on notification delivery or click-through.
• Your organization requires a vendor with an SLA, security review cadence, or long-term maintenance commitment. This is a single-maintainer package that tracks an upstream JS library; version drift against Sonner is a real, if manageable, ongoing cost.
• You are pre-PHP 8.3 or still on Laravel 10/11 with no upgrade path — this release does not reach back.
• Toast UX is explicitly not wanted for the workflow (e.g., regulated flows requiring acknowledgment before proceeding) — use inline alerts or modals instead.
• You require per-toast state that survives a full page reload, or a queue that persists across redirects beyond Livewire's next-page behavior.

How to Pitch It (Stakeholders)

For executives: This is a free, small-footprint package that gives our Laravel app polished, accessible in-app notifications without hiring front-end specialists or standing up a JavaScript build pipeline. It closes a security gap — user-supplied text in a toast could previously inject HTML into the page — and it unblocks our Laravel 12/13 upgrade, which was gated on it. The main caveat is maintenance risk: it is a single-maintainer package that mirrors an open-source JavaScript library, so we should pin the version and review on our normal dependency cadence rather than assume it is set-and-forget.

For engineering leads: v1.0.0 is the first stable release and is not fully backward compatible with the previous dev-main branch. Two removals to check for: the AmjadIqbal\Sonner\Livewire\UsesSonner trait (no longer needed) and the PHP-side promise() method (call toast.promise() from JavaScript instead). Also note the deliberate dark-theme change for rich-color error and warning toasts, which now use a neutral background — a design review item if anyone has screenshots or specs pinned to the old look. Everything else is additive: the full Sonner prop surface on <x-sonner />, defaults centralized in config/sonner.php, a JSON-serialized queue with proper escaping, textContent rendering, CSP nonce support, and a php artisan about line for deployment verification. Integration is a Blade component plus a facade or helper — no npm, no React, no asset pipeline changes. Livewire 3/4 is first-class, and flashed toasts now correctly leave the session after one render instead of lingering.

Suggested next step: pilot on one surface with user-generated text in the message (the highest-value case for the XSS fix), confirm CSP nonce behavior in staging, then roll out as the standard notification primitive with the version pinned.