Skip to content

Overview

The <x-aura::modal> component renders a dialog window that appears on top of the page content with a backdrop overlay. It supports named modals that can be opened and closed via Alpine.js $dispatch events or Livewire, configurable max width, glass morphism styling, and smooth enter/leave transitions. The modal is teleported to the document body to avoid z-index stacking issues.

Basic Usage

<x-aura::modal name="example">
    <p>This is the modal content.</p>
</x-aura::modal>

<!-- Open the modal from anywhere -->
<x-aura::button x-on:click="$dispatch('open-modal', 'example')">
    Open Modal
</x-aura::button>

Props

Prop Type Default Description
name string|null null Unique identifier for the modal. Used with dispatch events to open/close.
maxWidth string 'lg' Maximum width of the modal. Options: sm, md, lg, xl, 2xl, full.
glass bool false Enable glass morphism styling on the modal panel.
closeable bool true Whether the modal can be closed by clicking the backdrop or the close button.
slideOver bool false Reserved for slide-over panel behavior.
position string 'right' Position for slide-over mode.

Slots

Slot Description
Default ($slot) The main body content of the modal.
trigger Optional trigger element. Clicking it opens the modal without dispatch events.
title When provided, renders a header bar with the title text and an optional close button.
footer When provided, renders a footer section below the body, typically used for action buttons.

Variants / Examples

Confirmation Modal

<x-aura::modal name="confirm-delete" maxWidth="sm">
    <x-slot:title>Confirm Deletion</x-slot:title>

    <p>Are you sure you want to delete this item? This action cannot be undone.</p>

    <x-slot:footer>
        <div class="flex justify-end gap-3">
            <x-aura::button variant="ghost" x-on:click="$dispatch('close-modal', 'confirm-delete')">
                Cancel
            </x-aura::button>
            <x-aura::button variant="danger" wire:click="delete">
                Delete
            </x-aura::button>
        </div>
    </x-slot:footer>
</x-aura::modal>

<x-aura::button variant="danger" x-on:click="$dispatch('open-modal', 'confirm-delete')">
    Delete Item
</x-aura::button>

Form Modal with Glass Effect

<x-aura::modal name="create-user" maxWidth="xl" :glass="true">
    <x-slot:title>Create New User</x-slot:title>

    <form wire:submit="save">
        <div class="space-y-4">
            <x-aura::input label="Full Name" wire:model="name" />
            <x-aura::input label="Email" type="email" wire:model="email" />
            <x-aura::select label="Role" wire:model="role" placeholder="Select a role">
                <x-aura::select.option value="admin">Admin</x-aura::select.option>
                <x-aura::select.option value="editor">Editor</x-aura::select.option>
            </x-aura::select>
        </div>

        <x-slot:footer>
            <div class="flex justify-end gap-3">
                <x-aura::button variant="ghost" x-on:click="$dispatch('close-modal', 'create-user')">
                    Cancel
                </x-aura::button>
                <x-aura::button type="submit">Save User</x-aura::button>
            </div>
        </x-slot:footer>
    </form>
</x-aura::modal>

Inline Trigger Modal

<x-aura::modal name="preview" maxWidth="2xl">
    <x-slot:trigger>
        <x-aura::button variant="outline">Preview Image</x-aura::button>
    </x-slot:trigger>

    <x-slot:title>Image Preview</x-slot:title>

    <img src="/img/docs/photo-placeholder.svg" alt="Preview" class="w-full rounded-lg" />
</x-aura::modal>

Non-Closeable Modal

<x-aura::modal name="terms" :closeable="false" maxWidth="md">
    <x-slot:title>Terms of Service</x-slot:title>

    <p>Please read and accept the terms of service to continue.</p>

    <x-slot:footer>
        <x-aura::button wire:click="acceptTerms">
            I Accept
        </x-aura::button>
    </x-slot:footer>
</x-aura::modal>

Livewire Integration

{{-- In your Livewire component --}}
<x-aura::modal name="edit-record" maxWidth="lg">
    <x-slot:title>Edit Record #{{ $recordId }}</x-slot:title>

    <div class="space-y-4">
        <x-aura::input label="Title" wire:model="title" />
        <x-aura::textarea label="Description" wire:model="description" />
    </div>

    <x-slot:footer>
        <div class="flex justify-end gap-3">
            <x-aura::button variant="ghost" x-on:click="$dispatch('close-modal', 'edit-record')">
                Cancel
            </x-aura::button>
            <x-aura::button wire:click="update">Save Changes</x-aura::button>
        </div>
    </x-slot:footer>
</x-aura::modal>

{{-- Open from Livewire method: $this->dispatch('open-modal', 'edit-record') --}}

Accessibility

  • The modal overlay traps focus within the modal content by stopping click propagation (x-on:click.stop).
  • Pressing the Escape key closes the modal when closeable is true.
  • The close button includes an aria-label attribute for screen readers.
  • The modal uses smooth CSS transitions for enter and leave states, respecting reduced-motion preferences via the Aura transition system.
  • When closeable is false, neither the backdrop click nor the Escape key will dismiss the modal, ensuring the user must interact with the modal content.