Skip to content

No results for

↑ ↓ navigate ↵ open Esc close 
php artisan aura:add modal

Copies the component source into resources/views/components/aura/. Run php artisan aura:init first if you haven't already. See the CLI guide for all options.

composer require bluestarsystem/aura-ui
php artisan aura:install

Full installation instructions in the Installation guide.

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>
<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" x-on:click="$dispatch('close-modal', 'confirm-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>
<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>

    <div class="space-y-4">
        <x-aura::input label="Full Name" name="name" />
        <x-aura::input label="Email" name="email" type="email" />
    </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 variant="primary">Save User</x-aura::button>
        </div>
    </x-slot:footer>
</x-aura::modal>

<x-aura::button variant="primary" x-on:click="$dispatch('open-modal', 'create-user')">
    Create User (Glass)
</x-aura::button>
<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 Content</x-aura::button>
    </x-slot:trigger>

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

    <p>This modal was opened using the inline trigger slot. No dispatch event needed — just click the trigger button.</p>
</x-aura::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 variant="primary" x-on:click="$dispatch('close-modal', 'terms')">
            I Accept
        </x-aura::button>
    </x-slot:footer>
</x-aura::modal>

<x-aura::button variant="outline" x-on:click="$dispatch('open-modal', 'terms')">
    Show Terms (Non-Closeable)
</x-aura::button>
<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.