--- title: Modal description: Dialog overlay with backdrop visibility: guest draft: false --- # Modal The `` component creates accessible dialog overlays with focus trapping, scroll lock, and keyboard support. Modals are teleported to `` for proper stacking. ## Usage ### With Named Trigger Slot Use the `trigger` named slot to render a visible button that opens the modal. The trigger renders **outside** the teleported panel, so it is always visible on the page. :::preview{title="Modal with Trigger"} Open Modal Confirm Action Are you sure you want to proceed? Cancel Delete ::: ::: tip Prefer `` over ``. The named slot renders outside the teleported panel and is always visible, while the sub-component renders inside the hidden panel. ::: ### Programmatic (via Event) ```blade Confirm Content here ``` ### With Livewire `wire:model` ```blade Edit User Cancel Save ``` ## Width & Layout Modal width is controlled by the `size` prop — not by CSS classes: | Size | Max Width | | --- | --- | | `sm` | 24rem (384px) | | `md` | 28rem (448px) | | `lg` | 32rem (512px) | | `xl` | 36rem (576px) | | `full` | 100% viewport | ```blade … ``` Height grows with content and scrolls when exceeding the viewport. The modal is always vertically centered. ## Sizes | Size | Max Width | Use Case | | --- | --- | --- | | `sm` | 24rem (384px) | Simple confirmations | | `md` | 32rem (512px) | Standard dialogs (default) | | `lg` | 42rem (672px) | Forms with multiple fields | | `xl` | 56rem (896px) | Complex content, tables | | `full` | 100% | Full-width overlays | ```blade ... ``` ## Non-Dismissible Modals Prevent closing via ESC or backdrop click: :::preview{title="Non-Dismissible Modal"} Open Non-Dismissible Required You must complete this action. Complete ::: The user can only close by clicking the explicit action button. ## Keyboard | Key | Action | | --- | --- | | Escape | Close modal (when `dismissible`) | | Tab / Shift+Tab | Cycle focus within modal (focus trap) | ## Livewire Integration - `wire:model` syncs modal open/close state with a Livewire property - `wire:ignore.self` prevents Livewire DOM morphing from destroying modal content - `wire:navigate` (SPA mode) automatically closes open modals and cleans up focus traps ## Behavior - **[Focus trap](https://github.com/focus-trap/focus-trap)** (bundled ~3.8 KB) prevents keyboard navigation outside the modal - **Scroll lock** hides body scrollbar while modal is open - **Backdrop** click closes the modal (when `dismissible`) - **Teleport** renders modal at `` level for correct stacking - **Scale transition** for smooth open/close animation ## Modal Stacking Opening a modal on top of another is supported. A global active-overlay stack tracks the open dialogs; the topmost one owns ESC, focus, and `aria-modal="true"`. Underlying modals stay rendered, their focus trap pauses, and their `aria-modal` flips to `"false"` so screen readers announce only the active dialog. Closing the top modal resumes focus inside the previous one and restores its `aria-modal` to `"true"`. Use this for "confirm before discard" patterns where a dismissal modal must appear over an editor modal already in flight. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | **required** | Unique modal identifier | | `size` | `string` | `'md'` | Width: `sm`, `md`, `lg`, `xl`, `full` | | `dismissible` | `bool` | `true` | Whether ESC and backdrop click close the modal | | `ariaLabel` | `string\|null` | `null` | Names the dialog when it has no header. Required — as a prop or an `aria-label` attribute — if you omit `` | | `describedby` | `string\|null` | `null` | Element ID referenced by the dialog's `aria-describedby` (wire to ``) | | `scope` | `string\|null` | `null` | Scoped personalization key | ### Naming the dialog Every dialog needs an accessible name, or a screen reader announces it as just "dialog". A `` provides one automatically — its title becomes the dialog's name. If your modal has no header, name it yourself: ```blade This cannot be undone. ``` An `aria-label` attribute works the same way and takes precedence over the prop. With neither a header nor a name, the component tells you during development rather than shipping an unnamed dialog. ### Accessible Description Pair the `describedby` prop with an `id` on your body for screen-reader context: ```blade Delete account? This will permanently delete all your data. This action cannot be undone. ``` Screen readers will announce the title (via `aria-labelledby`) **and** read the body description when the dialog opens. ## Sub-Components | Component | Purpose | | --- | --- | | `` | **Recommended.** Named slot for the trigger button (renders outside teleport) | | `modal.header` | Title/heading area with bottom border + **auto close-X** (dismissible only) | | `modal.body` | Main scrollable content area | | `modal.footer` | Action buttons area with top border | | `modal.close` | Wraps any element to make it close the modal | ### Auto Close Button By default, `` renders a close-X in the top-right corner — matching the standard UX convention established by Radix, Headless UI, shadcn, Material, and Apple HIG. The button is Alpine-gated with `x-show="dismissible"`, so non-dismissible confirmation dialogs (`:dismissible="false"`) stay visually clean with no escape hatch surfaced to the user. Opt out of the auto close button when you want full control over the header layout: ```blade
Custom Header Layout
``` The auto close button uses `aria-label="Close"`, has a WCAG-compliant focus ring, and respects the same personalization system as the rest of the header — style it via `WireKit::personalize('modal.header', ['close' => 'your-classes'])`. ## Events ### Opening ```blade