jeremykenedy/laravel-toast

Table of Contents

• Framework Support
• Screenshots
  • Settings Page
• Requirements
• Installation
  • Tailwind Setup
  • Bootstrap Setup
  • Livewire Setup
• Quick Start
  • Blade
  • Livewire
  • Sharing Toasts with Inertia
  • Vue
  • React
  • Svelte
• Features
• Configuration
  • Per-Toast Options
  • JavaScript Container Props
• Animations
• Styles and Dark Mode
  • Customizing Colors
• Notification Settings
  • Routes
• Usage
  • Facade and Trait
  • Livewire Events
  • Broadcasting
• Changing Frameworks
  • Update
  • Switch
• Artisan Commands
  • Install Options
  • Publishing Assets
• Testing
• Documentation
• File Tree
• Contributing
• Changelog
• License

Framework Support

Every pairing ships framework-appropriate colors and supports the same toast payload. JavaScript components select their classes from the payload's css_framework, or from an explicit cssFramework prop.

Screenshots

The React container renders success, error, warning, and info notifications below using each supported CSS framework. Screenshots show the package's default colors in light and dark mode, with auto-dismiss disabled. Select an image to view it at full size.

CSS framework	Light mode	Dark mode
Tailwind v4
Bootstrap 5.2+
Bootstrap 4

To refresh these screenshots from the actual components, install the development dependencies and Chromium, then run:

npm ci
npx playwright install chromium
npm run screenshots

Settings Page

Captured from the settings page running in a Laravel application, with light and dark mode edited for the success and info types and every other color left on Default. The first image in each pair is the color pickers, the second is the live preview. Select an image to view it at full size.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12, or 13
• Tailwind v4, Bootstrap 5.2+, or Bootstrap 4 CSS
• Alpine.js for Tailwind Blade; Livewire 3 or 4 for the Livewire container; or Vue 3, React 18, or Svelte 4 / 5
• Laravel broadcasting, a queue worker, and Laravel Echo for optional real-time delivery
• A database table, only if you enable the optional notification settings

Bootstrap Blade toasts work without jQuery or the Bootstrap JavaScript bundle. CI selects Laravel 10 through 13 and both supported Livewire majors.

Installation

composer require jeremykenedy/laravel-toast
php artisan toast:install

The installer publishes config/toast.php and records your framework choices in .env. If configuration already exists, it detects the installation and asks before reinstalling. Use toast:update or toast:switch to preserve customized configuration. --force permits reinstalling and replacing the configuration; published views are retained.

Tailwind Setup

Register the package templates and components in resources/css/app.css:

@import "tailwindcss";
@source "../../vendor/jeremykenedy/laravel-toast/resources";

Tailwind does not automatically scan ignored dependency directories. Keep your application's other imports and sources, and run npm run build after adding this source.

For Tailwind Blade, load Alpine.js once in your application. If it is not already installed:

npm install alpinejs

import Alpine from 'alpinejs'

window.Alpine = Alpine
Alpine.start()

Livewire provides its own Alpine instance. Do not start a second instance in a Livewire application.

Bootstrap Setup

Load the selected Bootstrap stylesheet in your application and choose the matching toast framework:

php artisan toast:switch --css=bootstrap5
npm run build

Livewire Setup

If Livewire is not already installed:

composer require livewire/livewire

Use the Livewire container shown below and follow Livewire's normal application asset setup.

Quick Start

Create notifications with the helper or facade:

use Jeremykenedy\LaravelToast\Facades\Toast;

toast('Settings saved.');
toast('Upload failed.', 'error', 'Error');
Toast::warning('Low storage.', duration: 3000);
Toast::success('Step 1 done.')->info('Starting step 2.');

Blade

Place the directive before </body> in your layout:

@toasts

@include('toast::toasts') is equivalent. Standard string flash messages are converted automatically and shown once:

return back()->with('success', 'Profile updated.');

Livewire

<livewire:toast-container />

From another Livewire component:

$this->dispatch('toast', message: 'Saved!', type: 'success');
$this->dispatch('toast-error', message: 'Upload failed.');

Sharing Toasts with Inertia

Share the payload on each response from your Inertia middleware's share() method:

use Jeremykenedy\LaravelToast\Facades\Toast;

return array_merge(parent::share($request), [
    'toasts' => function () {
        if (config('toast.convert_flash', true)) {
            Toast::convertFlashMessages();
        }

        return Toast::get();
    },
]);

