elegantly/livewire-modal

Livewire Modals. Done Right.

This package allows you to seamlessly open Livewire components inside modals or slideovers with powerful features:

• Support for modals, slideovers, and similar UI patterns.
• Nested and stacked modals.
• Custom styling and animations, with optional presets.
• Preloading components for faster interactions.

Requirements

• livewire/livewire: v4
• tailwindcss: v3 (not yet tested with v4)

How It Works

This package provides a single Livewire Modal component that should be placed at the end of your body tag. This component dynamically renders and manages all modal instances while maintaining a modal history.

Modals can be opened and closed by dispatching modal-open and modal-close events.

For security, only components you explicitly allow can be opened in a modal (see Allowing Components).

Installation

Install the package via Composer:

composer require elegantly/livewire-modal

To customize modal behavior, publish the views with:

php artisan vendor:publish --tag="livewire-modal-views"

Usage

Configuring Tailwind CSS

Since the modal component is styled using Tailwind CSS, you must include its views in your Tailwind configuration file:

export default {
    content: [
        "./vendor/elegantly/livewire-modal/resources/views/**/*.blade.php",
    ],
};

Setting Up Your Application

Add the modal manager component <livewire:modal /> at the end of your body tag, typically in your layout views:

<body>
    ...
    <livewire:modal />
</body>

Allowing Components

The list of opened modals is sent by the browser, so anyone can ask the modal manager to render any component with any props. To prevent this, the modal manager refuses (403) every component that has not been explicitly allowed.

Allow a component by implementing the ModalComponent contract:

use Elegantly\LivewireModal\Contracts\ModalComponent;
use Livewire\Component;

class ShowUser extends Component implements ModalComponent
{
    // ...
}

To allow components you can't modify (from a vendor package for example), publish the config file and list them by name or class:

php artisan vendor:publish --tag="livewire-modal-config"

return [
    'components' => [
        'users.show',
        \Vendor\Package\Livewire\Component::class,
    ],
];

Props must be passed by name ({ userId: 1 }); positional props ([1]) are refused.

[!WARNING] Props come from the browser and must be treated as untrusted input, even on #[Locked] properties: they are assigned before mount() runs. A component opened in a modal also does not run the middleware of its own route (auth, can, Filament's panel access, ...), only those of the page hosting <livewire:modal />. Always authorize in mount() and in every action:

public function mount(User $user): void
{
    $this->authorize('view', $user);
}

Preparing Your Modals

Any allowed Livewire component can be displayed as a modal. However, certain features, such as stacking, require additional customization.

Creating a Simple Modal Component

This package provides two Blade components to simplify stacking and positioning:

• x-livewire-modal::stack: Provides a basic layout with stacking capabilities.
• x-livewire-modal::modal: Handles positioning and stacking.

Wrap your content within these components:

<x-livewire-modal::stack>
    <x-livewire-modal::modal
        position="center"
        class="w-full max-w-md overflow-auto rounded-lg bg-white p-5"
    >
        <div class="prose">
            <p>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam
                rhoncus, augue eget vulputate vehicula, justo dui auctor est, at
                iaculis urna orci ut nunc.
            </p>
        </div>
    </x-livewire-modal::modal>
</x-livewire-modal::stack>

Controlling the Modal Position

By default, modals are centered, but their position can be adjusted using the position prop:

<x-livewire-modal::stack>
    <x-livewire-modal::modal position="left"> ... </x-livewire-modal::modal>
</x-livewire-modal::stack>

<x-livewire-modal::stack>
    <x-livewire-modal::modal position="bottom"> ... </x-livewire-modal::modal>
</x-livewire-modal::stack>

Fullscreen Modal

To make a modal fullscreen, use the fullscreen prop:

<x-livewire-modal::stack fullscreen> ... </x-livewire-modal::stack>

Creating a Slideover Component

<x-livewire-modal::stack>
    <x-livewire-modal::slideover
        class="w-full max-w-md overflow-auto rounded-lg bg-white p-5"
    >
        <div class="prose">
            <p>
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam
                rhoncus, augue eget vulputate vehicula, justo dui auctor est, at
                iaculis urna orci ut nunc.
            </p>
        </div>
    </x-livewire-modal::slideover>
</x-livewire-modal::stack>

Opening a Modal

To open a modal, dispatch a modal-open event:

<button x-modal:open="{ modal: 'users.show', props: { userId: 1 } }">
    Open
</button>

<button
    x-on:click="$dispatch('modal-open', { modal: 'users.show', props: { userId: 1 } })"
>
    Open
</button>

Livewire.dispatch("modal-open", {
    modal: "users.show",
    props: { userId: 1 },
});

Preloading a Modal

To preload a modal, dispatch a modal-preload event with the same props used to open it:

Livewire.dispatch("modal-preload", {
    modal: "users.show",
    props: { userId: 1 },
});

Preloading a Modal on Hover

Using the custom Alpine directive, you can preload a modal when the user starts hovering over a button. This improves UX by ensuring faster modal openings.

<button x-modal:open.preload="{ modal: 'users.show', props: { userId: 1 } }">
    Preload and Open
</button>

Closing the Current Modal

To close the currently active modal, dispatch a modal-close event:

<button x-modal:close>Close</button>

<button x-on:click="$dispatch('modal-close')">Close</button>

Livewire.dispatch("modal-close");

Closing All Modals

To close all modals at once:

<button x-modal:close-all>Close</button>

<button x-on:click="$dispatch('modal-close-all')">Close All</button>

Livewire.dispatch("modal-close-all");

Testing

Run the test suite with:

composer test

Changelog

For recent changes, see CHANGELOG.

Contributing

See CONTRIBUTING for contribution guidelines.

Security Vulnerabilities

For information on reporting security vulnerabilities, please review our security policy.

Credits

• Quentin Gabriele
• All Contributors

License

This package is licensed under the MIT License. See License File for details.