Inertia Modal

https://github.com/inertiaui/modal
Admin
Inertia Modal allows you to easily open any route in a Modal or Slideover without altering existing...
Tokens:44,401
Snippets:422
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via NPM

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Alternative NPM installation for Vue or React.

```bash
# Vue
npm install @inertiaui/modal-vue

# React
npm install @inertiaui/modal-react
```

--------------------------------

### Install Laravel Boost

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/ai-assisted-coding.md

Install Laravel Boost as a development dependency after installing inertiaui/modal, then run the installer to select agent integrations.

```bash
composer require laravel/boost --dev
php artisan boost:install
```

--------------------------------

### Install via Composer

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Installs the package via Composer, the recommended method.

```bash
composer require inertiaui/modal
```

--------------------------------

### React App Setup

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

React app setup integrating the modal package with Inertia.

```jsx
import { renderApp } from '@inertiaui/modal-react'

createInertiaApp({
    setup({ el, App, props }) {
        const root = createRoot(el);
        root.render(renderApp(App, props));
    }
});
```

--------------------------------

### Vue App Setup

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Vue app setup integrating the modal package with Inertia.

```js
import { renderApp } from '@inertiaui/modal-vue'

createInertiaApp({
    setup({ el, App, props, plugin }) {
        createApp({ render: renderApp(App, props) })
            .use(plugin)
            .mount(el)
    }
})
```

--------------------------------

### Install Inertia Modal via Composer

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

Run this command to install the Inertia Modal package with Composer. This installs both the Laravel backend and the frontend packages, keeping them in sync.

```bash
composer require inertiaui/modal:^3.0.0
```

--------------------------------

### Install React frontend package via npm

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

Install the React frontend package separately using npm. You must manage the version yourself to keep it in sync with the backend.

```bash
npm install @inertiaui/modal-react@^3.0.0
```

--------------------------------

### Link React frontend package after Composer install

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

After Composer installation, link the React package into your project. Use the appropriate command for your package manager: npm, bun, or pnpm (with file: protocol).

```bash
# npm
npm install vendor/inertiaui/modal/react

# bun
bun add vendor/inertiaui/modal/react

# pnpm
pnpm add file:vendor/inertiaui/modal/react
```

--------------------------------

### Install Vue frontend package via npm

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

Install the Vue frontend package separately using npm. You must manage the version yourself to keep it in sync with the backend.

```bash
npm install @inertiaui/modal-vue@^3.0.0
```

--------------------------------

### Link Frontend Package

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Links the frontend package for Vue or React after Composer installation.

```bash
# Vue
npm install vendor/inertiaui/modal/vue

# React
npm install vendor/inertiaui/modal/react
```

--------------------------------

### Frontend: App setup with renderApp (Vue and React)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/SKILL.md

Set up the modal package in your app entry point using renderApp. For Vue, wrap the app with createApp and use the plugin. For React, render with createRoot. This is required for modals to work.

```javascript
// Vue
import { renderApp } from '@inertiaui/modal-vue'
createInertiaApp({
    setup({ el, App, props, plugin }) {
        createApp({ render: renderApp(App, props) })
            .use(plugin)
            .mount(el)
    }
})
```

```javascript
// React
import { renderApp } from '@inertiaui/modal-react'
createInertiaApp({
    setup({ el, App, props }) {
        const root = createRoot(el);
        root.render(renderApp(App, props));
    }
});
```

--------------------------------

### Link Vue frontend package after Composer install

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

After Composer installation, link the Vue package into your project. Use the appropriate command for your package manager: npm, bun, or pnpm (with file: protocol).

```bash
# npm
npm install vendor/inertiaui/modal/vue

# bun
bun add vendor/inertiaui/modal/vue

# pnpm
pnpm add file:vendor/inertiaui/modal/vue
```

--------------------------------

### Vue: Listen to @start and @success events on ModalLink

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Use the @start and @success events to toggle a loading state. The @start event fires when the Inertia request begins, and @success fires when it completes successfully.

```vue
<script setup>
import { ref } from 'vue'

const loading = ref(false)
</script>

<template>
    <ModalLink @start="loading = true" @success="loading = false">
        <!-- ... -->
    </ModalLink>
</template>
```

--------------------------------

### Vue: visitModal usage

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Import visitModal from '@inertiaui/modal-vue' and call it with a URL to open a modal. The example shows a button that triggers the modal.

```vue
<script setup>
import { visitModal } from '@inertiaui/modal-vue'

function createUserModal() {
    visitModal('/users/create')
}
</script>

<template>
    <button @click="createUserModal">Create User</button>
</template>
```

--------------------------------

### Read configuration with getConfig

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/configuration.md

Reads the current configuration using getConfig. Pass a dot-notation key to get a specific value, or call with no arguments to get the entire config object.

```js
import { getConfig } from '@inertiaui/modal-vue'

const navigate = getConfig('navigate')
const maxWidth = getConfig('modal.maxWidth')
const allConfig = getConfig() // returns entire config object
```

