PHPackages                             emargareten/inertia-modal - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. emargareten/inertia-modal

ActiveLibrary[Utility & Helpers](/categories/utility)

emargareten/inertia-modal
=========================

Inertia Modal is a Laravel package that lets you implement backend-driven modal dialogs for Inertia apps.

v3.3.0(5d ago)90142.9k↓25.1%12[1 PRs](https://github.com/emargareten/inertia-modal/pulls)MITPHPPHP ^8.2CI passing

Since Feb 21Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/emargareten/inertia-modal)[ Packagist](https://packagist.org/packages/emargareten/inertia-modal)[ Docs](https://github.com/emargareten/inertia-modal)[ RSS](/packages/emargareten-inertia-modal/feed)WikiDiscussions master Synced 4d ago

READMEChangelog (10)Dependencies (30)Versions (33)Used By (0)

Inertia Modal
=============

[](#inertia-modal)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b691b4387917f8daa074de91957c217b6426f9d1d1a2c2e5474dc0e70ae6778e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656d61726761726574656e2f696e65727469612d6d6f64616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/emargareten/inertia-modal)[![GitHub Tests Action Status](https://camo.githubusercontent.com/ee621e59908b570da52cdb72c3c76d2dbfcf7c2a86225bb6c23988c5730cea3b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f656d61726761726574656e2f696e65727469612d6d6f64616c2f72756e2d74657374732e796d6c3f6272616e63683d6d6173746572266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/emargareten/inertia-modal/actions?query=workflow%3Arun-tests+branch%3Amaster)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/8bc6356a4c03d354652de996563469eccd7953fe3af4d01cf38ec78e2244db21/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f656d61726761726574656e2f696e65727469612d6d6f64616c2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d6173746572266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/emargareten/inertia-modal/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amaster)[![Total Downloads](https://camo.githubusercontent.com/77319c14811592007d772836dcd343a12f9959546d07603393ff4e6f3b8d5c4c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f656d61726761726574656e2f696e65727469612d6d6f64616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/emargareten/inertia-modal)

Inertia Modal is a Laravel package that lets you implement backend-driven modal dialogs for Inertia apps. With this package, you can define modal routes on the backend and dynamically render them when you visit a dialog route.

Note

This package supports Laravel 11+, PHP 8.2+, Inertia Laravel v3, and Vue 3 only.

Note

Inertia Modal targets Inertia v3 and uses Inertia's built-in HTTP client. No separate Axios setup is required.

Installation
------------

[](#installation)

Install the Laravel package with Composer:

```
composer require emargareten/inertia-modal
```

Install the frontend peer dependencies in your application if they are not already present:

```
npm install @inertiajs/vue3 vue
```

Frontend Setup
--------------

[](#frontend-setup)

### `Modal` Component

[](#modal-component)

Modal is a **headless** component, meaning you have full control over its look, whether it's a modal dialog or a slide-over panel. You are free to use any 3rd-party solutions to power your modals, such as [Headless UI](https://github.com/tailwindlabs/headlessui).

Put the `Modal` component somewhere within the layout.

```

import { Modal } from '../../vendor/emargareten/inertia-modal'

```

Note

Ensure that the layout remains [persistent](https://inertiajs.com/pages#persistent-layouts) throughout the entire application. If you have multiple layouts, create a base layout that should invoke the modal, using nested layouts.

### Plugin

[](#plugin)

Set up the `modal` plugin with the same component resolver you use to render Inertia pages.

#### Vite / Laravel

[](#vite--laravel)

```
import { createInertiaApp } from '@inertiajs/vue3'
import { createApp, h } from 'vue'
import { modal } from '../../vendor/emargareten/inertia-modal'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

const pages = import.meta.glob('./Pages/**/*.vue')

createInertiaApp({
  resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, pages),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(modal, {
        resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, pages),
      })
      .mount(el)
  }
})
```

If you prefer an alias, point it at the Composer-installed package:

```
// vite.config.js
import { defineConfig } from 'vite'
import path from 'node:path'

export default defineConfig({
  resolve: {
    alias: {
      'inertia-modal': path.resolve('vendor/emargareten/inertia-modal'),
    },
  }
})
```

Usage
-----

[](#usage)

Modals have their own routes, letting you access them even via direct URLs. Define routes for your modal pages.

```
// background context / base page
Route::get('users', [UserController::class, 'index'])->name('users.index');

// modal route
Route::get('users/{user}', [UserController::class, 'show'])->name('users.show');
```

Render a modal from a controller. Specify the `base` route to render the background when the modal is accessed directly.

```
use Emargareten\InertiaModal\Modal;
use Inertia\Inertia;

class UserController extends Controller
{
    // ...

    public function show(User $user): Modal
    {
        return Inertia::modal('Users/Show', ['user' => $user])->baseRoute('users.index');
    }
}
```

The component argument follows Inertia's component conventions, including configured component transformers and string-backed enums.

Dot notation is supported for modal props:

```
return Inertia::modal('Users/Show', [
    'user' => $user,
    'filters.search' => request('search'),
])->baseRoute('users.index');
```

### Inertia v3 props

[](#inertia-v3-props)

Modal responses are resolved through Inertia's v3 response pipeline, so modal props can use the current Inertia prop helpers:

```
return Inertia::modal('Users/Show', [
    'user' => $user,
    'stats' => Inertia::defer(fn () => $user->stats()),
    'comments' => Inertia::merge($user->comments()->latest()->get())
        ->append()
        ->matchOn('id'),
    'actions' => Inertia::once(fn () => ActionResource::collection($actions)),
])->baseRoute('users.index');
```

This also preserves Inertia metadata such as shared props, deferred props, merge props, deep merge props, match-on strategies, once props, rescued props, and infinite scroll metadata when a modal opens over an existing page.

Partial reloads for modal props are supported using the nested `modal.props.*` path. This is also what Inertia uses when loading deferred modal props:

```
router.reload({ only: ['modal.props.stats'] })
```

Partial modal responses stay sparse so Inertia can apply `mergeProps`, `prependProps`, and `deepMergeProps` itself. For example, a deferred modal prop using `Inertia::merge(...)->append()` will be appended by Inertia's native client merge logic, not pre-merged by this package.

If you need to exclude expensive shared props from modal-only responses, publish the config file and update `exclude_shared_props`:

```
php artisan vendor:publish --provider="Emargareten\InertiaModal\InertiaModalServiceProvider"
```

### Backdrop behavior

[](#backdrop-behavior)

By default, the backdrop page is preserved with its current data while the modal is open. This keeps modal visits fast and avoids reloading the page behind the dialog. When the modal is closed through `redirect()`, Inertia visits the base URL again.

When a modal URL is opened directly, the configured base URL is dispatched through Laravel's normal router pipeline. Route middleware, model binding, route events, and response preparation run as they would for a normal request to the base page.

If your backdrop needs fresh data while the modal opens, call `refreshBackdrop()`:

```
    public function show(User $user): Modal
    {
        return Inertia::modal('Users/Show', ['user' => $user])
            ->baseRoute('users.index')
            ->refreshBackdrop();
    }
```

To ignore the current modal redirect header and force a specific base route as the backdrop, call `forceBase()`:

```
    public function show(User $user): Modal
    {
        return Inertia::modal('Users/Show', ['user' => $user])
            ->baseRoute('users.index')
            ->forceBase();
    }
```

This will force re-render of the base route (or even redirect to a different base route).

Both `refreshBackdrop()` and `forceBase()` accept a boolean.

### Frontend implementation

[](#frontend-implementation)

Use the `useModal()` composable in your modal component.

This example is a simple headlessui modal, you can add more transitions etc. see .

```

import { TransitionRoot, TransitionChild, Dialog, DialogPanel, DialogTitle } from '@headlessui/vue'
import { useModal } from '../../vendor/emargareten/inertia-modal'

const { show, close, redirect } = useModal()

```

The `redirect` method will redirect to the base route, you can pass in all inertia visit options as a parameter.

```
redirect({ preserveScroll: true })
```

The `close` method will close the modal without redirecting to the base route.

Note

If you configured the Vite alias shown above, import from `inertia-modal` instead of the vendor path:

```
import { useModal } from 'inertia-modal'
```

Testing
-------

[](#testing)

```
composer test
npm run build
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

This package was highly inspired by [momentum-modal](https://github.com/lepikhinb/momentum-modal)

- [emargareten](https://github.com/emargareten)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance96

Actively maintained with recent releases

Popularity49

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity69

Established project with proven stability

 Bus Factor1

Top contributor holds 59.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~48 days

Recently: every ~9 days

Total

26

Last Release

5d ago

Major Versions

v0.1.2 → v1.0.02024-02-01

v1.7.0 → v2.0.02026-03-26

v2.0.0 → v3.x-dev2026-05-24

PHP version history (3 changes)v0.0.1PHP ^8.0|^8.1|^8.2

v1.0.1PHP ^8.0

v2.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/d7bb3bbd6b71163ad5f4871aca931336ac3f8c045b9fef5c8b7e0618b62f6efa?d=identicon)[emargareten](/maintainers/emargareten)

---

Top Contributors

[![emargareten](https://avatars.githubusercontent.com/u/46111162?v=4)](https://github.com/emargareten "emargareten (99 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (32 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (22 commits)")[![laserhybiz](https://avatars.githubusercontent.com/u/100562257?v=4)](https://github.com/laserhybiz "laserhybiz (7 commits)")[![jaspertey](https://avatars.githubusercontent.com/u/1280844?v=4)](https://github.com/jaspertey "jaspertey (2 commits)")[![WINBIGFOX](https://avatars.githubusercontent.com/u/11940390?v=4)](https://github.com/WINBIGFOX "WINBIGFOX (2 commits)")[![Yiddishe-Kop](https://avatars.githubusercontent.com/u/36875437?v=4)](https://github.com/Yiddishe-Kop "Yiddishe-Kop (1 commits)")[![flexponsive](https://avatars.githubusercontent.com/u/7556675?v=4)](https://github.com/flexponsive "flexponsive (1 commits)")

---

Tags

inertiajslaravelmodalslaravelinertiamodal

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/emargareten-inertia-modal/health.svg)

```
[![Health](https://phpackages.com/badges/emargareten-inertia-modal/health.svg)](https://phpackages.com/packages/emargareten-inertia-modal)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[renatomarinho/laravel-page-speed

Laravel Page Speed

2.5k1.7M10](/packages/renatomarinho-laravel-page-speed)[erag/laravel-lang-sync-inertia

A powerful Laravel package for syncing and managing language translations across backend and Inertia.js (Vue/React/Svelte) frontends, offering effortless localization, auto-sync features, and smooth multi-language support for modern Laravel applications.

4925.3k](/packages/erag-laravel-lang-sync-inertia)[escalated-dev/escalated-laravel

An embeddable support ticket system for Laravel applications

263.9k3](/packages/escalated-dev-escalated-laravel)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)