README

Laravel Toaster Magic is a lightweight, dependency-free toast notification package for Laravel with Livewire v3 & v4 support.

Laravel Toaster Magic provides elegant, fully customizable toast notifications for Laravel applications — with zero dependency on jQuery, Bootstrap, or Tailwind CSS. It works out of the box with Livewire, supports multiple modern themes, and is simple enough to drop into any project in minutes.

🚀 Live Demo

👉 Try the Live Demo

✨ Features

🔥 Easy to Use — Simple, intuitive API with support for both static and fluent syntax.
🌍 RTL Support — Full compatibility with right-to-left languages.
🌙 Dark Mode — Built-in dark mode support via a single HTML attribute.
🎨 7+ Themes — iOS, Neon, Glassmorphism, Material, Minimal, Neumorphism, and Default.
🎞️ Entrance/Exit Animations — Choose how toasts enter and leave: slide, fade, pop, or bounce.
🪄 Smooth Stack Reflow — Remaining toasts glide into place (FLIP) when one is added or dismissed. Respects prefers-reduced-motion.
🖼️ Avatar Toasts — Render an image in place of the type icon for notification-style toasts.
⚡ Livewire Ready — First-class support for Livewire v3 & v4 with event-based dispatching.
🔒 Safe Button Links — Custom button URLs are sanitized before being rendered into the DOM. See the Security section for how message content is handled.
✅ Zero Dependencies — No jQuery, Bootstrap, or Tailwind required.

📦 Installation

Install the package via Composer:

composer require devrabiul/laravel-toaster-magic

Publish the package assets:

php artisan vendor:publish --provider="Devrabiul\ToastMagic\ToastMagicServiceProvider"

Note: Assets are also auto-published on the first page load and automatically refreshed whenever the package is updated.

⚙️ Basic Setup

Add the stylesheet inside your <head> tag and the scripts just before the closing </body> tag:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Page Title</title>

    {!! ToastMagic::styles() !!}
</head>
<body>

    <!-- Your Content -->

    {!! ToastMagic::scripts() !!}
</body>
</html>

🧑‍💻 Usage

1. Controller Usage

Trigger toast notifications from your controllers using the ToastMagic facade:

use Devrabiul\ToastMagic\Facades\ToastMagic;

public function store()
{
    // Simple message
    ToastMagic::success('Successfully Created');

    // Message with description
    ToastMagic::success('Success!', 'Your data has been saved!');

    // With custom options
    ToastMagic::success('Success!', 'Your data has been saved!', [
        'showCloseBtn' => true,
        'customBtnText' => 'View Record',
        'customBtnLink' => 'https://example.com',
        'timeOut' => 10000,    // Optional: override the auto-dismiss time (ms) for this toast only
        'showDuration' => 300, // Optional: override the show animation delay (ms) for this toast only
    ]);

    return back();
}

Available toast types: success, info, warning, error

You can also pass a validation MessageBag directly — its messages are flattened into a single toast, one per line:

ToastMagic::error($validator->errors());

🖼️ Avatar / notification-style toasts

Pass an avatar URL to render an image in place of the type icon — ideal for "new message" / "new follower" style notifications:

ToastMagic::info('New message', 'Hey, are you free to chat?', [
    'avatar' => $user->avatar_url,
]);

2. JavaScript Usage

Use ToastMagic directly in JavaScript for AJAX responses or client-side events:

const toastMagic = new ToastMagic();

toastMagic.success('Success!', 'Your data has been saved!');
toastMagic.error('Error!', 'Something went wrong.');
toastMagic.warning('Warning!', 'Check your input.', true);
toastMagic.info('Info!', 'Click for details.', false, 'Learn More', 'https://example.com');

// Programmatically dismiss all visible toasts
toastMagic.clear();      // or toastMagic.dismissAll();

Signature: toastMagic.{type}(heading, description, showCloseBtn, customBtnText, customBtnLink, timeOut, showDuration, avatar)

timeOut and showDuration are optional per-toast overrides (in milliseconds). avatar is an optional image URL shown in place of the type icon. When omitted, the global config values are used.

3. Livewire Support (v3 & v4)

Enable Livewire support in your config file:

// config/laravel-toaster-magic.php

return [
    'options' => [
        // your toast options...
    ],
    'livewire_enabled' => true,
    'livewire_version' => 'v3', // 'v3' or 'v4'
];

Dispatch toast notifications from any Livewire component:

// With full options
$this->dispatch('toastMagic',
    status: 'success',
    title: 'User Created',
    message: 'The user has been successfully created.',
    options: [
        'showCloseBtn' => true,
        'customBtnText' => 'View Profile',
        'customBtnLink' => 'https://example.com',
    ],
);

// Simple dispatch
$this->dispatch('toastMagic',
    status: 'info',
    title: 'Heads Up',
    message: 'Your session will expire soon.'
);

Supported status values: success, info, warning, error

