jantinnerezo / livewire-alert
This package provides a simple alert utilities for your livewire components.
Installs: 726 428
Dependents: 22
Suggesters: 0
Security: 0
Stars: 744
Watchers: 12
Forks: 79
Open Issues: 0
Requires
- php: ^8.1
- illuminate/support: ^10.0|^11.0|^12.0
- livewire/livewire: ^3.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.70
- orchestra/testbench: ^8.0|^9.0|^10.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^9.5|^10.0|^11.5.3
- dev-master
- v4.x-dev
- 4.0.x-dev
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0
- 2.2.7
- 2.2.6
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.9
- 2.1.8
- 2.1.7
- 2.1.6
- 2.1.5
- 2.1.4
- 2.1.3
- 2.1.2
- 2.1.1
- 2.1
- 2.0.2
- 2.0.1
- 2.0
- 1.2.0
- v1.0
- dev-bugfix/all-events-triggers
- dev-feat/livewire-3-beta-support
- dev-jantinnerezo-patch-1
- dev-fix/failing-test
- dev-patch-2
- dev-hotfix/2.2.6
- dev-hotfix-2.2.3
- dev-feature/emit-performance
- dev-bugfix/extra-parameters
- dev-experimental-2.1.9
- dev-publishable
- dev-config
- dev-experimental
This package is auto-updated.
Last update: 2025-03-14 04:47:24 UTC
README
Livewire Alert is a Laravel Livewire package designed to integrate SweetAlert2 notifications seamlessly into Livewire projects. This package simplifies the process of displaying simple, customizable alerts to users, enhancing the interactivity and user experience of your Livewire projects.
You can check the interactive demo here: livewire-alert.laravel.cloud
Requirements
- PHP 8.1 or higher
- Laravel 10.x or higher
- Livewire 3.x
- Composer
Installation
First, require the package with Composer:
composer require jantinnerezo/livewire-alert
Optionally, if you want to customize the global configuration, you can publish the config file:
php artisan vendor:publish --tag=livewire-alert:config
Next, install SweetAlert2 via npm or yan:
NPM
npm install sweetalert2
Yarn
yarn add sweetalert2
After installing SweetAlert2, import it into your resources/js/app.js
file
import Swal from 'sweetalert2' window.Swal = Swal
If you prefer not to use package manager installation, you can include SweetAlert2 directly via CDN. Add the following script to your Blade layout file (e.g., resources/views/layouts/app.blade.php)
before the closing </body>
tag:
<body> <script src="https://cdn.jsdelivr.net/npm/sweetalert2@11"></script> </body>
Filament
Integrate Livewire Alert in your Filament project, simply register the JavaScript asset in the boot method of your AppServiceProvider
to import SweetAlert2.
use Filament\Support\Facades\FilamentAsset; use Illuminate\Support\Facades\Vite; use Filament\Support\Assets\Js; public function boot() { FilamentAsset::register([ // Local asset build using Vite Js::make('sweetalert2', Vite::asset('resources/js/sweetalert2.js')), // Or via CDN Js::make('sweetalert2', 'https://cdn.jsdelivr.net/npm/sweetalert2@11'), ]); }
Usage
This package provides a convenient Facade that allows you to trigger customizable SweetAlert2-based alerts in your Laravel Livewire application. The Facade uses a fluent interface, enabling you to chain methods to configure your alert before displaying it.
Basic Usage
use Jantinnerezo\LivewireAlert\Facades\LivewireAlert; public function save() { LivewireAlert::title('Changes saved!') ->success() ->show(); }
Adding text
LivewireAlert::title('Item Saved') ->text('The item has been successfully saved to the database.') ->success() ->show();
Available alert icons
LivewireAlert::title('Success')->success();
LivewireAlert::title('Error')->error();
LivewireAlert::title('Warning')->warning();
LivewireAlert::title('Info')->info();
LivewireAlert::title('Question')->question();
Position
The position()
method allows you to specify where the alert appears on the screen. You can use either the Position enum for type safety or a plain string for flexibility.
Using the Position Enum
Leverage the Position enum for predefined, type-safe options:
use Jantinnerezo\LivewireAlert\Enums\Position; LivewireAlert::title('Question') ->position(Position::Center) ->question() ->show();
Using a String Value
Alternatively, you can pass a string directly, but it must exactly match one of the Position
enum values, See: Position enum.
LivewireAlert::title('Question') ->position('center') ->question() ->show();
Toast Notification
Create a toast-style alert with the toast()
method:
LivewireAlert::title('Welcome!') ->text('You have logged in successfully.') ->info() ->toast() ->position('top-end') ->show();
Timer
The timer()
method sets an auto-dismiss timer for the alert, specifying how long (in milliseconds) the alert remains visible before closing automatically.
Usage
Pass an integer representing the duration in milliseconds:
LivewireAlert::title('Success') ->text('Operation completed successfully.') ->success() ->timer(3000) // Dismisses after 3 seconds ->show();
Buttons
The LivewireAlert package provides methods to add and customize buttons in your alerts: withConfirmButton()
, withCancelButton()
, and withDenyButton()
. Each button can trigger specific events, handled via onConfirm()
, onDeny()
, or onDismiss()
, allowing you to execute custom logic in your Livewire component.
Confirm
LivewireAlert::title('Save?') ->withConfirmButton('Yes, Save') ->show();
Cancel
LivewireAlert::title('Hey cancel') ->withCancelButton('Cancel') ->show();
Deny
LivewireAlert::title('Are you do you want to do it?') ->withDenyButton('No') ->show();
Button text
Alternatively, you can use confirmButtonText()
, cancelButtonText()
, and denyButtonText()
to set the text after enabling the buttons with withConfirmButton()
, withCancelButton()
, or withDenyButton()
without text:
LivewireAlert::title('Save?') ->withConfirmButton() // Enables button with default text ->confirmButtonText('Yes') ->withDenyButton() // Enables button with default text ->denyButtonText('No') ->withCancelButton() // Enables button with default text ->cancelButtonText('Cancel') ->show();
Button Color
You can customize the appearance of buttons by setting their colors using the confirmButtonColor()
, cancelButtonColor()
, and denyButtonColor()
methods. These methods accept a color value (e.g., color names, hex codes, or CSS-compatible strings) to style the respective buttons.
LivewireAlert::title('Save?') ->confirmButtonColor('green') ->withDenyButton('red') ->withCancelButton('blue') ->show();
Button Events
Each button can trigger a corresponding event when clicked, allowing you to handle user interactions in your Livewire component.
onConfirm()
LivewireAlert::title('Save?') ->withConfirmButton('Save') ->onConfirm('saveData', ['id' => $this->itemId]) ->show(); public function saveData($data) { $itemId = $data['id']; // Save logic }
onDismiss()
LivewireAlert::title('Delete?') ->withConfirmButton('Delete') ->withCancelButton('Keep') ->onDismiss('cancelDelete', ['id' => $this->itemId]) ->show(); public function cancelDelete($data) { $itemId = $data['id']; // Cancel logic }
onDeny()
LivewireAlert::title('Update?') ->withConfirmButton('Update') ->withDenyButton('Discard') ->onDeny('discardChanges', ['id' => $this->itemId]) ->show(); public function discardChanges($data) { $itemId = $data['id']; // Discard logic }
Using them together example
LivewireAlert::title('Process File') ->text('What would you like to do?') ->question() ->withConfirmButton('Save') ->withCancelButton('Cancel') ->withDenyButton('Delete') ->onConfirm('saveFile', ['id' => $this->fileId]) ->onDeny('deleteFile', ['id' => $this->fileId]) ->onDismiss('cancelAction', ['id' => $this->fileId]) ->show();
Confirm Dialog
The asConfirm()
method configures the alert as a confirmation dialog with a predefined options. It automatically applies a question icon, adds confirm and deny buttons with default text from the configuration, and disables the auto-dismiss timer, making it ideal for scenarios requiring explicit user input.
LivewireAlert::title('Are you sure?') ->text('Do you want to proceed with this action?') ->asConfirm() ->show();
Handling Events
Combine with onConfirm()
and onDeny()
to handle user responses:
LivewireAlert::title('Delete Item') ->text('Are you sure you want to delete this item?') ->asConfirm() ->onConfirm('deleteItem', ['id' => $this->itemId]) ->onDeny('keepItem', ['id' => $this->itemId]) ->show(); public function deleteItem($data) { $itemId = $data['id']; // Delete logic } public function keepItem($data) { $itemId = $data['id']; // Keep logic }
Inputs
The LivewireAlert package allows you to add input fields to alerts using the withOptions()
method, leveraging SweetAlert2’s input capabilities. This is useful for collecting user input (e.g., text, selections) directly within the alert, with the input value returned via event handlers like onConfirm()
.
Usage
Use withOptions()
to pass an array containing SweetAlert2 input options. Common input types include text
, email
, password
, number
, textarea
, select
, radio
, checkbox
, and file
.
Add a simple text input:
LivewireAlert::title('Enter Your Name') ->withOptions([ 'input' => 'text', 'inputPlaceholder' => 'Your name here', ]) ->withConfirmButton('Submit') ->onConfirm('saveName') ->show(); public function saveName($data) { $name = $data['value']; // User’s input from the text field // Save the name }
Select Input Example
LivewireAlert::title('Choose an Option') ->withOptions([ 'input' => 'select', 'inputOptions' => [ 'small' => 'Small', 'medium' => 'Medium', 'large' => 'Large', ], 'inputPlaceholder' => 'Select a size', ]) ->withConfirmButton('Confirm') ->onConfirm('processSelection') ->show(); public function processSelection($data) { $size = $data['value']; // Selected value (e.g., 'small') // Process the selection }
Handling Input Values
When an input is present, the $data
parameter in event methods (e.g., onConfirm()
, onDeny()
) includes a value property containing the user’s input. This value depends on the input type:
- Text, email, password, number, textarea: The entered string or number.
- Select, radio: The selected option’s key.
- Checkbox: true or false.
- File: The file data (if applicable).
Flash Alert
Need to flash alerts across requests? In this package you can leverage Laravel’s session flashing alerts and display them in your Livewire components. This feature, inspired by version 3’s simplicity, gives you full freedom to define your own session keys and structure, allowing tailored flash alerts that appear automatically (e.g., on mount())
after actions like redirects.
public function mount() { if (session()->has('saved')) { LivewireAlert::title(session('saved.title')) ->text(session('saved.text')) ->success() ->show(); } } public function changesSaved() { session()->flash('saved', [ 'title' => 'Changes Saved!', 'text' => 'You can safely close the tab!', ]); $this->redirect('/dashboard'); }
Options
The withOptions()
method allows you to extend the alert’s configuration with any SweetAlert2-compatible options, giving you full control to customize its appearance, behavior, or functionality beyond the built-in methods. This is ideal for advanced use cases like adding inputs, modifying styles, or setting custom SweetAlert2 features.
LivewireAlert::title('Custom Alert') ->text('This alert has a unique style.') ->success() ->withOptions([ 'width' => '400px', 'background' => '#f0f0f0', 'customClass' => ['popup' => 'animate__animated animate__bounceIn'], 'allowOutsideClick' => false, ]) ->show();
For a comprehensive guide to customization and available configuration options, please refer to the SweetAlert2 documentation.
Dependency Injection
Who said you can only use the Facade? With this package, you can also inject the Jantinnerezo\LivewireAlert\LivewireAlert
class directly into your Livewire component methods via dependency injection. This approach lets you access the alert functionality within the context of your component, offering a clean alternative to the Facade syntax.
use Jantinnerezo\LivewireAlert\LivewireAlert; public function save(LivewireAlert $alert) { $alert->title('Success!') ->text('What would you like to do?') ->question() ->withConfirmButton('Save') ->withCancelButton('Cancel') ->withDenyButton('Delete') ->onConfirm('saveFile', ['id' => $this->fileId]) ->onDeny('deleteFile', ['id' => $this->fileId]) ->onDismiss('cancelAction', ['id' => $this->fileId]) ->show(); }
All methods remain available, and you can chain them fluently just like with the Facade!
Looking for v3?
If you’re seeking documentation for livewire-alert v3, note that the last release of the version 3 series was v3.0.3, available on GitHub at v3.0.3 Released on March 11, 2024, this version supports Livewire 3 and latest Laravel 12 and includes features like basic alert functionality with the LivewireAlert
trait.
This release, however, is a major refactor of the package, introducing a new architecture and enhanced features (like the fluent Facade interface and dependency injection). As a result, the documentation below focuses on v4.
For v3-specific usage:
composer require jantinnerezo/livewire-alert:^3.0
For ongoing projects, I recommend upgrading to v4.0 to take advantage of the improved API and feature set detailed in this documentation.
Testing
composer test
Contributors
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email erezojantinn@gmail.com instead of using the issue tracker.
License
The MIT License (MIT). Please see License File for more information.