```js
import { getConfig } from '@inertiaui/modal-react'

const navigate = getConfig('navigate')
const maxWidth = getConfig('modal.maxWidth')
const allConfig = getConfig() // returns entire config object
```

--------------------------------

### Update Boost and Discover Packages

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/ai-assisted-coding.md

Refresh generated resources and rescan installed packages for applications that already used Boost before adding Inertia Modal.

```bash
php artisan boost:update --discover
```

--------------------------------

### Wrap App with ModalRoot in Vue app.js

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/custom-app-mounting.md

In Vue, wrap the App component with ModalRoot in the setup function. The original line is shown with a strikethrough and the new line with an addition marker.

```js
import { ModalRoot } from '@inertiaui/modal-vue' // [!code ++]

createInertiaApp({
    setup({ el, App, props, plugin }) {
        return
            createApp({ render: () => h(App, props) }) // [!code --]
            createApp({ render: () => h(ModalRoot, () => h(App, props)) }) // [!code ++]
            .use(plugin)
            .mount(el)
    }
})
```

--------------------------------

### Set default configuration with putConfig

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/configuration.md

Sets the default configuration for modals and slideovers. Separate keys exist for modals and slideovers; this example shows the full default configuration.

```js
putConfig({
    type: 'modal',
    navigate: false,
    useNativeDialog: true,
    appElement: '#app',
    modal: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: '2xl',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white rounded',
        position: 'center',
    },
    slideover: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: 'md',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white min-h-screen',
        position: 'right',
    },
})
```

--------------------------------

### Open Modal from within Modal (React)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/nested-stacked-modals.md

Place a ModalLink inside a Modal to open a new modal on top. No special setup is required.

```React
export default function EditUser() {
    return (
        <Modal>
            <ModalLink href="/modal-2">
                Open Modal 2
            </ModalLink>
        </Modal>
    );
}
```

--------------------------------

### Programmatic usage: visitModal (Vue and React)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/SKILL.md

Open a modal programmatically using visitModal. In Vue, import it directly. In React, get it from useModalStack().

```javascript
// Vue
import { visitModal } from '@inertiaui/modal-vue'
visitModal('/users/create')
```

```javascript
// React
const { visitModal } = useModalStack()
visitModal('/users/create')
```

--------------------------------

### Wrap App with ModalStackProvider in React

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/custom-app-mounting.md

Wrap the App component with ModalStackProvider in the setup function to enable modal functionality.

```jsx
import { ModalStackProvider } from '@inertiaui/modal-react' // [!code ++]

createInertiaApp({
    setup({ el, App, props }) {
        const root = createRoot(el);

        root.render(
            <ModalStackProvider> // [!code ++]
                <App {...props} />
            </ModalStackProvider> // [!code ++]
        );
    }
});
```

--------------------------------

### React: Use WhenVisible component in a modal

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/load-when-visible.md

React example showing how to use the WhenVisible component from the Modal package to load the 'customer' prop only when the element becomes visible. Import WhenVisible from '@inertiaui/modal-react' instead of '@inertiajs/react'.

```jsx
import { WhenVisible } from '@inertiajs/react' // [!code --]
import { WhenVisible, Modal } from '@inertiaui/modal-react'
import { useState } from 'react'

export default function Overview({ invoice, customer }) {
    const [activeTab, setActiveTab] = useState('invoice')

    return (
        <Modal>
            <h1>Invoice {invoice.id}</h1>

            {/* Tabs for switching between Invoice and Customer details */}

            <div className={activeTab !== 'customer' ? 'hidden' : ''}>
                <h2>Customer Details</h2>

                <WhenVisible data="customer" fallback={<p>Loading customer...</p>}>
                    <CustomerComponent customer={customer} />
                </WhenVisible>
            </div>
        </Modal>
    )
}
```

--------------------------------

### React: useModalStack visitModal usage

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Import useModalStack from '@inertiaui/modal-react' and call visitModal on the returned stack object. The example shows a button that triggers the modal.

```jsx
import { useModalStack } from '@inertiaui/modal-react'

function UserIndex() {
    const modalStack = useModalStack();

    function createUserModal() {
        modalStack.visitModal('/users/create')
    }

    return (
        <button onClick={createUserModal}>Create User</button>
    );
}
```

--------------------------------

### ModalLink with method and data props

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Specifies the HTTP method (default is 'get') and passes additional data to the backend using the 'method' and 'data' props.

```vue
<template>
    <ModalLink
        href="/users/create"
        method="post"
        :data="{ default_name: 'John Doe' }"
    >
        Create User
    </ModalLink>
</template>
```

```jsx
export default function UserIndex() {
    return (
        <ModalLink
            href="/users/create"
            method="post"
            data={{ default_name: 'John Doe' }}
        >
            Create User
        </ModalLink>
    );
}
```

--------------------------------

### HeadlessModal custom UI example (Vue and React)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/headless-mode.md

Use the HeadlessModal component to build a custom modal UI without the default styling. The component exposes props like close, isOpen, and modalContext through a render prop (React) or scoped slot (Vue). You are responsible for implementing the custom UI, as the package does not provide support for custom implementations.