Mount one container in your layout. The examples below assume that the layout file lives in resources/js/Layouts/; adjust the relative import if needed. Updated initialToasts arrays enqueue new IDs without replaying dismissed messages.

Vue

<script setup>
import ToastContainer from '../../../vendor/jeremykenedy/laravel-toast/resources/js/vue/pages/ToastContainer.vue'

defineProps({ toasts: { type: Array, default: () => [] } })
</script>

<template>
    <slot />
    <ToastContainer :initial-toasts="toasts" />
</template>

React

import ToastContainer from '../../../vendor/jeremykenedy/laravel-toast/resources/js/react/pages/ToastContainer.jsx'

export default function AppLayout({ children, toasts = [] }) {
    return <>{children}<ToastContainer initialToasts={toasts} /></>
}

Svelte

<script>
    import ToastContainer from '../../../vendor/jeremykenedy/laravel-toast/resources/js/svelte/pages/ToastContainer.svelte'
    export let toasts = []
</script>

<slot />
<ToastContainer initialToasts={toasts} />

The JavaScript containers also accept window.__toasts as an initial fallback:

<script>
    window.__toasts = {{ Illuminate\Support\Js::from(Toast::get()) }};
</script>

Later updates should use initialToasts or a broadcast subscription. Changing window.__toasts after mounting does not enqueue notifications.

Features

• Four notification types with optional titles and custom SVG icons
• All 15 CSS/frontend combinations, including Bootstrap JavaScript components
• Reactive SPA notifications with ID deduplication and bounded visible stacks
• Global defaults and per-toast options
• Enter and exit animations, reduced-motion support, and manual dismissal
• Hover and keyboard-focus pause, progress bars, RTL, and dark mode
• Session flash conversion and optional private broadcasts
• Translations for 42 locales and a dismissLabel prop for JavaScript frontends
• Optional settings page with color pickers, live light and dark previews, and every behavior option, saved to your database and available for Blade, Livewire, Vue, React and Svelte in all three CSS frameworks

Configuration

php artisan vendor:publish --tag=toast-config

All environment settings are optional. Configure them in your application's .env or edit the published configuration. When configuration is cached, run php artisan config:cache after changing environment values.

TOAST_FRONTEND records the setup for Artisan commands. Your layout decides which frontend renders. TOAST_CSS selects Blade/Livewire views and supplies the JavaScript payload's CSS framework.

When laravel-ui-kit is installed and toast has no explicit override, commands update UI_KIT_CSS and UI_KIT_FRONTEND. An existing TOAST_CSS or TOAST_FRONTEND override is updated directly, so the command changes the setting that actually controls toast. Clear those overrides to resume following the kit.

Per-Toast Options

duration is a separate method argument in milliseconds; 0 keeps the toast until manual dismissal. Configuration-only settings such as broadcasting and session storage are not per-toast options.

toast()->success('Saved!', 'Done', 3000, [
    'position' => 'bottom-right',
    'dir' => 'rtl',
    'stack' => false,
    'show_border' => false,
    'enter_animation' => 'slide-right',
    'exit_animation' => 'fade',
    'progress_position' => 'bottom',
]);

JavaScript Container Props

Animations

49 animation styles, plus none, available for both enter_animation and exit_animation. Every style ships an enter and an exit keyframe, and all of them work in every CSS framework and frontend. Directionless names (e.g., slide, bounce) use a sensible default (typically center or right):

Enter and exit animations have independent duration controls (enter_duration, exit_duration).

Styles and Dark Mode

Blade and Livewire inline the package keyframes and the selected Bootstrap theme. JavaScript components import the shared animation, theme, and layout styles themselves. Importing components directly from vendor/ keeps those relative imports intact. If you copy a component into your application, update its stylesheet imports and its toast-options.js import to their package paths.

toast-css publishes all three stylesheets for applications that prefer their own CSS entry points.

Tailwind uses your application's dark: variant configuration. Bootstrap supports .dark or data-bs-theme="dark" on an ancestor, and the operating-system preference when no Bootstrap theme is selected. An explicit data-bs-theme="light" or .light ancestor prevents automatic dark colors. All Bootstrap theme overrides are scoped to the package's toast markers.

Customizing Colors

The quickest way to change colors is the notification settings page, or the colors config key. To go further, publish the Blade/Livewire views and edit their actual classes:

php artisan vendor:publish --tag=toast-views

For JavaScript components, override the scoped classes in your stylesheet after loading the package:

[data-laravel-toast="component"].bg-green-50 {
    background-color: #d1fae5;
    color: #065f46;
}

