Momentum Modal

Momentum Modal is a headless Vue 3 modal system for Laravel applications that use Inertia 3. This Inventas fork contains the Laravel package and its matching Vue client.

The Vue client keeps the original modal, Modal, and useModal API. It uses the native Inertia 3 request interceptor. It does not change Axios defaults and does not require Axios.

Requirements

• PHP 8.2 or later
• Laravel 12 or 13
• inertiajs/inertia-laravel 3
• Vue 3
• @inertiajs/vue3 3

Installation

Add the Inventas repository and install the Laravel package.

composer config repositories.momentum-modal vcs https://github.com/Inventas/momentum-modal
composer require inventas/momentum-modal:dev-feature/inertia-3

Use the co-located Vue package. This keeps the existing momentum-modal imports in the application.

{
  "dependencies": {
    "momentum-modal": "file:vendor/inventas/momentum-modal/vue"
  }
}

Run npm install after Composer installs the package. Do not install the old public momentum-modal package from the npm registry. That package uses the Inertia 1 and 2 Axios transport and does not support Inertia 3.

Client setup

Register the plugin with the same component resolver that Inertia uses.

import { createInertiaApp } from "@inertiajs/vue3"
import { createApp, h } from "vue"
import { resolvePageComponent } from "laravel-vite-plugin/inertia-helpers"
import { modal } from "momentum-modal"

const pages = import.meta.glob("./Pages/**/*.vue")
const resolve = (name: string) =>
  resolvePageComponent(`./Pages/${name}.vue`, pages)

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

Add the headless Modal host to a persistent layout.

<script setup lang="ts">
import { Modal } from "momentum-modal"
</script>

<template>
  <main>
    <slot />
    <Modal />
  </main>
</template>

The host owns the modal request interceptor, page watcher, and browser history listener. It removes these resources when the host unmounts. This makes the package safe for SSR and Vite hot module replacement.

TypeScript page props

The package exports its public types. Add modal to the application's existing Inertia shared page props declaration. If the application already defines sharedPageProps, add the field to that same type instead of adding a second declaration.

import type { ModalPageData } from "momentum-modal"

declare module "@inertiajs/core" {
  interface InertiaConfig {
    sharedPageProps: {
      modal?: ModalPageData | null
    }
  }
}

Do not add a local declaration for the momentum-modal module. The package includes its own declarations.

Server usage

Modal pages have normal routes. The base route supplies the background page when a modal URL is loaded directly.

use Inertia\Inertia;

Route::get('/users/{user}', ShowUser::class)
    ->name('users.show');

Route::get('/users/{user}/tweets/{tweet}', ShowTweet::class)
    ->name('users.tweets.show');

final class ShowTweet
{
    public function __invoke(User $user, Tweet $tweet)
    {
        return Inertia::modal('Tweets/Show', [
            'user' => $user,
            'tweet' => $tweet,
        ])->baseRoute(
            name: 'users.show',
            parameters: $user,
        );
    }
}

Each modal response must call baseRoute() or baseURL(). The package reports a clear exception when the base URL is missing.

The legacy Inertia::dialog() and Inertia::render(...)->stackable() aliases remain available for applications that used the original package API.

Modal component API

Use useModal() in the resolved modal page component.

<script setup lang="ts">
import { useModal } from "momentum-modal"

const { show, close, redirect } = useModal()
</script>

<template>
  <Dialog :open="show" @close="close" @after-leave="redirect">
    <!-- Modal content -->
  </Dialog>
</template>

close() removes modal request context and starts the leave transition. redirect() removes the retained modal component and visits its return URL after that transition.

Development

Run the Laravel checks from the repository root.

vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint --test

Run all Vue client checks from vue/.

npm ci
npm run check

Credits

The package is based on the original work by Boris Lepikhin and the Momentum contributors. Inventas maintains this Inertia 3 fork.

License

Momentum Modal is open-source software licensed under the MIT license.