Inertia X adds Frames to Inertia 3

Update: You might also be interested in Inertia X UI, a UI layer built on top of Inertia X. It has...

Update: You might also be interested in Inertia X UI, a UI layer built on top of Inertia X.

It has been a long time coming, but after countless hours of refactoring, testing, and completely rethinking how we orchestrate monolithic single-page applications, I am very excited to finally type npm publish.

Inertia X.11 is a fork of Inertia 3 that adds the Frame component to the Svelte adapter.

You can check out the source code, read the documentation, and grab the package right now on GitHub: github.com/buhrmi/inertiax.

If you’ve been following the project, you know that the landscape shifted dramatically with the arrival of the Inertia 3.x branch. To ensure complete alignment with these fundamental core upgrades and Svelte’s modern architecture, I made a tough but necessary decision: Inertia X.11 is a complete rewrite from scratch. By avoiding fragile monkey-patching and building natively on top of the newest Inertia 3 foundation, Inertia X.11 is cleaner, strictly typed, and incredibly fast. Here is a deep dive into why you should use it, what has changed, and how it works.

The Core Problem: The Singleton Limitation

Standard Inertia.js is brilliant, but it introduces a major architectural constraint: the global singleton router. Standard Inertia assumes your entire app has exactly one router and one active page state.

Because of this, building complex interfaces—like slide-over panels, nested application wizards, or dynamic sidebars that pull live server data without resetting the rest of the application UI—can turn into a developer nightmare. You’re often forced to ditch the Inertia paradigm entirely and build custom JSON API endpoints or pollute your global page props.

Inertia X.11 shatters this limitation. It adds a first-class <Frame> component to the Svelte adapter, giving you the ability to spin up multiple independent Inertia page regions on the exact same document. Each frame owns its own router and page state, ensuring that forms and links executed inside a frame only update that specific frame.

What’s New and Changed in X.11?

If you used previous iterations of Inertia X, things look vastly different now that we are built on top of Inertia 3:

• Explicit, First-Class Hooks: Instead of manually digging through global store lookups, X.11 introduces clear, modern hooks like useFrameRouter() and useFrameContext().
• Smart Browser History Tracking: By default, actions taken within non-top frames update that frame's history state without replacing or mangling the browser URL. If you want a frame navigation to explicitly change the address bar, you now explicitly pass updateBrowserUrl: true.
• Automatic Link Interception: Inertia X.11 introduces a global click handler that automatically intercepts standard same-origin <a> tags clicked within a frame, turning them into frame-scoped visits without requiring any boilerplate.
• X-Inertia-Referer Header: To support clean server-side redirect_back behavior inside isolation, Inertia X now automatically sends an X-Inertia-Referer header containing the frame’s src URL.

Useful Examples

Using Inertia X.11 feels exactly like standard Inertia, but with superpowers. Here is how you can use the new syntax in your projects today:

1. Basic Frame Loading

Need to load a dynamic sub-page or sidebar? Simply place a <Frame> component. You can pass a fallback snippet inside it to handle loading states smoothly.

<script>
  import { Frame } from 'inertiax-svelte';
</script>

<div class="app-layout">
  <main>
    <h1>Dashboard Home</h1>
  </main>

  <aside>
    <Frame id="sidebar" src="/users/42/edit">
      <p>Loading user profile...</p>
    </Frame>
  </aside>
</div>

2. Accessing the Local Router

Inside a component rendered within a frame, you can seamlessly control navigation utilizing useFrameRouter(). The top-level global router remains accessible through the standard import.

<script lang="ts">
  import { useFrameRouter } from 'inertiax-svelte';

  const router = useFrameRouter();

  function nextStep() {
    // Navigates strictly inside this frame
    router.get('/wizard/step-2');
  }
</script>

<button on:click={nextStep}>Next Step</button>

3. Controlling a Frame From Somewhere Else

Sometimes a parent layout or a main data table needs to trigger an event inside a secondary panel (like a detail slider). You can target a frame using frameId in your visit options:

<script lang="ts">
  import { router } from 'inertiax-svelte';

  function openDetailsPanel(userId: number) {
    router.get(`/users/${userId}/details`, {}, { frameId: 'details' });
  }
</script>

<button on:click={() => openDetailsPanel(42)}>View Details</button>

Alternatively, if you prefer explicit control, you can instantiate a dedicated router and pass it directly to the frame:

<script lang="ts">
  import { createRouter, Frame } from 'inertiax-svelte';

  const detailsRouter = createRouter('details');

  function showUser(userId: number) {
    detailsRouter.visit(`/users/${userId}/details`);
  }
</script>

<button on:click={() => showUser(42)}>Show User</button>

<Frame id="details" router={detailsRouter} src="/users/42/details">
  <p>Loading details...</p>
</Frame>

4. Customizing Link Interception

Because standard <a> tags are intercepted automatically inside frames, building navigation is incredibly clean. If you want a specific link to bypass Inertia entirely, just use data-inertia-ignore. You can also intercept links programmatically using the onClickLink prop:

<script lang="ts">
  import { Frame } from 'inertiax-svelte';

  function onClickLink(event: MouseEvent, href: string) {
    if (href.startsWith('/admin')) {
      event.preventDefault(); // Stop frame navigation for admin routes
      // Implement custom routing or alert logic here
    }
  }
</script>

<Frame id="sidebar" src="/users/42/edit" {onClickLink} />

Installation & Migration

Because Inertia X.11 is a complete replacement ecosystem built over Inertia 3, migrating means swapping out the core packages. Your backend adapters (Laravel, Rails, Go, etc.) require zero changes!

# Using npm
npm remove @inertiajs/svelte @inertiajs/vite @inertiajs/core
npm install inertiax-svelte inertiax-vite inertiax-core

Next, update your imports across your project files:

• Change @inertiajs/svelte -> inertiax-svelte
• Change @inertiajs/core -> inertiax-core
• Change @inertiajs/vite -> inertiax-vite

Wrapping Up

Rewriting Inertia X from scratch for the 3.x branch was a massive undertaking, but the result is a bulletproof development experience. You no longer have to fight the framework to build complex, multi-region web applications.

Go check out the code on GitHub, install the package, and let me know what incredible interfaces you create with it!