```vue
<script setup>
import { HeadlessModal } from '@inertiaui/modal-vue'
import { ref } from 'vue'

const modal = ref(null)

function closeModal() {
    modal.value.close()
}
</script>

<template>
    <HeadlessModal
        ref="modal"
        v-slot="{
            afterLeave,
            close,
            config,
            emit,
            getChildModal,
            getParentModal,
            id,
            index,
            modalContext,
            onTopOfStack,
            isOpen,
            reload,
            setOpen,
        }"
    >
        <!-- Your custom modal here -->
    </HeadlessModal>
</template>
```

```jsx
import { HeadlessModal } from '@inertiaui/modal-react'
import { useRef } from 'react'

export default function UserEdit({ ...props }) {
    const modalRef = useRef(null)

    function closeModal() {
        modalRef.current.close()
    }

    return (
        <HeadlessModal ref={modalRef} {...props}>
            {({ afterLeave,
                close,
                config,
                emit,
                getChildModal,
                getParentModal,
                id,
                index,
                modalContext,
                onTopOfStack,
                isOpen,
                reload,
                setOpen
            }) => (
                {/* Your custom modal here */ }
            )}
        </HeadlessModal>
    )
}
```

--------------------------------

### Open Modal from within Modal (Vue)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/nested-stacked-modals.md

Place a ModalLink inside a Modal to open a new modal on top. No special setup is required.

```Vue
<template>
    <Modal>
        <ModalLink href="/modal-2">
            Open Modal 2
        </ModalLink>
    </Modal>
</template>
```

--------------------------------

### Vue: Use WhenVisible component in a modal

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/load-when-visible.md

Vue example showing how to use the WhenVisible component from the Modal package to load the 'customer' prop only when the element becomes visible. Import WhenVisible from '@inertiaui/modal-vue' instead of '@inertiajs/vue3'.

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3' // [!code --]
import { WhenVisible, Modal } from '@inertiaui/modal-vue'
import { ref } from 'vue'

defineProps({
    invoice: Object,
    customer: Object,
})

const activeTab = ref('invoice')
</script>

<template>
    <Modal>
        <h1>Invoice {{ invoice.id }}</h1>

        <!-- Tabs for switching between Invoice and Customer details -->

        <div v-show="activeTab === 'customer'">
            <h2>Customer Details</h2>

            <WhenVisible data="customer">
                <template #fallback> Loading customer... </template>

                <CustomerComponent :customer="customer" />
            </WhenVisible>
        </div>
    </Modal>
</template>
```

--------------------------------

### Update NPM frontend packages to 3.x

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/upgrade-guide.md

Updates the frontend package via NPM if it was originally installed that way instead of using the Composer symlink. The Vue and React packages are shown as alternatives in a code group.

```bash
npm install @inertiaui/modal-vue@^3.0.0
```

```bash
npm install @inertiaui/modal-react@^3.0.0
```

--------------------------------

### Backend Configuration

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Configures modal behavior: base route, max width, position, and slideover style.

```php
return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index')
    ->maxWidth('2xl')
    ->position('center')
    ->slideover();
```

--------------------------------

### React: Listen to onStart and onSuccess events on ModalLink

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Use the onStart and onSuccess props to toggle a loading state. The onStart event fires when the Inertia request begins, and onSuccess fires when it completes successfully.

```jsx
export default function UserIndex() {
    const [loading, setLoading] = useState(false)

    return (
        <ModalLink
            onStart={() => setLoading(true)}
            onSuccess={() => setLoading(false)}
        >
            {/* ... */}
        </ModalLink>
    );
}
```

--------------------------------

### Custom App Mounting with ModalStackProvider (React)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Custom app mounting for React using ModalRoot, ModalStackProvider, and initFromPageProps directly. Wrap the app with ModalStackProvider and render ModalRoot in the layout.

```jsx
import { ModalStackProvider, initFromPageProps, setPageLayout } from '@inertiaui/modal-react'

// Layout component
function ModalLayout({ children }) {
    return <>{children}<ModalRoot /></>
}

createInertiaApp({
    resolve: (name) => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx'))
        .then(setPageLayout(ModalLayout)),
    setup({ el, App, props }) {
        const root = createRoot(el);
        initFromPageProps(props)
        root.render(
            <ModalStackProvider>
                <App {...props} />
            </ModalStackProvider>
        );
    }
});
```

--------------------------------

### Listen for ModalLink close event (Vue/React)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/nested-stacked-modals.md

Listen for the built-in 'close' event on the ModalLink component to react when a child modal is closed. The Vue example uses @close, while the React example uses onClose. This is useful for updating the parent modal when the child modal closes.

```vue
<script setup>
function handleClosedChildModal() {
    console.log('Child modal closed');
}
</script>

<template>
    <!-- Parent Modal... -->
    <Modal>
        <ModalLink href="/modal-2" @close="handleClosedChildModal">
            Open Modal 2
        </ModalLink>
    </Modal>