Backward Compatibility: Both showCloseBtn and closeButton option keys are supported in Livewire events. If both are provided, showCloseBtn takes priority.

4. Alternative & Fluent Syntax

ToastMagic supports both a quick static method and a fluent dispatch style.

Static (Quick):

use Devrabiul\ToastMagic\Facades\ToastMagic;

ToastMagic::success('Operation Successful');
ToastMagic::error('Something went wrong');

Fluent (Advanced):

ToastMagic::dispatch()->success(
    'User Created',
    'The user has been successfully created.',
    [
        'showCloseBtn'  => true,
        'customBtnText' => 'View Profile',
        'customBtnLink' => 'https://example.com',
    ]
);

📍 Position Options

Control where toasts appear on screen using the positionClass config option:

Value	Position
`toast-top-start`	Top left
`toast-top-end`	Top right (default)
`toast-top-center`	Top center
`toast-bottom-start`	Bottom left
`toast-bottom-end`	Bottom right
`toast-bottom-center`	Bottom center

🎨 Themes

ToastMagic includes 7 built-in themes. Set your preferred theme in config/laravel-toaster-magic.php:

return [
    'options' => [
        "theme" => "default", // See options below
    ],
];

Theme	Description
`default`	Clean, classic look
`material`	Material Design — flat and bold
`ios`	Apple-style notifications with backdrop blur
`glassmorphism`	Heavy blur, semi-transparent, modern aesthetic
`neon`	Dark background with glowing borders — ideal for dark UIs
`minimal`	Clean design with colored left-side accent
`neumorphism`	Soft UI with extruded shadow styling

For a full theme preview, see THEMES.md.

🌈 Color Mode

Enable color mode to apply toast-type colors automatically to backgrounds and accents:

return [
    'options' => [
        'color_mode' => true,
    ],
];

🌟 Gradient Mode

Enable gradient mode to apply subtle gradients to toast backgrounds:

return [
    'options' => [
        "gradient_enable" => true,
    ],
];

Note: Gradient mode works best with the default, material, and neon themes.

🎞️ Animations

Choose how toasts enter and leave the screen using the animation config option:

return [
    'options' => [
        'animation' => 'slide', // default, slide, fade, pop, bounce
    ],
];

Value	Effect
`default`	Slide in from the toast's position (default)
`slide`	Same as default — explicit slide
`fade`	Fade in/out with no movement
`pop`	Scale up from slightly smaller, with a soft overshoot
`bounce`	Slide in with a springy overshoot

Smooth stack reflow: When a toast is added or dismissed, the remaining toasts glide smoothly into their new positions (using the FLIP technique) instead of jumping. This honors the user's prefers-reduced-motion setting and requires no configuration.

🌙 Dark Mode

Add theme="dark" to your <body> tag to enable dark mode globally:

<body theme="dark">

⚙️ Full Configuration Reference

// config/laravel-toaster-magic.php

return [
    'options' => [
        'closeButton'       => true,
        'positionClass'     => 'toast-top-end',
        'preventDuplicates' => false,
        'showDuration'      => 300,
        'timeOut'           => 5000,
        'theme'             => 'default', // default, material, ios, glassmorphism, neon, minimal, neumorphism
        'gradient_enable'   => false,
        'color_mode'        => false,
        'pauseOnHover'      => true, // Pause the auto-dismiss timer while hovering a toast
        'animation'         => 'default', // default, slide, fade, pop, bounce
    ],
    'livewire_enabled'  => false,
    'livewire_version'  => 'v3',
];

🔒 Security

Custom button links (customBtnLink) are validated before being rendered into href attributes. Only URLs starting with http://, https://, /, or # are allowed; all other values are safely replaced with #.

Message content is rendered as HTML. The toast heading and description are inserted into the DOM as HTML — this is what enables multi-line messages (newlines become <br>). Because of this, you should never pass unescaped, user-supplied input directly into a toast, as it can introduce a cross-site scripting (XSS) vulnerability. If a value may contain user input, escape it first — for example with Laravel's e() helper or strip_tags():

ToastMagic::success('Welcome, ' . e($user->name) . '!');

Roadmap: A future major release (v3.0.0) will escape message content by default, with an opt-in flag for cases where HTML is intentional.

📝 Changelog

See CHANGELOG.md for a list of notable changes in each release.

🤝 Contributing

Contributions are welcome! Please fork the repository, make your changes, and open a pull request. For bug reports or feature requests, open an issue on GitHub.

📄 License

This package is open-source software licensed under the MIT License.

🌱 Treeware

This package is Treeware. If you use it in production, we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you'll be creating employment for local families and restoring wildlife habitats.

📬 Contact & Links

🔗 GitHub: devrabiul/laravel-toaster-magic
🔗 Live Demo: laravel-toaster-magic.rixetbd.com
🔗 Packagist: packagist.org/packages/devrabiul/laravel-toaster-magic
📧 Email: devrabiul@gmail.com

devrabiul / laravel-toaster-magic

Maintainers

Package info

Statistics

Security