About LivewireUI Modal
LivewireUI Modal is a Livewire component that provides you with a modal that supports multiple child modals while maintaining state.
Installation
Click the image above to read a full article on using the Livewire UI modal package or follow the instructions below.
To get started, require the package via Composer:
composer require livewire-ui/modal
Livewire directive
Add the Livewire directive @livewire('livewire-ui-modal')
and also the Javascript @livewireUIScripts
directive to your template.
<html>
<body>
<!-- content -->
@livewire('livewire-ui-modal')
@livewireUIScripts
</body>
</html>
Next you will need to publish the required scripts with the following command:
php artisan vendor:publish --tag=livewire-ui:public --force
Important: When updating to a newer version of LivewireUI modal make sure to run the command again with the --force
flag.
Alpine
Livewire UI requires Alpine. You can use the official CDN to quickly include Alpine:
<script src="https://cdn.jsdelivr.net/gh/alpinejs/[email protected]/dist/alpine.min.js" defer></script>
TailwindCSS
The base modal is made with TailwindCSS. If you use a different CSS framework I recommend that you publish the modal template and change the markup to include the required classes for your CSS framework.
php artisan vendor:publish --tag=livewire-ui:views
Creating a modal
You can run php artisan make:livewire EditUser
to make the initial Livewire component. Open your component class and make sure it extends the ModalComponent
class:
<?php
namespace App\Http\Livewire;
use LivewireUI\Modal\ModalComponent;
class EditUser extends ModalComponent
{
public function render()
{
return view('livewire.edit-user');
}
}
Opening a modal
To open a modal you will need to emit an event. To open the EditUser
modal for example:
<!-- Outside of any Livewire component -->
<button onclick="Livewire.emit('openModal', 'edit-user')">Edit User</button>
<!-- Inside existing Livewire component -->
<button wire:click="$emit('openModal', 'edit-user')">Edit User</button>
Passing parameters
To open the EditUser
modal for a specific user we can pass the user id (notice the single quotes):
<!-- Outside of any Livewire component -->
<button onclick='Livewire.emit("openModal", "edit-user", {{ json_encode(["user" => $user->id]) }})'>Edit User</button>
<!-- Inside existing Livewire component -->
<button wire:click='$emit("openModal", "edit-user", {{ json_encode(["user" => $user->id]) }})'>Edit User</button>
<!-- Example of passing multiple parameters -->
<button wire:click='$emit("openModal", "edit-user", {{ json_encode([$user->id, $isAdmin]) }})'>Edit User</button>
The parameters are passed to the mount
method on the modal component:
<?php
namespace App\Http\Livewire;
use App\Models\User;
use LivewireUI\Modal\ModalComponent;
class EditUser extends ModalComponent
{
public User $user;
public function mount(User $user)
{
Gate::authorize('update', $user);
$this->user = $user;
}
public function render()
{
return view('livewire.edit-user');
}
}
Opening a child modal
From an existing modal you can use the exact same event and a child modal will be created:
<!-- Edit User Modal -->
<!-- Edit Form -->
<button wire:click='$emit("openModal", "delete-user", {{ json_encode(['user' => $user->id]) }})'>Delete User</button>
Closing a (child) modal
If for example a user clicks the 'Delete' button which will open a confirm dialog, you can cancel the deletion and return to the edit user modal by emitting the closeModal
event. This will open the previous modal. If there is no previous modal the entire modal component is closed and the state will be reset.
<button wire:click="$emit('closeModal')">No, do not delete</button>
You can also close a modal from within your modal component class:
<?php
namespace App\Http\Livewire;
use App\Models\User;
use LivewireUI\Modal\ModalComponent;
class EditUser extends ModalComponent
{
public User $user;
public function mount(User $user)
{
Gate::authorize('update', $user);
$this->user = $user;
}
public function update()
{
Gate::authorize('update', $user);
$this->user->update($data);
$this->closeModal();
}
public function render()
{
return view('livewire.edit-user');
}
}
If you don't want to go to the previous modal but close the entire modal component you can use the forceClose
method:
public function update()
{
Gate::authorize('update', $user);
$this->user->update($data);
$this->forceClose()->closeModal();
}
Often you will want to update other Livewire components when changes have been made. For example, the user overview when a user is updated. You can use the closeModalWithEvents
method to achieve this.
public function update()
{
Gate::authorize('update', $user);
$this->user->update($data);
$this->closeModalWithEvents([
UserOverview::getName() => 'userModified',
]);
}
It's also possible to add parameters to your events:
public function update()
{
$this->user->update($data);
$this->closeModalWithEvents([
UserOverview::getName() => ['userModified', [$this->user->id],
]);
}
Changing modal properties
You can change the width (default value '2xl') of the modal by overriding the static modalMaxWidth
method in your modal component class:
/**
* Supported: 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl', '6xl', '7xl'
*/
public static function modalMaxWidth(): string
{
return 'xl';
}
By default, the modal will close when you hit the escape
key. If you want to disable this behavior to, for example, prevent accidentally closing the modal you can overwrite the static closeModalOnEscape
method and have it return false
.
public static function closeModalOnEscape(): bool
{
return false;
}
By default, the modal will close when you click outside the modal. If you want to disable this behavior to, for example, prevent accidentally closing the modal you can overwrite the static closeModalOnClickAway
method and have it return false
.
public static function closeModalOnClickAway(): bool
{
return false;
}
Skipping previous modals
In some cases you might want to skip previous modals. For example:
- Team overview modal
- -> Edit Team
- -> Delete Team
In this case, when a team is deleted, you don't want to go back to step 2 but go back to the overview.
You can use the skipPreviousModal
method to achieve this. By default it will skip the previous modal. If you want to skip more you can pass the number of modals to skip skipPreviousModals(2)
.
<?php
namespace App\Http\Livewire;
use App\Models\Team;
use LivewireUI\Modal\ModalComponent;
class DeleteTeam extends ModalComponent
{
public Team $team;
public function mount(Team $team)
{
$this->team = $team;
}
public function delete()
{
Gate::authorize('delete', $this->team);
$this->team->delete();
$this->skipPreviousModal()->closeModalWithEvents([
TeamOverview::getName() => 'teamDeleted'
]);
}
public function render()
{
return view('livewire.delete-team');
}
}
Security
If you are new to Livewire I recommend to take a look at the security details. In short, it's very important to validate all information given Livewire stores this information on the client-side, or in other words, this data can be manipulated. Like shown in the examples above, use the Guard
facade to authorize actions.
Credits
License
Livewire UI is open-sourced software licensed under the MIT license.