</template>
```

```jsx
export default function EditUser() {
    function handleClosedChildModal() {
        console.log('Child modal closed');
    }

    return (
        <Modal>
            <ModalLink href="/modal-2" onClose={handleClosedChildModal}>
                Open Modal 2
            </ModalLink>
        </Modal>
    );
}
```

--------------------------------

### Open local modal with '#' prefix

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

To open a local modal, prepend the URL with a '#' as shown.

```javascript
visitModal('#confirm-action')
```

--------------------------------

### Publish Configuration File

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/base-route-url.md

Run this artisan command to publish the configuration file. This allows you to set bind_extended_redirector to false and disable the extended redirector behavior.

```bash
php artisan vendor:publish --provider="InertiaUI\Modal\ModalServiceProvider"
```

--------------------------------

### Custom App Mounting with ModalRoot (Vue)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Custom app mounting for Vue using ModalRoot and initFromPageProps directly. Render ModalRoot wrapping the App component.

```js
import { ModalRoot, initFromPageProps } from '@inertiaui/modal-vue'

createInertiaApp({
    setup({ el, App, props, plugin }) {
        initFromPageProps(props)
        createApp({ render: () => h(ModalRoot, () => h(App, props)) })
            .use(plugin)
            .mount(el)
    }
})
```

--------------------------------

### Prefetching with ModalLink in React

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to enable prefetching on hover, click, mount, or multiple triggers using the prefetch prop. The prefetch prop accepts 'hover', 'click', 'mount', or an array of these values.

```React
export default function UserIndex() {
    return (
        <>
            {/* Prefetch on hover */}
            <ModalLink href="/users/create" prefetch="hover">
                Create User
            </ModalLink>

            {/* Prefetch on click (mousedown) */}
            <ModalLink href="/users/create" prefetch="click">
                Create User
            </ModalLink>

            {/* Prefetch on mount */}
            <ModalLink href="/users/create" prefetch="mount">
                Create User
            </ModalLink>

            {/* Multiple triggers */}
            <ModalLink href="/users/create" prefetch={['hover', 'click']}>
                Create User
            </ModalLink>
        </>
    );
}
```

--------------------------------

### Prefetch Events with ModalLink in React

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to listen for prefetching and prefetched events using the onPrefetching and onPrefetched props.

```React
export default function UserIndex() {
    return (
        <ModalLink
            href="/users/create"
            prefetch="hover"
            onPrefetching={() => console.log('Prefetching...')}
            onPrefetched={() => console.log('Prefetched!')}
        >
            Create User
        </ModalLink>
    );
}
```

--------------------------------

### Emit event using ref attribute (React)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/event-bus.md

Use the `useRef` hook to get a reference to the modal component and call the `emit` method on it. This is an alternative to using the render prop.

```jsx
import { useRef } from 'react';

export default function MyPage() {
    const modalRef = useRef(null);

    function increaseBy(amount) {
        modalRef.current.emit('increaseBy', amount);
    }

    return (
        <Modal ref={modalRef}>
            {/* ... */}
        </Modal>
    );
}
```

--------------------------------

### Configure Inertia.js with Vue modal root

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

In your app.js file, import withInertiaModal and wrap the app with it inside the withApp callback of createInertiaApp.

```js
import { withInertiaModal } from '@inertiaui/modal-vue' // [!code ++]

createInertiaApp({
    withApp(app) { // [!code ++]
        withInertiaModal(app) // [!code ++]
    }, // [!code ++]
})
```

--------------------------------

### Emit event using ref attribute (Vue)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/event-bus.md

Use the `ref` attribute to get a reference to the modal component and call the `emit` method on it. This is an alternative to using the slot prop.

```vue
<script setup>
import { ref } from 'vue';

const modalRef = ref(null);

function increaseBy(amount) {
    modalRef.value.emit('increaseBy', amount);
}
</script>

<template>
    <Modal ref="modalRef">
        <!-- ... -->
    </Modal>
</template>
```

--------------------------------

### Prefetch Events with ModalLink in Vue

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to listen for prefetching and prefetched events using the @prefetching and @prefetched event handlers.

```Vue
<template>
    <ModalLink
        href="/users/create"
        prefetch="hover"
        @prefetching="console.log('Prefetching...')"
        @prefetched="console.log('Prefetched!')"
    >
        Create User
    </ModalLink>
</template>
```

--------------------------------

### React: Listen to onError event on ModalLink

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Use the onError prop to handle a failed Inertia request. The event is triggered when the request fails, and the example shows calling an errorToast function.

```jsx
export default function UserIndex() {
    return (
        <ModalLink onError={() => errorToast('Whoops! Something went wrong.')}>
            {/* ... */}
        </ModalLink>
    );
}
```

--------------------------------

### Prefetching with ModalLink in Vue

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to enable prefetching on hover, click, mount, or multiple triggers using the prefetch prop. The prefetch prop accepts 'hover', 'click', 'mount', or an array of these values.

```Vue
<template>
    <!-- Prefetch on hover -->
    <ModalLink href="/users/create" prefetch="hover">
        Create User
    </ModalLink>

    <!-- Prefetch on click (mousedown) -->
    <ModalLink href="/users/create" prefetch="click">
        Create User
    </ModalLink>

    <!-- Prefetch on mount -->
    <ModalLink href="/users/create" prefetch="mount">
        Create User
    </ModalLink>

    <!-- Multiple triggers -->
    <ModalLink href="/users/create" :prefetch="['hover', 'click']">
        Create User
    </ModalLink>
