aura
Home Aura
aura

Modal

The Modal component is a flexible dialog box or popup window that overlays the current page. It’s perfect for notifications, forms, custom content, or multi-step workflows. Modals can be triggered either from the frontend (no backend request) or backend (with data fetching or logic).

Overview

Modals support various sizes, close buttons, dismissible behavior, and nesting. They can be opened directly from the frontend using show-modal or from the backend using a ModalComponent class with methods like $this->showModal() and $this->hideModal().

Attributes

  • Attribute: name

    • Type: String
    • Description: Unique identifier for opening/closing the modal
    • Default: Required

  • Attribute: size

    • Type: String
    • Description: Modal width (e.g., sm, lg, full)
    • Default: md

  • Attribute: closeable

    • Type: Boolean
    • Description: Shows a close button if true
    • Default: true

  • Attribute: dismissible

    • Type: Boolean
    • Description: Closes on outside click if true
    • Default: true

  • Attribute: title

    • Type: String
    • Description: Modal header title
    • Default: Optional

Control the modal’s width with the size attribute:

  • sm - Small
  • md - Medium (default)
  • lg - Large
  • xl - Extra Large
  • 2xl - 2x Large
  • 3xl - 3x Large
  • 4xl - 4x Large
  • 5xl - 5x Large
  • 6xl - 6x Large
  • 7xl - 7x Large
  • full - Full-screen

Frontend Triggered Modal

For simple modals without backend logic (e.g., no data fetching), use show-modal on a button:

Basic Modal

Copy to clipboard

<aura:button text="Open Modal" show-modal="modal-1" />

<aura:modal name="modal-1" title="Basic Modal" size="sm">
    <aura:fieldset>
        <aura:input label="Name" placeholder="John Doe" />
        <aura:input label="Email" placeholder="[email protected]" />
        <aura:input type="password" label="Password" placeholder="password" revealable />
    </aura:fieldset>

    <x-slot:actions>
        <aura:button outline text="Cancel" hide-modal="modal-1" />
        <aura:button solid text="Save" />
    </x-slot:actions>
</aura:modal>
  • show-modal="modal-1" opens the modal without a backend request.
  • hide-modal="modal-1" closes it from the frontend.

Backend Triggered Modal

For modals requiring backend logic (e.g., fetching data), use a ModalComponent class. The modal’s name is bound dynamically with :name="$name", and the backend triggers it using $this->showModal().

Example

Backend (PHP Component)

Copy to clipboard

class UserProfileModal extends ModalComponent
{
    public string $name = 'user-profile-modal';

    public $user;

    public function fetchUserData()
    {
        $this->user = User::find(1); // Fetch data
        $this->showModal();          // Trigger modal from backend
    }

    public function saveProfile()
    {
        // Save logic
        $this->hideModal();          // Close modal from backend
    }
}

Frontend (Template)

Edit Profile

Editing user: John Doe

Copy to clipboard

<aura:button text="Edit Profile" show-modal="profile-modal" />

<aura:modal name="profile-modal" title="Edit Profile">
    <aura:p>Editing user: John Doe</aura:p>
    <x-slot:actions>
        <aura:button solid text="Save" />
    </x-slot:actions>
</aura:modal>
  • Use :name="$name" to bind the modal’s name to the backend component’s $name property.
  • $this->showModal() opens the modal after backend processing (e.g., data fetching).
  • $this->hideModal() closes it, optionally refreshing the page.

Optional Hooks

  • Add a beforeShow() method to run code before the modal opens.
  • Add a beforeHide() method to run code before it closes.

Small Modal

Full Screen Modal

This modal takes up the entire screen

Copy to clipboard

<aura:button solid text="Small Modal" show-modal="modal-sm" />
<aura:modal name="modal-sm" size="sm" title="Small Modal">
    <x-slot:subtitle>This is a small modal</x-slot:subtitle>
</aura:modal>

<aura:button solid text="Full Screen" show-modal="modal-full" />
<aura:modal name="modal-full" size="full" title="Full Screen Modal">
    <aura:p>This modal takes up the entire screen</aura:p>
</aura:modal>

Closeable Modal

Display a close button with closeable:

Closeable Modal

This modal has no close button

Copy to clipboard

<aura:button text="Open Modal" show-modal="modal-closeable" />

<aura:modal name="modal-closeable" title="Closeable Modal" :closeable="false">
    <aura:p>This modal has no close button</aura:p>
</aura:modal>
  • Default: true (close button visible).
  • Set :closeable="false" to disable it.

Dismissible Modal

Allow closing by clicking outside with dismissible:

Non-Dismissible Modal

You must use buttons to close this modal

Copy to clipboard

<aura:button text="Open Modal" show-modal="modal-dismissible" />

<aura:modal name="modal-dismissible" title="Non-Dismissible Modal" :dismissible="false">
    <aura:p>You must use buttons to close this modal</aura:p>
</aura:modal>
  • Default: true (outside click closes it).
  • Set :dismissible="false" to disable.

Nested Modals

Create nested modals for multi-step interactions:

Parent Modal

Nested Modal

Copy to clipboard

<aura:button text="Open Parent Modal" show-modal="modal-parent" />

<aura:modal name="modal-parent" size="sm" title="Parent Modal" closeable>
    <aura:button text="Open Nested Modal" show-modal="modal-child" />
</aura:modal>

<aura:modal name="modal-child" size="sm" title="Nested Modal" closeable />

Key Usage Notes

  • Frontend (show-modal): Use for static modals with no backend interaction. No request is made.
  • Backend ($this->showModal()): Use when the modal needs data or logic from the server. Bind the modal name with :name="$name".
  • Use $this->hideModal() to close programmatically from the backend, with optional beforeHide() cleanup.

Best Practices

  • Use descriptive name values to avoid conflicts.
  • Reserve backend triggering for dynamic content or workflows.
  • Limit nested modals to maintain a clean user experience.

This version emphasizes practical usage, distinguishes between frontend and backend approaches, and keeps the focus on triggering modals effectively.