[data-laravel-toast][data-css-framework="bootstrap4"].alert-success {
    background-color: #d1fae5;
    color: #065f46;
}

[data-bs-theme="dark"] [data-laravel-toast].alert-success {
    background-color: #064e3b !important;
    color: #d1fae5 !important;
}

Use .text-bg-success instead of .alert-success for Bootstrap 5. Keep selectors scoped so other application alerts and badges retain their colors.

Notification Settings

Let people with the right permission change every notification color and behavior option from the browser, with a live preview, and save the result to your database. It is off by default; nothing is created or exposed until you enable it.

php artisan toast:install --settings --settings-page --settings-layout=layouts.app
php artisan migrate

Define who may use it, in a service provider (an undefined gate denies everyone):

Gate::define('manage-toast-settings', fn ($user) => $user->can('manage-site'));

Then place the panel wherever you want it, or use the page at /toast/settings:

The page can extend your own Blade layout (--settings-layout, --settings-section) and run your own middleware (--settings-middleware). Colors can also be set without the UI through the colors config key. Saved values override config/toast.php; anything never saved falls back to config. See docs/settings.md for the full guide, configuration, request format and security notes.

Routes

Registered only when TOAST_SETTINGS_ENABLED=true. Every route runs settings.middleware (default web, auth) and then the gate.

Usage

Facade and Trait

use Jeremykenedy\LaravelToast\Facades\Toast;

Toast::success('Saved.');
Toast::error('Failed.', 'Error');
Toast::warning('Low storage.');
Toast::info('Update available.');
Toast::clear();

Controllers may use Jeremykenedy\LaravelToast\Traits\HasToasts for toastSuccess(), toastError(), toastWarning(), and toastInfo().

Livewire Events

$this->dispatch('toast', message: 'Saved!', type: 'success', duration: 3000);
$this->dispatch('toast-success', message: 'Created!');
$this->dispatch('toast-error', message: 'Failed!');
$this->dispatch('toast-warning', message: 'Low storage.');
$this->dispatch('toast-info', message: 'Update available.');

$this->dispatch('toast', message: 'RTL toast', type: 'info', options: [
    'dir' => 'rtl',
    'exit_animation' => 'slide-left',
]);

Broadcasting

Configure Laravel's broadcast connection and Echo, and run a queue worker. Toast broadcasts are queued after the current database transaction commits. See Laravel broadcasting setup.

TOAST_BROADCAST_ENABLED=true
TOAST_BROADCAST_CHANNEL=toast.{userId}

Authorize the private channel in your application's routes/channels.php:

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('toast.{userId}', function ($user, $userId) {
    return (string) $user->getAuthIdentifier() === (string) $userId;
});

If you customize the channel template, change the authorization pattern and client subscription accordingly. The package does not register application authentication routes or authorization policies.

Send a notification to an explicit recipient from a controller, service, or job:

use Jeremykenedy\LaravelToast\Facades\Toast;

Toast::broadcast($user->getAuthIdentifier(), 'Your export is ready.', 'success');

broadcast() does not write a session toast and is inactive when broadcast.enabled is false. Ordinary success(), error(), and other session methods remain session-only.

The Livewire container subscribes to the authenticated user's channel when broadcasting is enabled and Echo is available. On Blade pages requiring live updates, use <livewire:toast-container /> instead of the session-only @toasts directive.

For Vue, React, or Svelte, set the container's channel prop to toast.{actualUserId} and provide echo if your instance is not window.Echo:

<ToastContainer initialToasts={toasts} channel={`toast.${user.id}`} echo={echo} />

Each container removes its own listener on unmount or a channel change. For a custom frontend, import listenForToasts from resources/js/toast-options.js in the package and provide your own callback. It returns an unsubscribe function.

Changing Frameworks

Use update or switch after installation to preserve customized configuration and views. An existing toast-specific override remains in control and is updated directly; otherwise the ui-kit setting is updated when available.

Update

php artisan toast:update
php artisan toast:update --css=bootstrap5 --frontend=vue

The interactive flow offers framework selection and confirmation. Passing flags updates the specified settings without replacing the configuration file.

Switch

php artisan toast:switch --css=bootstrap5
php artisan toast:switch --frontend=livewire

After switching, load the selected framework's CSS, use the corresponding layout component, and run npm run build. When switching to Tailwind, register the package source described in Installation.

Artisan Commands

Install Options

The settings flags are validated before any file is written. The commands never run migrations and never define the gate. Without a settings flag, an interactive run asks whether to add the settings page; a --no-interaction run changes nothing about settings.