</template>
```

--------------------------------

### Vue: Listen to @error event on ModalLink

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Use the @error event to handle a failed Inertia request. The event is triggered when the request fails, and the example shows calling an errorToast function.

```vue
<template>
    <ModalLink @error="errorToast('Whoops! Something went wrong.')">
        <!-- ... -->
    </ModalLink>
</template>
```

--------------------------------

### Configure Inertia.js with React modal root

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/installation.md

In your app.js file, import ModalStackProvider and ModalRoot, define a ModalLayout component, and wrap the app with ModalStackProvider inside withApp. Set the layout to ModalLayout.

```jsx
import { ModalStackProvider, ModalRoot } from '@inertiaui/modal-react' // [!code ++]

function ModalLayout({ children }) { // [!code ++]
    return <>{children}<ModalRoot /></> // [!code ++]
} // [!code ++]

createInertiaApp({
    withApp(app) { // [!code ++]
        return <ModalStackProvider>{app}</ModalStackProvider> // [!code ++]
    }, // [!code ++]
    layout: () => ModalLayout, // [!code ++]
})
```

--------------------------------

### Configuration: putConfig for modal and slideover

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/SKILL.md

Configure global modal and slideover behavior using putConfig. Options include type, navigation, native dialog, and styling classes. The modal and slideover sections have separate settings.

```javascript
import { putConfig } from '@inertiaui/modal-vue' // or modal-react

putConfig({
    type: 'modal',
    navigate: false,
    useNativeDialog: true,
    appElement: '#app',
    modal: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: '2xl',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white rounded',
        position: 'center',
    },
    slideover: {
        closeButton: true,
        closeExplicitly: false,
        closeOnClickOutside: true,
        maxWidth: 'md',
        paddingClasses: 'p-4 sm:p-6',
        panelClasses: 'bg-white min-h-screen',
        position: 'right',
    },
})
```

--------------------------------

### Backend: Open a modal with a base route

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/SKILL.md

Add a baseRoute to enable URL changes and browser history when opening a modal. The baseRoute method takes a route name.

```php
return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index');
```

--------------------------------

### Use setPageLayout helper in app.jsx

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/custom-app-mounting.md

Alternative to manually setting the layout: use the setPageLayout helper to apply ModalLayout to all pages.

```jsx
import { setPageLayout } from '@inertiaui/modal-react' // [!code ++]

createInertiaApp({
    resolve: (name) => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx'))
        .then(setPageLayout(ModalLayout)), // [!code ++]
});
```

--------------------------------

### Reload modal props using a ref (Vue and React)

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/reload-props.md

Shows how to use the `ref` attribute to get a reference to the modal component and call the `reload` method directly on it. The Vue version uses `ref` and `modalRef.value.reload`, while the React version uses `useRef` and `modalRef.current.reload`.

```vue
<script setup>
import { ref } from 'vue';

const modalRef = ref(null);

function reloadPermissions() {
    modalRef.value.reload({ only: ['permissions'] });
}
</script>

<template>
    <Modal ref="modalRef">
        <!-- ... -->
    </Modal>
</template>
```

```jsx
import { useRef } from 'react';

export default function MyPage({ permissions, roles }) {
    const modalRef = useRef(null);

    function reloadPermissions() {
        modalRef.current.reload({ only: ['permissions'] });
    }

    return (
        <Modal ref={modalRef}>
            {/* ... */}
        </Modal>
    );
}
```

--------------------------------

### visitModal options object

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Shows the full options object for visitModal, including method, navigate, data, headers, config (slideover), listeners, lifecycle callbacks, and queryStringArrayFormat.

```js
visitModal('/users/create', {
    method: 'post',
    navigate: true,
    data: { default_name: 'John Doe' },
    headers: { 'X-Header': 'Value' },
    config: {
        slideover: true,
    },
    listeners: {
        userCreated(user) { console.log(user) }
    },
    onStart: () => {},
    onSuccess: () => {},
    onError: () => {},
    onClose: () => {},
    onAfterLeave: () => {},
    queryStringArrayFormat: 'brackets', // or 'indices'
})
```

--------------------------------

### Create a local modal with ModalLink

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/local-modals.md

Add a Modal component with a unique name and use ModalLink with href set to the modal name prefixed with '#'. This snippet shows the Vue and React equivalents for opening a local modal.

```Vue
<template>
    <!-- ... -->

    <ModalLink href="#confirm-action">
        Perform Action
    </ModalLink>

    <Modal name="confirm-action">
        <!-- ... -->
    </Modal>
