Beautiful toast notifications for Livewire
Toaster provides a seamless experience to display toast notifications in your Livewire powered Laravel apps.
Unlike many other toast implementations that are available, Toaster makes it effortless to dispatch a toast notification
from either a standard Controller or a Livewire Component. You don't have to think about "flashing" things to the
session or "dispatching browser events" from your Livewire components. Just dispatch your toast and Toaster will route the message accordingly.
Showcase
Compatibility
| Livewire | PHP | Laravel |
|---|---|---|
| | | [LW2](https://laravel-livewire.com/docs/2.x) | [LW3](https://livewire.laravel.com/docs) | |-|-|-| | [1.x](https://github.com/masmerise/livewire-toaster/tree/1.3.0) | ✅ | ❌ | | 2.x | ❌ | ✅ | | | | PHP 8.2 | PHP 8.3 | |-|-|-| | 1.0 - ∞ | ✅ | ✅ | | | | L10 | L11 | |-|-|-| | 1.0 - 2.1 * | ✅ | ❌ | | 2.2 - ∞ | ❌ | ✅ | |
* feature complete
Contents
Looking for v1 docs? Click here.
Installation
You can install the package via composer:
composer require masmerise/livewire-toasterYou can publish the package's config file:
php artisan vendor:publish --tag=toaster-configThis is the contents of the toaster.php config file:
return [
/**
* Add an additional second for every 100th word of the toast messages.
*
* Supported: true | false
*/
'accessibility' => true,
/**
* The vertical alignment of the toast container.
*
* Supported: "bottom", "middle" or "top"
*/
'alignment' => 'bottom',
/**
* Allow users to close toast messages prematurely.
*
* Supported: true | false
*/
'closeable' => true,
/**
* The on-screen duration of each toast.
*
* Minimum: 3000 (in milliseconds)
*/
'duration' => 3000,
/**
* The horizontal position of each toast.
*
* Supported: "center", "left" or "right"
*/
'position' => 'right',
/**
* Whether messages passed as translation keys should be translated automatically.
*
* Supported: true | false
*/
'translate' => true,
];Preparing your template
Next, you'll need to use the <x-toaster-hub /> component in your master template:
<!DOCTYPE html>
<html>
<head>
<!-- ... -->
</head>
<body>
<!-- Application content -->
<x-toaster-hub /> <!-- 👈 -->
</body>
</html>Configuring scripts
After that, you'll need to import Toaster at the top of your resources/js/app.js bundle to start listening to incoming toasts:
import './bootstrap';
import '../../vendor/masmerise/livewire-toaster/resources/js'; // 👈
// other app stuff...Tailwind styles
[!NOTE] Skip this step if you're going to customize Toaster's default view.
Toaster provides a minimal view that utilizes Tailwind CSS defaults.
If the default toast appearances suffice your needs, you'll need to register it with Tailwind's purge list:
module.exports = {
content: [
'./resources/**/*.blade.php',
'./vendor/masmerise/livewire-toaster/resources/views/*.blade.php', // 👈
],
}Otherwise, please refer to View customization.
RTL support
[!NOTE] LTR will be assumed regardless of whether you apply the
ltrattribute or not.
If your app makes use of an RTL language such as Arabic and Hebrew, don't forget to add the rtl attribute to the document root:
<!DOCTYPE html>
<html dir="rtl"> <!-- 👈 -->
...
</html>This will make sure the UI elements (such as the close button) are flipped and the text is properly aligned.
Usage
Sending toasts from the back-end
[!NOTE] Toaster supports the dispatch of multiple toasts at once, you are not limited to dispatching a single toast.
Toaster
The standard recommended way for dispatching toast messages is through the Toaster facade.
use Masmerise\Toaster\Toaster;
final class RegistrationForm extends Component
{
public function submit(): void
{
$this->validate();
User::create($this->form);
Toaster::success('User created!'); // 👈
}
}If you need fine-grained control, you can always use the PendingToast class directly to which Toaster proxies its calls:
use Masmerise\Toaster\PendingToast;
final class RegistrationForm extends Component
{
public function submit(): void
{
$this->validate();
$user = User::create($this->form);
// 👇
PendingToast::create()
->when($user->isAdmin(),
fn (PendingToast $toast) => $toast->message('Admin created')
)
->unless($user->isAdmin(),
fn (PendingToast $toast) => $toast->message('User created')
)
->success();
}
}Toastable
You can make any class Toastable to dispatch toasts from:
use Masmerise\Toaster\Toastable;
final class ProductListing extends Component
{
use Toastable; // 👈
public function check(): void
{
$result = Product::query()
->tap(new Available())
->count();
if ($result < 5) {
$this->warning('The quantity on hand is critically low.'); // 👈
}
}
}Redirects
Whenever you return a RedirectResponse from anywhere in your app, you can chain any of the Toaster methods
to dispatch a toast message:
final class CompanyController extends Controller
{
/** @throws ValidationException */
public function store(Request $request): RedirectResponse
{
$validator = Validator::make($request->all(), [...]);
if ($validator->fails()) {
return Redirect::back()
->error('The form contains several errors'); // 👈
}
Company::create($validator->validate());
return Redirect::route('dashboard')
->info('Company created!'); // 👈
}
}This is, of course, not limited to Controllers as you can also redirect in Livewire Components.
Dependency injection
If you'd like to keep things "pure", you can also inject the Collector contract
and use the ToastBuilder to dispatch your toasts:
use Masmerise\Toaster\Collector;
use Masmerise\Toaster\ToasterConfig;
use Masmerise\Toaster\ToastBuilder;
final readonly class SendEmailVerifiedNotification
{
public function __construct(
private ToasterConfig $config,
private Collector $toasts,
) {}
public function handle(Verified $event): void
{
$toast = ToastBuilder::create()
->duration($this->config->duration)
->success()
->message("Thank you, {$event->user->name}!")
->get();
$this->toasts->collect($toast);
}
}Sending toasts from the front-end
You can invoke the globally available Toaster instance to dispatch any toast message from anywhere:
<button @click="Toaster.success('Form submitted!')">
Submit
</button>Available methods: error, info, warning & success
Automatic translation of messages
[!NOTE] The
translateconfiguration value must be set totrue.
Instead of doing this:
Toaster::success(
Lang::get('path.to.translation', ['replacement' => 'value'])
);Toaster makes it possible to do this:
Toaster::success('path.to.translation', ['replacement' => 'value']);You can mix and match without any problems:
Toaster::info('user.created', ['name' => $user->full_name]);
Toaster::info('You now have full access!');You can do whatever you want, whenever you want.
Accessibility
[!NOTE] The
accessibilityconfiguration value must be set totrue.
Toaster will add an additional second to a toast's on-screen duration for every 100th word. This way, your users will have enough time to read toasts that are a tad larger than usual.
So, if your base duration value is 3 seconds and your toast contains 223 words,
the total on-screen duration of the toast will be 3 + 2 = 5 seconds
Unit testing
[!NOTE] If you make use of automatic translation of messages, you should assert whether the translation keys are passed along correctly instead of the human readable messages that are replaced by Laravel's translator. Otherwise, your tests are going to fail as the messages are not translated during unit testing.
Toaster provides a couple of testing capabilities in order for you to build a robust application:
use Masmerise\Toaster\Toaster;
final class RegisterUserControllerTest extends TestCase
{
#[Test]
public function users_can_register(): void
{
// Arrange
Toaster::fake();
Toaster::assertNothingDispatched();
// Act
$response = $this->post('users', [ ... ]);
// Assert
$response->assertRedirect('profile');
Toaster::assertDispatched('Welcome!');
}
}Extending behavior
Imagine that you'd like to keep track of how many toasts are dispatched daily to display on an admin dashboard. First, create a new class that encapsulates this logic:
final readonly class DailyCountingCollector implements Collector
{
public function __construct(private Collector $next) {}
public function collect(Toast $toast): void
{
// increment the counter on durable storage
$this->next->collect($toast);
}
public function release(): array
{
return $this->next->release();
}
}After that, extend the behavior in your AppServiceProvider:
public function register(): void
{
$this->app->extend(Collector::class,
static fn (Collector $next) => new DailyCountingCollector($next)
);
}That's it!
View customization
Even though the default toasts are pretty, they might not fit your design and you may want to customize them.
You can do so by publishing Toaster's views:
php artisan vendor:publish --tag=toaster-viewsThe hub.blade.php view will be published to your application's resources/views/vendor/toaster directory.
Feel free to modify anything to your liking.
Available viewData
$alignment- can be used to align the toast container vertically depending on the configuration$closeable- whether the close button should be rendered by the Blade component$config- default configuration values, used by the Alpine component$position- can be used to position the toasts depending on the configuration$toasts- toasts that were flashed to the session by Toaster, used by the Alpine component
[!WARNING] You must keep the
x-dataandx-initdirectives and you must keep using thex-forloop. Otherwise, the Alpine component that powers Toaster will start malfunctioning.
Testing
composer testChangelog
Please see CHANGELOG for more information on what has changed recently.
Security
If you discover any security related issues, please email support@muhammedsari.me instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.