All commands accept Artisan's --no-interaction flag. A noninteractive reinstall requires --force.

Publishing Assets

php artisan vendor:publish --tag=toast-config
php artisan vendor:publish --tag=toast-views
php artisan vendor:publish --tag=toast-lang
php artisan vendor:publish --tag=toast-css
php artisan vendor:publish --tag=toast-settings-migrations
php artisan vendor:publish --tag=toast-settings-page

Testing

Frontend tests and screenshot capture require Node.js 22 (22.12 or newer), 24, or 26+. The Svelte component retains Svelte 4 syntax and is tested with Svelte 5's mounting API.

composer test
composer lint
npm ci
npm test
npx playwright install chromium
npm run test:browser

PHP tests use a protected in-memory SQLite configuration that fails the run if any other database is configured. Only the opt-in settings feature reads and writes a table, and its tests do so in that in-memory database. Frontend tests compile and mount Vue, React, and Svelte, execute Blade/Livewire timers, and exercise updates, replacement, broadcasting, animations, and cleanup. Chromium tests cover all nine SPA/CSS combinations, a Tailwind build with explicit package sources, and Bootstrap theme isolation.

Run PHP tests that do not require Livewire with:

./vendor/bin/pest --ci --exclude-group livewire

Documentation

File Tree

Main package files and directories, with translation and test files grouped by directory:

laravel-toast/
├── .github/workflows/tests.yml       # PHP, frontend, browser, and style checks
├── art/
│   ├── banner-dark.svg
│   ├── banner-light.svg
│   └── screenshots/                 # Toast previews and settings page captures
├── config/toast.php                 # Package defaults and environment settings
├── database/migrations/             # Opt-in settings table migration stub
├── docs/settings.md                 # Notification settings guide
├── resources/
│   ├── css/
│   │   ├── toast-animations.css
│   │   ├── toast-components.css
│   │   ├── toast-settings.css
│   │   └── toast-themes.css
│   ├── js/
│   │   ├── react/pages/{ToastContainer,ToastSettings}.jsx
│   │   ├── svelte/pages/{ToastContainer,ToastSettings}.svelte
│   │   ├── vue/pages/{ToastContainer,ToastSettings}.vue
│   │   ├── toast-colors.js          # Color stylesheet generator shared with PHP
│   │   ├── toast-options.js         # Shared options and Echo subscriptions
│   │   ├── toast-settings-panel.js  # Blade settings panel script
│   │   └── toast-settings-shared.js # Shared logic for the JavaScript settings components
│   ├── lang/                       # Translations grouped by locale
│   └── views/
│       ├── bootstrap4/blade/          # toasts, settings, settings-page, layout
│       ├── bootstrap5/blade/          # toasts, settings, settings-page, layout
│       ├── livewire/
│       │   ├── bootstrap4/            # toast-container, toast-settings
│       │   ├── bootstrap5/            # toast-container, toast-settings
│       │   ├── partials/timer-script.blade.php
│       │   ├── toast-container.blade.php
│       │   └── toast-settings.blade.php
│       ├── shared/settings-script.blade.php
│       └── tailwind/blade/            # toasts, settings, settings-page, layout
├── routes/web.php                   # Settings routes, registered only when enabled
├── scripts/capture-screenshots.mjs
├── src/
│   ├── Console/                    # Install, update, and switch commands
│   ├── Events/ToastBroadcast.php
│   ├── Facades/Toast.php
│   ├── Http/                       # Settings controller, form request, middleware
│   ├── Livewire/{ToastContainer,ToastSettings}.php
│   ├── Models/ToastSetting.php
│   ├── Providers/ToastServiceProvider.php
│   ├── Services/ToastManager.php
│   ├── Support/                    # ToastAnimations, ToastColors, ToastSettings
│   ├── Traits/HasToasts.php
│   └── helpers.php
├── tests/
│   ├── Browser/                    # Browser fixture and Chromium checks
│   ├── Feature/                    # Laravel and Livewire integration tests
│   ├── Frontend/                   # Mounted components and timer tests
│   ├── Unit/                       # Payload, animation, and database safety tests
│   ├── Pest.php
│   └── TestCase.php
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── composer.json
├── package.json
├── phpunit.xml
├── pint.json
├── playwright.config.js
├── vite.config.js
└── vitest.config.js

Contributing

See CONTRIBUTING.md. Report security issues through SECURITY.md.

Changelog

See CHANGELOG.md.

License

This package is open-sourced software licensed under the MIT license.