</template>
```

```React
export default function Page() {
    return (
        <div>
            {/* ... */}

            <ModalLink href="#confirm-action">
                Perform Action
            </ModalLink>

            <Modal name="confirm-action">
                {/* ... */}
            </Modal>
        </div>
    );
}
```

--------------------------------

### visitModal

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Opens a modal programmatically. Accepts a URL and an optional options object to customize the request and modal behavior.

```APIDOC
## [POST] visitModal

### Description
Opens a modal programmatically by visiting the given URL. Accepts an optional options object to customize the request and modal behavior.

### Method
POST

### Endpoint
visitModal

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to visit. For local modals, prepend with '#'.

#### Request Body
- **method** (string) - Optional - HTTP method to use (e.g., 'post', 'get'). Defaults to 'get'.
- **navigate** (boolean) - Optional - Whether to navigate the browser history.
- **data** (object) - Optional - Data to send with the request.
- **headers** (object) - Optional - Custom headers for the request.
- **config** (object) - Optional - Configuration options for the modal (e.g., slideover).
- **listeners** (object) - Optional - Event listeners for the modal.
- **onStart** (function) - Optional - Callback when the visit starts.
- **onSuccess** (function) - Optional - Callback when the visit succeeds.
- **onError** (function) - Optional - Callback when the visit fails.
- **onClose** (function) - Optional - Callback when the modal closes.
- **onAfterLeave** (function) - Optional - Callback when the modal is removed from the DOM.
- **queryStringArrayFormat** (string) - Optional - Format for query string arrays: 'brackets' or 'indices'.

### Request Example
```js
visitModal('/users/create', {
    method: 'post',
    navigate: true,
    data: { default_name: 'John Doe' },
    headers: { 'X-Header': 'Value' },
    config: {
        slideover: true,
    },
    listeners: {},
    onStart: () => console.log('Start visiting modal'),
    onSuccess: () => console.log('Modal visit successful'),
    onError: () => console.log('Modal visit failed'),
    onClose: () => console.log('Modal closed'),
    onAfterLeave: () => console.log('Modal removed from DOM'),
    queryStringArrayFormat: 'brackets',
})
```

### Response
#### Success Response (200)
No explicit response body documented.

#### Response Example
No response example provided.
```

--------------------------------

### Reset configuration with resetConfig

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/configuration.md

Resets all configuration to the defaults using resetConfig.

```js
import { resetConfig } from '@inertiaui/modal-vue'

resetConfig()
```

```js
import { resetConfig } from '@inertiaui/modal-react'

resetConfig()
```

--------------------------------

### Loading State with ModalLink in Vue

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to use the loading slot prop to display a loading state while the modal is being fetched.

```Vue
<template>
    <ModalLink #default="{ loading }">
        {{ loading ? 'Loading...' : 'Open Modal' }}
    </ModalLink>
</template>
```

--------------------------------

### getConfig(path?)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Retrieves global modal configuration values using `getConfig`.

```APIDOC
## [JS] getConfig(path?)

### Description
Retrieves the current global configuration. Optionally accepts a dot-notation path to get a specific value.

### Usage
```js
import { getConfig } from '@inertiaui/modal-vue'

const value = getConfig('modal.maxWidth')
const all = getConfig() // entire config
```

### Parameters
- **path** (string) - Optional - Dot-notation path to a specific config value.

### Returns
- The requested config value or the entire config object if no path is provided.
```

--------------------------------

### Enable Navigation for Modal Links

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Enables navigation for modal links on the frontend. Use the 'navigate' prop on a ModalLink or set 'navigate' globally via putConfig.

```html
<!-- Per-link -->
<ModalLink navigate href="/users/create">Create User</ModalLink>

<!-- Global -->
putConfig('navigate', true)
```

--------------------------------

### visitModal listeners option

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Shows how to attach event listeners programmatically when opening a modal with `visitModal`.

```APIDOC
## [JS] visitModal listeners option

### Description
Registers programmatic event listeners when visiting a modal via the `visitModal` function.

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

### Parameters
- **url** (string) - Required - The URL of the modal to visit.
- **options.listeners** (object) - Optional - An object mapping event names to callback functions.
```

--------------------------------

### putConfig(config)

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Configures global modal settings using `putConfig`.

```APIDOC
## [JS] putConfig(config)

### Description
Sets global configuration options for the modal library. Accepts either a full config object or a dot-notation path.

### Usage
```js
import { putConfig } from '@inertiaui/modal-vue'

putConfig({ modal: { closeButton: false } })
putConfig('modal.closeButton', false) // dot notation
```

### Parameters
- **config** (object | string) - Required - Either a configuration object or a dot-notation path.
- **value** (any) - Optional - The value to set when using dot notation.

