Inertia Modal

Inertia Modal is a package designed for Laravel, Inertia.js, and Tailwind CSS that allows you to open any existing route within a Modal or Slideover. A key advantage is that it requires zero backend configuration; you can use your existing routes and controllers without modification.

Key Features:

• Framework Support: Works with both React and Vue.
• UI Flexibility: Supports Modals, Slideovers, multiple sizes, and positions.
• Advanced Capabilities: Supports nested/stacked modals, headless mode, and reusable modals.
• Data Handling: Supports reloading props within modals and easy communication between nested/stacked modals.
• Routing: Supports Base Route / URL patterns.

Inertia Modal is a suite of components for Laravel, Inertia.js, and Tailwind CSS that enables modal and slideover functionality with zero backend configuration.

Key capabilities include:

• Framework Support: React and Vue.
• UI Flexibility: Supports Modals, Slideovers, multiple sizes/positions, and Headless mode.
• Advanced UX: Nested/stacked modals, prefetch support for faster loading, and native HTML dialog support for accessibility.
• Data Handling: Reload props within modals, easy communication between nested modals, and support for local modals with prop passing.
• Developer Experience: TypeScript definitions included and a simple frontend API that requires no changes to existing routes or controllers.

You can improve perceived performance by prefetching modal content using the prefetch prop.

Prefetch Triggers

• true: Shorthand for "hover".
• hover: Prefetch on hover (with a 75ms delay).
• click: Prefetch on mousedown.
• mount: Prefetch as soon as the component is mounted.
• Array: You can provide multiple triggers, e.g., ['hover', 'click'].

Cache Duration

Prefetched content is cached for 30 seconds by default. Use the cache-for prop (in milliseconds) to change this behavior.

<!-- Prefetch on hover with 60s cache -->
<ModalLink href="/users/create" prefetch="hover" :cache-for="60000">
    Create User
</ModalLink>

To improve perceived performance, you can prefetch modal content before a user clicks the link using the prefetch prop.

Supported values for prefetch:

• true: Shorthand for "hover".
• hover: Prefetch when the user hovers over the link (75ms delay).
• click: Prefetch on mousedown.
• mount: Prefetch as soon as the component is mounted.
• An array of values (e.g., ['hover', 'click']).

Cache Duration: Use the cache-for prop (in milliseconds) to control how long prefetched content is stored. The default is 30 seconds.

<!-- Prefetch on hover with 60s cache -->
<ModalLink href="/users/create" prefetch="hover" :cache-for="60000">
    Create User
</ModalLink>

You can send data from a child modal back to its parent modal using the emit method.

There are two ways to access the communication functions:

1. Via Slot Props: The Modal component provides getParentModal and getChildModal functions through its default slot.
2. Via Refs: You can use a ref on the Modal component to access its instance and call getParentModal().emit(eventName, data).

On the parent modal, listen for the custom event using standard event listeners (e.g., @message in Vue or onMessage in React).

```vue <template>
    <Modal #default="{ getParentModal }">
        <button type="button" @click="getParentModal().emit('message', 'Hello from child')">
            Push message to parent
        </button>
    </Modal>
</template>```

The Inertia Modal backend package extends the default Laravel redirector. This allows you to use the standard back() method to redirect the user back to the modal's base route instead of the previous page in history.

Disabling Extended Redirector: If you want to disable this automatic behavior, you must:

1. Publish the configuration file: php artisan vendor:publish --provider="InertiaUI\Modal\ModalServiceProvider"
2. Set the bind_extended_redirector option to false in the config.
3. Use the back_from_modal() helper method explicitly for redirects.

If you want to use the functionality of Inertia Modal without its default customizable UI, you can use Headless Mode. This allows you to implement your own UI components while still leveraging the package's state management, stacking logic, and event handling. You achieve this by using the HeadlessModal component and accessing its internal state and methods via scoped slots (Vue) or render props (React).

<!-- Vue Example -->
<HeadlessModal v-slot="modalContext">
    <!-- Your custom UI using modalContext props -->
</HeadlessModal>

The Inertia Modal skill provides AI agents with guidance for the following development tasks:

• Controller Responses: Using Inertia::modal() to return responses from existing controllers.
• Navigation: Opening routes using ModalLink and visitModal() in Vue and React.
• Routing Configuration: Configuring base routes or base URLs to ensure the background page remains correct.
• Modal Composition: Building nested and stacked modals and using the event bus for communication between them.
• Prop Management: Handling reloading, lazy, deferred, and load-when-visible props within a modal.
• Customization: Registering local modals and using headless mode for custom modal markup.

Boost is an optional development tool and is not required for your application to function at runtime.

If you want to use the functionality of Inertia Modal without its default customizable UI, you can use Headless Mode. This allows you to build your own UI from scratch while still leveraging the package's state management, stacking logic, and event handling.

To implement this, use the HeadlessModal component. Note that when using headless mode, you are responsible for the implementation of the visual elements and transitions.

Inertia Modal provides an event bus to communicate between the modal content and the parent page (or the ModalLink that opened it).

1. Emitting Events from the Modal

Inside your Modal component, use the emit function.

Vue:

<Modal #default="{ emit }">
    <button @click="emit('increaseBy', 1)">Increase</button>
</Modal>

2. Listening to Events

Via ModalLink (Vue/React):

<!-- Vue -->
<ModalLink href="/modal" @increase-by="handleIncrease">Open</ModalLink>

// React
<ModalLink href="/modal" onIncreaseBy={handleIncrease}>Open</ModalLink>

Via Programmatic Listeners (visitModal):

visitModal('/users/create', {
    listeners: {
        increaseBy(amount) { console.log(amount) }
    }
})

By default, version 2.x uses the native HTML <dialog> element for better accessibility and backdrop handling.

Important Styling Note: When useNativeDialog is true (the default), the .im-backdrop element is not rendered. Instead, the backdrop is handled via the ::backdrop pseudo-element. Because Tailwind CSS cannot target the ::backdrop pseudo-element directly, you must use plain CSS for custom backdrop styling.

To target the backdrop in CSS:

dialog.im-dialog::backdrop {
    /* your styles */
}

To opt out and return to the previous behavior (rendering .im-backdrop):

putConfig({
    useNativeDialog: false,
})

If you installed via Composer, use one of the following commands to symlink the frontend package from your vendor directory into node_modules.

For Vue users:

npm install vendor/inertiaui/modal/vue
bun add vendor/inertiaui/modal/vue
pnpm add file:vendor/inertiaui/modal/vue

For React users:

npm install vendor/inertiaui/modal/react
bun add vendor/inertiaui/modal/react
pnpm add file:vendor/inertiaui/modal/react

Note for pnpm users: You must use the file: protocol (e.g., pnpm add file:...) to ensure transitive dependencies are resolved correctly.

# Example for Vue with pnpm
pnpm add file:vendor/inertiaui/modal/vue