<x-widget.modal>
Modal Blade component for Laravel and Livewire
Dialogs on <dialog>: centred in four sizes or full screen, drawers from either side or the bottom, and a bottom sheet on phones. Pinned header and footer, Esc, backdrop and swipe-down close, focus return, scroll lock, and modal.confirm() for quick yes/no questions. Works inside Livewire components: it stays open through renders, and opens or closes on modal-open and modal-close events.
php artisan bladewell:add modal
- Also adds
- Button, Icon
- Used by
- Dropdown, Pagination
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guide
- A Livewire modal that stays open through re-renders
Usage
Livewire
Inside a Livewire component an open modal stays open through every render, so a form in it shows its validation errors where they belong. Open and close it from the component with $this->dispatch('modal-open', id: 'edit-profile') and 'modal-close' (which closes a disable-close modal too: the app asked). With reset-on-close, closing it also empties the bound properties.
<x-widget.button data-modal-open="edit-profile">Edit profile</x-widget.button>
<x-widget.modal id="edit-profile" title="Edit profile">
<form id="profile-form" wire:submit="save" class="space-y-4">
<x-widget.text-input label="Name" wire:model="name" />
<x-widget.text-input label="Email" type="email" wire:model="email" />
</form>
<x-slot:footer>
<x-widget.button variant="neutral" data-modal-close>Cancel</x-widget.button>
<x-widget.button type="submit" form="profile-form">Save</x-widget.button>
</x-slot:footer>
</x-widget.modal>
{{-- In the component, after saving: $this->dispatch('modal-close', id: 'edit-profile'); --}}
Examples
Basic
Any element with data-modal-open="{id}" opens it; data-modal-close closes it. From JS: modal.open(id), modal.close(id). mobile="sheet" turns it into a bottom sheet on phones, which close-on-backdrop also lets a finger swipe down.
Show code Hide code
<x-widget.button data-modal-open="delete-transaction">Delete transaction</x-widget.button>
<x-widget.modal id="delete-transaction" title="Delete transaction?" close-on-backdrop size="sm" mobile="sheet">
<p class="text-foreground/75 text-sm">This can't be undone. Click outside, press Esc or use a button to close.</p>
<x-slot:footer>
<x-widget.button variant="neutral" data-modal-close>Cancel</x-widget.button>
<x-widget.button variant="danger" data-modal-close>Delete</x-widget.button>
</x-slot:footer>
</x-widget.modal>
Drawer
variant="drawer" slides a panel in from the end edge (side="end", the right in left-to-right pages), the start edge, or the bottom. Same focus, Esc and backdrop behaviour as a dialog, and with close-on-backdrop a bottom drawer can be swiped down too; size sets its width.
Show code Hide code
<div class="flex flex-wrap gap-3">
<x-widget.button variant="neutral" data-modal-open="filters-drawer">Filters</x-widget.button>
<x-widget.button variant="neutral" data-modal-open="share-sheet">Share</x-widget.button>
</div>
<x-widget.modal id="filters-drawer" title="Filters" variant="drawer" size="sm" close-on-backdrop>
<div class="flex flex-col gap-3 text-sm">
@foreach (['Deposits', 'Withdrawals', 'Transfers', 'Fees'] as $type)
<label class="flex items-center gap-2"><input type="checkbox" checked class="accent-primary size-4"> {{ $type }}</label>
@endforeach
</div>
<x-slot:footer>
<x-widget.button variant="neutral" data-modal-close>Reset</x-widget.button>
<x-widget.button data-modal-close>Show results</x-widget.button>
</x-slot:footer>
</x-widget.modal>
<x-widget.modal id="share-sheet" label="Share" variant="drawer" side="bottom" close-on-backdrop>
<p class="text-foreground/75 text-sm">A bottom sheet: the usual shape for quick actions on phones.</p>
</x-widget.modal>
Scrollable
scrollable keeps the title and the footer's buttons in view while only the body scrolls, so a long form never hides its Save button.
Show code Hide code
<x-widget.button data-modal-open="edit-profile">Edit profile</x-widget.button>
<x-widget.modal id="edit-profile" title="Edit profile" scrollable>
<div class="flex flex-col gap-4">
@foreach (['Full name', 'Display name', 'Email', 'Phone', 'Company', 'Job title', 'Website', 'Address line 1', 'Address line 2', 'City', 'State or region', 'Postal code', 'Country'] as $field)
<label class="flex flex-col gap-1 text-sm">{{ $field }}<input type="text" class="border-line rounded-xl border px-3 py-2"></label>
@endforeach
<label class="flex flex-col gap-1 text-sm">Bio<textarea rows="4" class="border-line rounded-xl border px-3 py-2"></textarea></label>
</div>
<x-slot:footer>
<x-widget.button variant="neutral" data-modal-close>Cancel</x-widget.button>
<x-widget.button data-modal-close>Save</x-widget.button>
</x-slot:footer>
</x-widget.modal>
Confirm
modal.confirm() asks a yes/no question with no markup and resolves true or false; the script beside this calls it. It starts on Cancel, so Enter can't confirm by accident; danger styles the confirm button for destructive actions. For a button that only needs to ask before it acts, confirm="…" on the button asks the same way with no script.
Show code Hide code
<div class="flex flex-wrap items-center gap-3">
<x-widget.button variant="danger" data-delete-wallet>Delete wallet</x-widget.button>
<span id="confirm-result" class="text-foreground/75 text-sm" aria-live="polite"></span>
</div>
document.addEventListener('click', async (event) => {
if (!event.target.closest('[data-delete-wallet]')) {
return;
}
const confirmed = await modal.confirm({
title: 'Delete this wallet?',
message: 'Its history will be removed for good.',
confirm: 'Delete',
danger: true,
});
document.getElementById('confirm-result').textContent = confirmed ? 'Deleted.' : '';
});
Full screen
size="full" fills the screen, for editors and step-by-step flows. Its title and footer stay pinned.
Show code Hide code
<x-widget.button variant="neutral" data-modal-open="compose">Compose</x-widget.button>
<x-widget.modal id="compose" title="New message" size="full">
<textarea rows="12" placeholder="Write your message..." class="border-line h-full min-h-60 w-full rounded-xl border p-3 text-sm"></textarea>
<x-slot:footer>
<x-widget.button variant="neutral" data-modal-close>Discard</x-widget.button>
<x-widget.button data-modal-close>Send</x-widget.button>
</x-slot:footer>
</x-widget.modal>
Locked
disable-close turns off Esc, the backdrop and the close button; only modal.close(id, { force: true }) closes it, from your own script.
Show code Hide code
<x-widget.button data-modal-open="accept-terms">Review terms</x-widget.button>
<x-widget.modal id="accept-terms" title="Accept the terms" disable-close>
<p class="text-foreground/75 text-sm">Esc, the backdrop and the close button are disabled. Only the button below closes this.</p>
<x-slot:footer>
<x-widget.button data-accept-terms>I accept</x-widget.button>
</x-slot:footer>
</x-widget.modal>
// A locked modal ignores Esc, the backdrop and data-modal-close; your code decides when it's done.
document.addEventListener('click', (event) => {
if (event.target.closest('[data-accept-terms]')) {
modal.close('accept-terms', { force: true });
}
});
Long content
The dialog scrolls as a whole while the page behind it stays locked.
Show code Hide code
<x-widget.button variant="neutral" data-modal-open="terms-of-service">Read the terms</x-widget.button>
<x-widget.modal id="terms-of-service" title="Terms of service" size="lg">
<div class="text-foreground/75 flex flex-col gap-6 text-sm leading-relaxed">
@foreach ([
'Who these terms cover' => [
'These terms are an agreement between you and us. They apply whenever you open an account, add money, send a transfer or receive one, whether you use the website, the mobile app or the API.',
'By creating an account you confirm that you are at least 18 years old and that the details you give us are true and complete. If you use the service for a business, you confirm you are allowed to accept these terms on its behalf.',
],
'Opening your account' => [
'We are required by law to check who you are before you can send money. We may ask for a photo ID, proof of address and, for larger amounts, where the money came from. Until these checks are complete, some features stay limited.',
'You may hold one personal account. Accounts opened with someone else\'s details, or to get around a limit or a closure, will be closed without notice.',
],
'Keeping your account safe' => [
'Keep your password and verification codes to yourself. We will never ask for them by email, text or phone. Turn on two-step verification and keep your email address and phone number up to date.',
'Tell us straight away if you think someone else has accessed your account or if your device is lost or stolen. You will not be responsible for transfers made after you tell us, unless you acted fraudulently.',
],
'Sending money' => [
'Before you confirm a transfer we show you the amount, the fee, the exchange rate and when the money should arrive. Check the recipient\'s details carefully: once a transfer has been paid out, we may not be able to get it back.',
'Most transfers arrive within one working day. Some take longer because of the recipient\'s bank, public holidays or extra checks we must carry out. We will keep you updated in the app while a transfer is in progress.',
'You can cancel a transfer free of charge until the money has been sent to the recipient. After that, cancelling is only possible if the recipient\'s bank agrees to return the funds.',
],
'Fees and exchange rates' => [
'Our fees are listed on the pricing page and are always shown before you confirm. We never hide a margin in the exchange rate: the rate you see is the rate you get, for as long as the quote is valid.',
'If a quote expires before your money reaches us, we will offer a new one. You can accept it or ask for a full refund.',
],
'Limits' => [
'Daily and monthly limits depend on your country, the currency and how much we have verified about you. You can see your current limits in account settings and ask us to raise them.',
],
'Things you must not do' => [
'You must not use the service for anything illegal, to receive money from fraud, or to pay for goods and services that are prohibited in your country or ours. You must not try to interfere with the service or access other people\'s accounts.',
'If we suspect any of this, we may delay or block a transfer, freeze your balance while we investigate and report it to the authorities where the law requires us to.',
],
'Closing your account' => [
'You can close your account at any time from account settings once any transfers in progress have finished. We will send the remaining balance to a bank account in your name.',
'We may close your account with two months\' notice, or immediately if you break these terms or the law requires it. We keep your records for as long as the law requires after the account closes.',
],
'Complaints' => [
'If something goes wrong, contact us through the help centre and we will reply within 15 working days. If you are not happy with our answer, you may be able to take your complaint to an independent ombudsman.',
],
'Changes to these terms' => [
'We may update these terms from time to time. We will email you at least two months before a change affects you. If you do not agree, you can close your account for free before the change takes effect.',
],
] as $heading => $paragraphs)
<section class="flex flex-col gap-2">
<h3 class="text-foreground text-base font-semibold">{{ $loop->iteration }}. {{ $heading }}</h3>
@foreach ($paragraphs as $paragraph)
<p>{{ $paragraph }}</p>
@endforeach
</section>
@endforeach
</div>
</x-widget.modal>
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.modal>
| Prop | Default | Description |
|---|---|---|
| id | Required | Required, and unique on the page: buttons open it with data-modal-open="{id}", scripts with modal.open('{id}'). |
| title |
null
|
The heading at the top, and the modal's name for screen readers. |
| label |
null
|
The modal's name for screen readers when it has no title; a title wins. |
| size |
'md'
|
How wide it is: sm, md, lg or xl. full fills the whole screen (dialogs only). |
| variant |
'dialog'
|
dialog: a panel in the middle of the screen. drawer: a panel that slides in from the edge set by side. |
| side |
'end'
|
With variant="drawer", the edge it slides in from: start, end (the right in left-to-right pages) or bottom. |
| scrollable |
false
|
Keeps the title and footer in view while only the body scrolls. Drawers and size="full" always work this way. |
| mobile |
null
|
sheet: on phones, a dialog becomes a sheet that slides up from the bottom. Leave it out to keep the dialog centred. Dialogs only, and not with size="full". |
| close-button |
true
|
The X in the top corner. Never shown with disable-close. |
| close-on-backdrop |
false
|
A click on the dimmed area outside the panel closes it too. |
| disable-close |
false
|
Locks it open: no Esc, backdrop or X. Only your code closes it, with modal.close(id, { force: true }) or a modal-close event from Livewire. |
| reset-on-close |
false
|
Puts the forms inside back to their starting values each time it closes (wire:model properties too). |
| open |
false
|
Opens as the page loads, e.g. :open="$errors->any()" to reopen a form after failed validation. |
Accessibility
All 7 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.
Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.
Source
What bladewell:add modal writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from
the components it also adds , and the theme and base CSS.
resources/views/components/widget/modal/index.blade.php Show
resources/js/widget/modal/index.js Show
app/View/Widget/ElementIds.php Show