### Returns
- None.
```

--------------------------------

### visitModal options object

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

The visitModal method accepts a second argument with options such as method, navigate, data, headers, config, listeners, and callbacks. The config option customizes modal behavior and style; queryStringArrayFormat can be 'brackets' or 'indices'.

```javascript
visitModal('/users/create', {
    method: 'post',
    navigate: true,
    data: { default_name: 'John Doe' },
    headers: { 'X-Header': 'Value' },
    config: {
        slideover: true,
    },
    listeners: {},
    onStart: () => console.log('Start visiting modal'),
    onSuccess: () => console.log('Modal visit successful'),
    onError: () => console.log('Modal visit failed'),
    onClose: () => console.log('Modal closed'),
    onAfterLeave: () => console.log('Modal removed from DOM'),
    queryStringArrayFormat: 'brackets',
})
```

--------------------------------

### Open Route as Modal

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Opens a route as a modal with optional base route or base URL for URL changes and browser history.

```php
// Simple modal (no URL change)
return Inertia::modal('EditUser', [
    'user' => $user,
    'roles' => Role::pluck('name', 'id'),
]);

// With base route (enables URL change and browser history)
return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index');

// With base URL
return Inertia::modal('EditUser', ['user' => $user])
    ->baseUrl('/users');
```

--------------------------------

### Import Modal Type Definitions

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Type definitions are included in both packages. Import types from '@inertiaui/modal-vue' or '@inertiaui/modal-react'.

```ts
import type { ModalConfig, ModalTypeConfig, VisitOptions, ReloadOptions, PrefetchOption } from '@inertiaui/modal-vue'
// or from '@inertiaui/modal-react'
```

--------------------------------

### Import Modal and ModalLink in React

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Import the Modal and ModalLink components from '@inertiaui/modal-react' in a React page.

```jsx
import { Modal, ModalLink } from '@inertiaui/modal-react'
```

--------------------------------

### Modal::beforeBaseRerender()

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Registers a callback to be executed before the base URL is re-rendered.

```APIDOC
## [PHP] Modal::beforeBaseRerender()

### Description
Registers a callback to be executed before the base URL is re-rendered.

### Method
PHP static method

### Endpoint
`Modal::beforeBaseRerender(callable $callback)`

### Parameters
- **callback** (callable) - Required - The callback to execute.

### Request Example
```php
Modal::beforeBaseRerender(function () {
    // ...
});
```

### Response
No return value.
```

--------------------------------

### Chain baseUrl or baseRoute Methods

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/base-route-url.md

Chain baseRoute or baseUrl to Inertia::modal() to define the base route. baseRoute() accepts an array of parameters as its second argument, similar to route().

```php
return Inertia::modal('EditUser')
    ->baseRoute('users.index')
    // or:
    ->baseUrl('/users');
