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.
⚡ Livewire Ready — First-class support for Livewire v3 & v4 with event-based dispatching.
🔒 XSS Safe — Custom button URLs are sanitized before rendering into the DOM.
✅ 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',
    ]);

    return back();
}

Available toast types: success, info, warning, error

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');

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

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.

🌙 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,
    ],
    '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 # to prevent XSS attacks.

🤝 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