```

--------------------------------

### Loading State with ModalLink in React

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Shows how to use the loading render prop to display a loading state while the modal is being fetched.

```React
export default function UserIndex() {
    return (
        <ModalLink>
            {({ loading }) => (
                <span>{loading ? 'Loading...' : 'Open Modal'}</span>
            )}
        </ModalLink>
    );
}
```

--------------------------------

### Define Base Route with Inertia::modal()

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/base-route-url.md

Use Inertia::modal() instead of Inertia::render() to define a modal. It accepts the same arguments, allowing you to pass data like roles and user.

```php
return Inertia::render('EditUser', [ // [!code --]
return Inertia::modal('EditUser', [ // [!code ++]
    'roles' => Role::pluck('name', 'id'),
    'user' => $user,
]);
```

--------------------------------

### ModalLink Prefetching and Loading State

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Documentation for the ModalLink component's prefetching and loading state features.

```APIDOC
## ModalLink Prefetching

### Description
Enables prefetching of modal content before the user clicks the link to improve perceived performance. The `prefetch` prop accepts a single value or an array of values.

### Component
`ModalLink`

### Props
- **prefetch** (string | string[]) - Optional - Accepts `true`, `"hover"`, `"click"`, `"mount"`, or an array of these values. `true` is shorthand for `"hover"`. `"hover"` prefetches on hover with a 75ms delay, `"click"` prefetches on mousedown, `"mount"` prefetches on component mount.
- **cache-for** (number) - Optional - Cache duration in milliseconds for prefetched content. Default is 30000 (30 seconds).

### Events
- **prefetching** - Emitted when prefetching starts.
- **prefetched** - Emitted when prefetching completes.

### Examples

#### Vue
```vue
<template>
    <!-- Prefetch on hover -->
    <ModalLink href="/users/create" prefetch="hover">
        Create User
    </ModalLink>

    <!-- Prefetch on click (mousedown) -->
    <ModalLink href="/users/create" prefetch="click">
        Create User
    </ModalLink>

    <!-- Prefetch on mount -->
    <ModalLink href="/users/create" prefetch="mount">
        Create User
    </ModalLink>

    <!-- Multiple triggers -->
    <ModalLink href="/users/create" :prefetch="['hover', 'click']">
        Create User
    </ModalLink>
</template>
```

#### React
```jsx
export default function UserIndex() {
    return (
        <>
            {/* Prefetch on hover */}
            <ModalLink href="/users/create" prefetch="hover">
                Create User
            </ModalLink>

            {/* Prefetch on click (mousedown) */}
            <ModalLink href="/users/create" prefetch="click">
                Create User
            </ModalLink>

            {/* Prefetch on mount */}
            <ModalLink href="/users/create" prefetch="mount">
                Create User
            </ModalLink>

            {/* Multiple triggers */}
            <ModalLink href="/users/create" prefetch={['hover', 'click']}>
                Create User
            </ModalLink>
        </>
    );
}
```

#### Cache Duration

Vue:
```vue
<template>
    <!-- Cache for 60 seconds -->
    <ModalLink href="/users/create" prefetch="hover" :cache-for="60000">
        Create User
    </ModalLink>
</template>
```

React:
```jsx
export default function UserIndex() {
    return (
        <ModalLink href="/users/create" prefetch="hover" cacheFor={60000}>
            Create User
        </ModalLink>
    );
}
```

#### Prefetch Events

Vue:
```vue
<template>
    <ModalLink
        href="/users/create"
        prefetch="hover"
        @prefetching="console.log('Prefetching...')"
        @prefetched="console.log('Prefetched!')"
    >
        Create User
    </ModalLink>
</template>
```

React:
```jsx
export default function UserIndex() {
    return (
        <ModalLink
            href="/users/create"
            prefetch="hover"
            onPrefetching={() => console.log('Prefetching...')}
            onPrefetched={() => console.log('Prefetched!')}
        >
            Create User
        </ModalLink>
    );
}
```

## ModalLink Loading State

### Description
Provides a `loading` slot prop to display a loading state while the modal is being fetched. Use it to show a spinner or text.

### Component
`ModalLink`

### Slot Props
- **loading** (boolean) - Indicates whether the modal is currently being fetched.

### Examples

#### Vue
```vue
<template>
    <ModalLink #default="{ loading }">
        {{ loading ? 'Loading...' : 'Open Modal' }}
    </ModalLink>
</template>
```

#### React
```jsx
export default function UserIndex() {
    return (
        <ModalLink>
            {({ loading }) => (
                <span>{loading ? 'Loading...' : 'Open Modal'}</span>
            )}
        </ModalLink>
    );
}
```
```

--------------------------------

### Create ModalLayout.jsx with ModalRoot

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/custom-app-mounting.md

Create a Layout component that renders the ModalRoot component after the main content. This is required for manual mounting in React.

```jsx
import { ModalRoot } from '@inertiaui/modal-react'

export default function ModalLayout({ children }) {
    return (
        <>
            {children}
            <ModalRoot />
        </>
    )
}
```

--------------------------------

### Inertia::modal()

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Opens a route as a modal with optional props.

```APIDOC
## [PHP] Inertia::modal()

### Description
Opens a route as a modal. Accepts a component name and props, and returns a modal response.

### Method
PHP function call

### Endpoint
`Inertia::modal(string $component, array $props = [])`

### Parameters
- **component** (string) - Required - The Inertia component name to render in the modal.
- **props** (array) - Optional - The props to pass to the modal component.

### Request Example
```php
return Inertia::modal('EditUser', [
    'user' => $user,
    'roles' => Role::pluck('name', 'id'),
]);
```

### Response
Returns a modal response object that can be further configured with chainable methods.
```

--------------------------------

### Backend: Open a route as a modal with Inertia::modal()

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/SKILL.md

Use Inertia::modal() instead of Inertia::render() in a controller to render a page inside a modal. The first argument is the component name, and the second is the props array.

```php
return Inertia::modal('EditUser', [
    'user' => $user,
    'roles' => Role::pluck('name', 'id'),
]);
```

--------------------------------

### useModal Hook / Composable

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Documentation for the useModal hook/composable that provides access to modal context.

```APIDOC
## useModal Hook / Composable

### Description
Access modal context from child components.

### Usage
```vue
<!-- Vue -->
<script setup>
import { useModal } from '@inertiaui/modal-vue'
const { props, close, reload, emit } = useModal()
</script>
```

```jsx
// React
import { useModal } from '@inertiaui/modal-react'
const { props, close, reload, emit } = useModal()
```

### Returns
- `props` (object) - Modal props
- `close` (function) - Function to close the modal
- `reload` (function) - Function to reload props
- `emit` (function) - Function to emit an event
```

--------------------------------

### Set Base Route or URL in Backend

Source: https://github.com/inertiaui/modal/blob/3.x/resources/boost/skills/inertia-modal-development/references/inertia-modal-guide.md

Sets the base route or URL for the modal on the backend. Use 'baseRoute' with a route name or 'baseUrl' with a URL.

```php
return Inertia::modal('EditUser', ['user' => $user])
    ->baseRoute('users.index');
    // or: ->baseUrl('/users');
```

--------------------------------

### Import Modal and ModalLink in Vue

Source: https://github.com/inertiaui/modal/blob/3.x/docs/v3/basic-usage.md

Import the Modal and ModalLink components from '@inertiaui/modal-vue' in a Vue page.

```vue
<script setup>
import { Modal, ModalLink } from '@inertiaui/modal-vue'
</script>
```
Tokens:
Raw