---
url: /guide/asset-versioning.md
---
# Asset Versioning

One common challenge when building single-page apps is refreshing site assets when they've been changed. Thankfully, Inertia makes this easy by optionally tracking the current version of your site assets. When an asset changes, Inertia will automatically make a full page visit instead of a XHR visit on the next request.

## Configuration

To enable automatic asset refreshing, you need to tell Inertia the current version of your assets using the `InertiaRails.configure` method and setting the `config.version` property. This can be any arbitrary string (letters, numbers, or a file hash), as long as it changes when your assets have been updated.

```ruby
InertiaRails.configure do |config|
  config.version = ViteRuby.digest # or any other versioning method
end

# You can also use lazy evaluation
InertiaRails.configure do |config|
  config.version = lambda { ViteRuby.digest }
end
```

## Cache Busting

Asset refreshing in Inertia works on the assumption that a hard page visit will trigger your assets to reload. However, Inertia doesn't actually do anything to force this. Typically this is done with some form of cache busting. For example, appending a version query parameter to the end of your asset URLs.

With Vite Ruby, cache busting is done automatically: built files get a content hash in their names. The [Rails generator](/guide/server-side-setup#rails-generator) also sets `config.version = ViteRuby.digest` in `config/initializers/inertia_rails.rb`, so the Inertia version changes whenever your frontend files change.

## Background Requests

@available\_since rails=3.23.0 core=3.6.0

A version change detected on a background request, such as polling or a `router.reload()`, does not force a full page visit. Reloading a request the user never initiated could wipe out unsaved state, so the current page stays untouched and the next user-initiated visit picks up the new assets. You may hook into the [`location` event](/guide/events#location) to detect an asset version change and show a notification instead of reloading.

The client tells a version change apart from a redirect by the `X-Inertia-Version` header, which Inertia Rails sends with the version change response.

## Manual Refreshing

If you want to take asset refreshing into your own control, you can set the version to a fixed value. This disables Inertia's automatic asset versioning.

For example, if you want to notify users when a new version of your frontend is available, you can still expose the actual asset version to the frontend by including it as [shared data](/guide/shared-data).

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  # Disable automatic asset versioning
  config.version = nil
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  inertia_share version: -> { ViteRuby.digest }
end
```

On the frontend, you can watch the `version` property and show a notification when a new version is detected.

---

---
url: /guide/authentication.md
---
# Authentication

One of the benefits of using Inertia is that you don't need a special authentication system such as OAuth to connect to your data provider (API). Also, since your data is provided via your controllers, and housed on the same domain as your JavaScript components, you don't have to worry about setting up CORS.

Rather, when using Inertia, you can simply use whatever authentication system you like, such as solutions based on Rails' built-in `has_secure_password` method, or gems like [Devise](https://github.com/heartcombo/devise), [Sorcery](https://github.com/Sorcery/sorcery), [Authentication Zero](https://github.com/lazaronixon/authentication-zero), etc.

Rails 8 also ships a session-based authentication generator, which adds users, sessions, and password resets to your app:

```bash
bin/rails generate authentication
```

The generator creates ERB views for the sign-in and password reset forms. To use Inertia pages instead, render them from the generated `SessionsController` and `PasswordsController`.

> \[!TIP]
> The [Inertia Rails starter kits](/guide/starter-kits) provide out-of-the-box scaffolding for new Inertia applications, including authentication.

---

---
url: /guide/authorization.md
---
# Authorization

When using Inertia, authorization is best handled server-side in your application's authorization policies. However, you may be wondering how to perform checks against your authorization policies from within your Inertia page components since you won't have access to your framework's server-side helpers.

The simplest approach to solving this problem is to pass the results of your authorization checks as props to your page components.

Here's an example of how you might do this in a Rails controller using the [Action Policy](https://github.com/palkan/action_policy) gem:

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      can: {
        create_user: allowed_to?(:create, User)
      },
      users: User.all.map do |user|
        user.as_json(
          only: [:id, :first_name, :last_name, :email]
        ).merge(
          can: {
            edit_user: allowed_to?(:edit, user)
          }
        )
      end
    }
  end
end
```

---

---
url: /awesome.md
---
# Awesome Inertia Rails

A curated list of community resources, tools, and content for Inertia Rails.

## Starter kits (alphabetical)

* [GrowthX Starter Kit](https://github.com/growthxai/starter) - Rails 8 + React 19 + Inertia.js + Shadcn/UI Starter Kit from GrowthX.ai
* [Inertia Rails Starter Kits](https://inertia-rails.dev/guide/starter-kits) — Official starter kits for React, Vue, and Svelte (TypeScript, shadcn/ui)
* [Kaze](https://github.com/gtkvn/kaze) — Rails authentication scaffolding (Hotwire/React/Vue)
* [Kickstart](https://github.com/alec-c4/kickstart) — Rails application starter kits, Inertia-based (React, Svelte, Vue) and classic (API, esbuild and importmaps)
* [Svelte starter template](https://github.com/georgekettle/rails_svelte) — Svelte starter template (Svelte, shadcn/ui)

## Packages (alphabetical)

### Inertia-specific

* [Alba::Inertia](https://github.com/skryukov/alba-inertia) — Seamless integration between Alba serializers and Inertia Rails
* [Inertia Modal](https://github.com/inertiaui/modal) — Open any route in a Modal or Slideover without having to change anything about your existing routes or controllers (React, Vue)
* [Inertia X](https://github.com/buhrmi/inertiax) — Svelte-only fork of Inertia with additional features (Svelte)
* [InertiaBuilder](https://github.com/rodrigotavio91/inertia-builder) — JBuilder-like DSL for declaring Inertia.js props
* [InertiaCable](https://github.com/cole-robertson/inertia-cable) — Real-time prop updates for Inertia.js Rails apps using ActionCable
* [InertiaI18n](https://github.com/alec-c4/inertia_i18n) — Translation management bridging Rails YAML and frontend i18next JSON
* [useInertiaForm](https://github.com/aviemet/useInertiaForm) — Direct replacement of Inertia's useForm hook with support for nested forms (React)

### General

* [JS From Routes](https://github.com/ElMassimo/js_from_routes) — Generate path helpers and API methods from your Rails routes
* [JsRoutes](https://github.com/railsware/js-routes) — Brings Rails named routes to JavaScript
* [Typelizer](https://github.com/skryukov/typelizer) — A TypeScript type generator for Ruby serializers
* [types\_from\_serializers](https://github.com/ElMassimo/types_from_serializers) — Generate TypeScript interfaces from your JSON serializers

## Articles (newest first)

* [Optimistic UI in Rails with optimism... and Inertia](https://evilmartians.com/chronicles/optimistic-ui-in-rails-with-optimism-and-inertia) — Deep dive by Svyatoslav Kryukov (2026)
* [Redprints CFP: an open source CFP management app built with Rails + Inertia.js](https://evilmartians.com/chronicles/redprints-cfp-open-source-cfp-management-app-build-with-rails-and-inertia-js) — Deep dive by Vladimir Dementyev (2025)
* [Simplicity, vanished?! Solving the mystery with Inertia.js + Rails](https://evilmartians.com/chronicles/simplicity-vanished-solving-the-mystery-with-inertia-js-and-rails) — Deep dive by Svyatoslav Kryukov (2025)
* [Building Filters with Inertia.js and Rails: A Clean Approach](https://pedro.switchdreams.com.br/inertiajs/2025/06/03/filters-with-inertia-and-rails/) — Guide by Pedro Duarte (2025)
* [How to Build a Twitter Clone with Rails 8 Inertia and React](https://robrace.dev/blog/build-a-twitter-clone-with-rails-inertia-and-react) — Tutorial by Rob Race (2025)
* [How to Handle Bundle Size in Inertia.js](https://pedro.switchdreams.com.br/inertiajs/2025/03/21/handle-bundle-size-inertiajs) — Guide by Pedro Duarte (2025)
* [How We Fell Out of Love with Next.js and Back in Love with Ruby on Rails & Inertia.js](https://hardcover.app/blog/part-1-how-we-fell-out-of-love-with-next-js-and-back-in-love-with-ruby-on-rails-inertia-js) — Deep dive by Adam Fortuna (2025)
* [Building an InertiaJS app with Rails](https://avohq.io/blog/inertia-js-with-rails) — Tutorial by Exequiel Rozas (2025)
* [Inertial Rails project setup to use code generated from v0 (ShadcnUI, TailwindCSS4, React, TypeScript) and deploy with Kamal](https://tuyenhx.com/blog/inertia-rails-shadcn-typescript-ssr-en/) — Guide by Tom Ho (2025)
* [Keeping Rails cool: the modern frontend toolkit](https://evilmartians.com/chronicles/keeping-rails-cool-the-modern-frontend-toolkit) — Deep dive by Irina Nazarova (2024)
* [Inertia.js in Rails: a new era of effortless integration](https://evilmartians.com/chronicles/inertiajs-in-rails-a-new-era-of-effortless-integration) — Deep dive by Svyatoslav Kryukov (2024)

## Videos and talks (newest first)

* [Inertia Rails Workshop](https://www.youtube.com/watch?v=XBZcLD5xcPY) — SF Ruby Conference 2025 workshop by Brandon Shar, Svyatoslav Kryukov, and Brian Knoles ([demo app](https://github.com/inertia-rails/inertia-workshop-demo))
* [Optimistic Drawer UI with Inertia.js and Rails](https://www.youtube.com/watch?v=WOd3uNlW37I) — by Brian Knoles (2025)
* [Optimistic UI Updates with Inertia.js and Rails](https://www.youtube.com/watch?v=B8D195yQX04) — by Brian Knoles (2025)
* [The Best of Both Worlds: InertiaJS + React + Rails](https://www.youtube.com/watch?v=MHqITeJGci0) — by Colleen Schnettler (2025)
* [Tropical on Rails 2025: Defying Front-End Inertia](https://www.youtube.com/watch?v=uLFItMoF_wA) — Conference talk by Svyatoslav Kryukov (2025)
* [Ken Greeff's YouTube channel](https://www.youtube.com/@kengreeff/search?query=inertia) — Fresh Inertia Rails content (2025)
* [InertiaJS on Rails](https://www.youtube.com/watch?v=03EjkPaCHEI\&list=PLRxuhjCzzcWj4MUjDCC9TCP_ZfcRL0I1s) — YouTube course by Brandon Shar (2021)
* [RailsConf 2021: Inertia.js on Rails Lightning Talk](https://www.youtube.com/watch?v=-JT1RF-IhKs) — Conference talk by Brandon Shar (2021)

## Example applications (alphabetical)

### Open source

* [Code Basics](https://code-basics.com) — Free online programming courses. **Code available on [GitHub](https://github.com/hexlet-basics/hexlet-basics)**
* [Redprints CFP](https://github.com/evilmartians/redprints-cfp) — Open source CFP management app built with Rails and Inertia.js

### Demo

* [Ruby on Rails/Vue](https://github.com/ledermann/pingcrm) by Georg Ledermann
* [Ruby on Rails/Vue SSR/Vite](https://github.com/ElMassimo/pingcrm-vite) by Máximo Mussini

### Production

* [Calm Companies](https://calmcompanies.club) — Get weekly emails when companies with a great work culture are hiring
* [Clipflow](https://www.clipflow.co) — Project management for content creators
* [Crevio](https://crevio.co) — All-In-One creator store
* [Hardcover](https://hardcover.app) — A social network for book lovers
* [Katara](https://trykatara.com) - A reverse job board for software engineers
* [OG Pilot](https://ogpilot.com) — A dynamic Open Graph image generator tool
* [Switch Kanban](https://switchkanban.com.br) — Project management tool for software houses
* [railsfullstack.com](https://railsfullstack.com) - Ruby on Rails back-end & full-stack job board

## Other (alphabetical)

* [Inertia Rails Skills](https://github.com/cole-robertson/inertia-rails-skills) — Agent skills and best practices for AI coding assistants working with Inertia Rails
* [Inertia.js devtools](https://chromewebstore.google.com/detail/inertiajs-devtools/golilfffgehhabacoaoilfgjelagablo?hl=en) — Inertia.js page JSON in devtools panel

## Community

* [X.com](https://x.com/inertiajs) — Official X account
* [Discord](https://discord.gg/inertiajs) — Official Discord server
* [Reddit](https://www.reddit.com/r/inertiajs) — Inertia.js subreddit

*Please share your projects and resources with us!*

---

---
url: /guide/big-integers.md
---
# Big Integers

@available\_since rails=3.23.0 core=3.8.0

JavaScript can't represent integers above `2**53 - 1` exactly, so it rounds them while parsing JSON. An ID like `900719925474099988` from a `bigint` column or a generator like Twitter's Snowflake reaches your components as `900719925474100000`. With big integer support enabled, Inertia Rails sends those values in a form the client turns into native `BigInt` values, following the JSON convention [documented on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json).

## Enabling Big Integers

Big integer support is disabled by default. It's enabled entirely on the server, so there is nothing to configure on the client. Set the `preserve_big_integers` config value to `true`, or set the `INERTIA_PRESERVE_BIG_INTEGERS` environment variable.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.preserve_big_integers = true
end
```

You can also enable it for all actions in a controller:

```ruby
class OrdersController < ApplicationController
  inertia_config(preserve_big_integers: true)
end
```

Or for a single response, which is handy when only a few pages deal with large integers. Passing `false` opts a single response out once the feature is enabled in your configuration.

```ruby
render inertia: { order: order }, preserve_big_integers: true
render inertia: { report: report }, preserve_big_integers: false
```

## How Values Are Transported

Integers outside JavaScript's safe range are wrapped in a marker object, and the page is flagged with `preserveBigIntegers: true`. The client turns each marker back into a `BigInt`, so your component receives the exact value.

```ruby
render inertia: { id: 900719925474099988 }
# The response carries "id": {"$bigint": "900719925474099988"}
```

:::tabs key:frameworks

\== Vue

```vue
<script setup>
defineProps({ id: BigInt })
</script>

<template>
  <p>User {{ id }}</p>
  <!-- User 900719925474099988 -->
</template>
```

\== React

```jsx
export default function Show({ id }) {
  return <p>User {String(id)}</p>
  // User 900719925474099988
}
```

\== Svelte

```svelte
<script>
  let { id } = $props()
</script>

<p>User {id}</p>
<!-- User 900719925474099988 -->
```

:::

Integers within the safe range stay regular numbers, so the same prop may arrive as a number or a `BigInt` depending on its value. [Flash data](/guide/flash-data) gets the same treatment as props.

Inertia Rails looks for big integers in the finished page, after [`prop_transformer`](/guide/configuration#prop-transformer) runs. It finds them inside Active Record models, objects with `as_json` or `to_inertia`, [cached props](/guide/cached-props), JSON fragments, and [infinite scroll](/guide/infinite-scroll) page numbers. Partial reloads, deferred props, and the page sent to the [SSR server](/guide/server-side-rendering) are covered too. In your root template, [`inertia_page`](/guide/responses#inertia-page) holds the markers instead of the integers.

The client only revives markers on pages with the flag, so an app that already sends its own `{"$bigint": "..."}` objects keeps receiving them as plain objects everywhere else.

> \[!WARNING]
> On pages with the flag, the client turns every `{"$bigint": "..."}` object into a `BigInt`, including ones that come from user data. A marker that holds anything but digits makes the page fail to load.

## Submitting Big Integers

A `BigInt` submitted through the router, a form, or [Precognition](/guide/precognition) is sent as its digits, the same way form data and query strings send numbers. Your controller receives a numeric string, which Active Record casts as usual.

```js
router.post('/orders', { id: props.order.id })
```

```ruby
def create
  order = Order.find(params.require(:id))
  # ...
end
```

The [`useHttp`](/guide/http-requests) hook doesn't handle `BigInt` values, since it's often used to call third-party APIs. Convert them to strings before sending.

## Testing

The Inertia Rails [testing helpers](/guide/testing) turn markers back into integers, so you can assert against the values you passed to the response.

:::tabs key:tests

\== RSpec

```ruby
expect(inertia).to have_props(order: { id: 900719925474099988 })
expect(inertia.props[:order][:id]).to eq 900719925474099988
```

\== Minitest

```ruby
assert_inertia_props order: { id: 900719925474099988 }
assert_equal 900719925474099988, inertia.props[:order][:id]
```

:::

---

---
url: /guide/cached-props.md
---
# Cached Props

@available\_since rails=3.21.0

Cached props use your server-side cache store to avoid recomputing expensive data on every request. When the cache is warm, the block is never evaluated — Inertia serves the pre-serialized JSON directly.

> \[!NOTE]
> To understand when to use cached props vs once props vs HTTP caching, see the [Caching](/guide/caching) guide.

## Creating Cached Props

To create a cached prop, use the `InertiaRails.cache` method. This method requires a cache key and a block that returns the prop data.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      stats: InertiaRails.cache('dashboard_stats', expires_in: 1.hour) { Stats.compute },
    }
  end
end
```

On the first request, the block is evaluated, serialized to JSON, and written to the cache. Subsequent requests serve the cached JSON without evaluating the block.

## Cache Keys

Cache keys determine when cached data is invalidated. Inertia supports several key formats.

### String Keys

The simplest form — a static string:

```ruby
InertiaRails.cache('sidebar_nav') { NavigationItem.tree }
```

### Active Record Objects

Pass an Active Record object to derive the key from `cache_key_with_version`. The cache is automatically invalidated when the record is updated:

```ruby
InertiaRails.cache(@post) { PostSerializer.render(@post) }
# Cache key: "inertia_rails/@2/posts/1-20260410120000"
```

### Array Keys

Pass an array to build a composite key:

```ruby
InertiaRails.cache(['stats', current_user.id]) { Stats.for(current_user) }
# Cache key: "inertia_rails/@2/stats/42"
```

## Cache Options

You can pass `expires_in` and `race_condition_ttl` options to control cache behavior:

```ruby
InertiaRails.cache('stats', expires_in: 1.hour) { Stats.compute }

InertiaRails.cache('stats', expires_in: 1.hour, race_condition_ttl: 10.seconds) { Stats.compute }
```

## Combining with Other Prop Types

The `cache` option can be passed to [deferred](/guide/deferred-props) and [optional](/guide/partial-reloads#lazy-data-evaluation) props:

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      # Deferred prop with caching
      feed: InertiaRails.defer(cache: { key: 'feed', expires_in: 5.minutes }, group: 'feed') { current_user.feed },

      # Optional prop with caching
      categories: InertiaRails.optional(cache: @team) { @team.categories },
    }
  end
end
```

The `cache` option accepts the same key formats as `InertiaRails.cache`: strings, Active Record objects, arrays, and hashes with options.

```ruby
InertiaRails.defer(cache: { key: 'feed', expires_in: 5.minutes }) { current_user.feed }
```

## Cache Store

By default, Inertia uses `Rails.cache`. You can configure a different store via the [`cache_store`](/guide/configuration#cache-store) option. All cached prop keys are automatically prefixed with `inertia_rails/@2/` to avoid collisions.

For more information on configuring cache stores, cache key strategies, and expiration policies, see the [Rails low-level caching guide](https://guides.rubyonrails.org/caching_with_rails.html#low-level-caching-using-rails-cache).

---

---
url: /guide/caching.md
---
# Caching

Inertia Rails offers several complementary strategies for avoiding redundant work. Each solves a different problem, and you can combine them. If you're new to caching in Rails, start with the [Rails caching guide](https://guides.rubyonrails.org/caching_with_rails.html).

## Choosing a Strategy

| Strategy                             | What it saves               | Where it lives          | Best for                                  |
| ------------------------------------ | --------------------------- | ----------------------- | ----------------------------------------- |
| [HTTP caching](#http-caching)        | Entire response render      | Browser / CDN           | Pages tied to a single record's freshness |
| [Cached props](#prop-level-caching)  | Block evaluation            | Server-side cache store | Expensive queries or computations         |
| [Once props](#once-props)            | Bandwidth and serialization | Client memory           | Large or rarely-changing shared data      |
| [SSR caching](#ssr-response-caching) | SSR render request          | Server-side cache store | Avoiding redundant Node.js SSR calls      |

In short: **cached props skip computing**, **once props skip sending**, **HTTP caching skips rendering**, and **SSR caching skips the SSR request**.

These strategies are independent. A prop can be both cached on the server and marked as once so the client doesn't re-request it. HTTP caching can wrap an entire response that contains cached props. SSR caching can be layered on top of any combination.

### Why only `defer` and `optional` support the `cache` option

The `cache` option is available on [deferred](/guide/deferred-props) and [optional](/guide/partial-reloads#lazy-data-evaluation) props because these represent data that is loaded on demand — caching their result avoids re-evaluating expensive blocks on repeated requests.

Other prop types don't need it:

* **Once props** already skip evaluation when the client has the data. If the computation itself is expensive, use `InertiaRails.cache` directly in the block.
* **Always props** are meant for cheap, frequently-changing data (flash messages, auth state). If the data is expensive enough to cache, it probably shouldn't be `always`.
* **Merge and scroll props** describe how the client handles the data, not how the server computes it. If the underlying data is expensive, wrap it with `InertiaRails.cache` and pass the result.

## HTTP Caching

Rails provides built-in HTTP caching via `stale?` and `fresh_when`, and it works with Inertia responses out of the box.

@available\_since rails=3.22.0

The same URL answers with different bodies: an HTML document on the initial visit, an Inertia JSON page on client-side visits, and prop subsets on partial reloads. Inertia Rails folds the Inertia request headers into every ETag automatically, so each representation gets its own ETag and a conditional request never receives a `304 Not Modified` backed by a different representation's body. Plain (non-Inertia) requests are unaffected.

> \[!NOTE]
> On older adapter versions, differentiate the ETags yourself by adding `etag { request.inertia? }` to your `ApplicationController`.

### Using `stale?`

Use `stale?` as you normally would in Rails:

```ruby
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    if stale?(@post)
      render inertia: { post: @post.as_json }
    end
  end
end
```

When the post hasn't changed, Rails returns a `304 Not Modified` response and skips rendering entirely.

### Using `fresh_when`

For simpler cases where you don't need conditional logic:

```ruby
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
    fresh_when(@post)

    render inertia: { post: @post.as_json }
  end
end
```

> \[!WARNING]
> Automatic differentiation applies to ETags. A `fresh_when last_modified:` call with no `etag` produces no validator to differentiate, so a shared cache that ignores `Vary` can pair a `304` with the wrong representation. Pair `last_modified` with an `etag`.

If your conditionally cached responses still carry `Set-Cookie` headers — most shared caches refuse to store those — see [HTTP caching and XSRF cookie refresh](/cookbook/http-caching-and-xsrf-cookie-refresh).

## Prop-Level Caching

Prop-level caching stores computed values in your Rails cache store, skipping expensive block evaluation on cache hits. See the [Cached props](/guide/cached-props) guide for full details.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      stats: InertiaRails.cache('dashboard_stats', expires_in: 1.hour) { Stats.compute },
      feed: InertiaRails.defer(cache: { key: 'feed', expires_in: 5.minutes }) { current_user.feed },
    }
  end
end
```

## Once Props

Once props are remembered by the client and excluded from subsequent responses. This saves bandwidth for data that rarely changes, such as shared navigation or role lists. See the [Once props](/guide/once-props) guide for full details.

```ruby
class ApplicationController < ActionController::Base
  inertia_share countries: InertiaRails.once { Country.all }
end
```

## SSR Response Caching

When SSR is enabled, each page load sends a request to the Node.js server. SSR caching stores these responses so identical page data is only rendered once. See [SSR response caching](/guide/server-side-rendering#ssr-response-caching) for full details.

```ruby
InertiaRails.configure do |config|
  config.ssr_cache = true
end
```

---

---
url: /guide/client-side-setup.md
---
# Client-Side Setup

Once you have your [server-side framework configured](/guide/server-side-setup), you then need to setup your client-side framework. Inertia currently provides support for React, Vue, and Svelte.

## Prerequisites

> \[!NOTE]
> You can skip this step if you have already executed the [Rails generator](/guide/server-side-setup#rails-generator).

Inertia requires your client-side framework and its corresponding Vite plugin to be installed and configured. You may skip this section if your application already has these set up.

:::tabs key:frameworks

\== Vue

```bash
npm install vue @vitejs/plugin-vue
```

\== React

```bash
npm install react react-dom @vitejs/plugin-react
```

\== Svelte

```bash
npm install svelte @sveltejs/vite-plugin-svelte
```

:::

Then, add the framework plugin to your `vite.config.js` file.

:::tabs key:frameworks

\== Vue

```js
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [RubyPlugin(), vue()],
})
```

\== React

```js
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [RubyPlugin(), react()],
})
```

\== Svelte

```js
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
  plugins: [RubyPlugin(), svelte()],
})
```

:::

For more information on configuring these plugins, consult [Vite Rails documentation](https://vite-ruby.netlify.app).

## Installation

> \[!NOTE]
> You can skip this step if you have already executed the [Rails generator](/guide/server-side-setup#rails-generator).

### Install dependencies

@available\_since core=3.0.0

Install the Inertia client-side adapter and Vite plugin.

> \[!NOTE]
> The `@inertiajs/vite` plugin supports Vite 7 and Vite 8.

:::tabs key:frameworks

\== Vue

```bash
npm install @inertiajs/vue3 @inertiajs/vite
```

\== React

```bash
npm install @inertiajs/react @inertiajs/vite
```

\== Svelte

```bash
npm install @inertiajs/svelte @inertiajs/vite
```

:::

### Configure Vite

@available\_since core=3.0.0

Add the Inertia plugin to your `vite.config.js` file.

```js
import inertia from '@inertiajs/vite'
import RubyPlugin from 'vite-plugin-ruby'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    RubyPlugin(),
    inertia(),
    // ...
  ],
})
```

### Initialize the Inertia app

Update your main JavaScript file to boot your Inertia app. The Vite plugin handles page resolution and mounting automatically, so a minimal entry point is all you need.

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  pages: '../pages',
})
```

\== React

```js
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp({
  pages: '../pages',
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
  pages: '../pages',
})
```

:::

The `pages` path is relative to the entry point. The Rails generator places the entry point in `app/frontend/entrypoints` and your pages in `app/frontend/pages`, so it uses `../pages`. Without the `pages` option, the plugin looks for pages in the `./pages` and `./Pages` directories next to the entry point. The app mounts automatically.

### React Strict Mode

@available\_since core=3.0.0

The React adapter supports enabling React's [Strict Mode](https://react.dev/reference/react/StrictMode) via the `strictMode` option.

```jsx
createInertiaApp({
  strictMode: true,
  // ...
})
```

### Pages Shorthand

@available\_since core=3.0.0

You may use the `pages` shorthand to customize which directory to search for page components.

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  pages: './AppPages',
  // ...
})
```

\== React

```js
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp({
  pages: './AppPages',
  // ...
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
  pages: './AppPages',
  // ...
})
```

:::

An object may also be provided for more control over how pages are resolved. You only need to include the options you wish to customize.

```js
createInertiaApp({
  pages: {
    path: './Pages',
    extension: '.tsx',
    lazy: true,
    transform: (name, page) => name.replace('/', '-'),
  },
})
```

| Option      | Description                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `path`      | The directory to search for page components.                                                                         |
| `extension` | A string or array of file extensions (e.g., `'.tsx'` or `['.tsx', '.jsx']`). Defaults to your framework's extension. |
| `lazy`      | Whether to lazy-load page components. Defaults to `true`. See [code splitting](/guide/code-splitting).               |
| `transform` | A callback that receives the page name and page object, returning a transformed name.                                |

## Customizing the App

Sometimes you may wish to customize the app instance, for example to register plugins, wrap with providers, or set context values. Pass the `withApp` callback to `createInertiaApp` to hook into the app before it renders.

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  // ...
})

createInertiaApp({
  withApp(app) {
    app.use(i18n)
  },
})
```

\== React

```jsx
import { createInertiaApp } from '@inertiajs/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

createInertiaApp({
  withApp(app) {
    return <QueryClientProvider client={queryClient}>{app}</QueryClientProvider>
  },
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
  withApp(context) {
    context.set('theme', 'dark')
  },
})
```

:::

A second argument provides the current rendering environment via `ssr`, allowing you to conditionally apply logic based on where the app is running.

:::tabs key:frameworks

\== Vue

```js
createInertiaApp({
  withApp(app, { ssr }) {
    app.use(i18n)

    if (!ssr) {
      app.use(browserOnlyPlugin)
    }
  },
})
```

\== React

```jsx
createInertiaApp({
  withApp(app, { ssr }) {
    if (!ssr) {
      return <BrowserProvider>{app}</BrowserProvider>
    }

    return app
  },
})
```

\== Svelte

```js
createInertiaApp({
  withApp(context, { ssr }) {
    context.set('theme', 'dark')

    if (!ssr) {
      context.set('analytics', createAnalytics())
    }
  },
})
```

:::

The second argument also includes the current `page` object, giving you access to the component name, URL, version, and shared props before the app renders. Useful for configuring plugins or providers with server-driven state like the user's locale.

:::tabs key:frameworks

\== Vue

```js
createInertiaApp({
  withApp(app, { page }) {
    const i18n = createI18n({ locale: page.props.locale })

    app.use(i18n)
  },
})
```

\== React

```jsx
createInertiaApp({
  withApp(app, { page }) {
    const i18n = createI18n({ locale: page.props.locale })

    return <I18nProvider i18n={i18n}>{app}</I18nProvider>
  },
})
```

\== Svelte

```js
createInertiaApp({
  withApp(context, { page }) {
    context.set('locale', page.props.locale)
  },
})
```

:::

## Manual Setup

If you prefer not to use the Vite plugin, you may provide the `resolve` and `setup` callbacks manually. The `resolve` callback tells Inertia how to load a page component and receives the component name and the full [page object](/guide/the-protocol). The `setup` callback initializes the client-side framework.

> \[!NOTE]
> A manual `setup` callback prevents the Vite plugin from auto-generating [SSR](/guide/server-side-rendering) handling. You should create a [separate SSR entry point](/guide/server-side-rendering#manual-setup) and update your app to use [client-side hydration](/guide/server-side-rendering#client-side-hydration).

:::tabs key:frameworks

\== Vue

```js
import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.vue')
    return pages[`../pages/${name}.vue`]()
  },
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
})
```

\== React

```jsx
import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.jsx')
    return pages[`../pages/${name}.jsx`]()
  },
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />)
  },
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'
import { mount } from 'svelte'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.svelte')
    return pages[`../pages/${name}.svelte`]()
  },
  setup({ el, App, props }) {
    mount(App, { target: el, props })
  },
})
```

:::

By default, page components are lazy-loaded, splitting each page into its own bundle. To eagerly bundle all pages into a single file instead, see the [code splitting](/guide/code-splitting) documentation.

## Configuring Defaults

@available\_since core=2.2.11

You may pass a `defaults` object to `createInertiaApp()` to configure default settings for various features. You don't have to pass a default for every key, just the ones you want to tweak.

```js
createInertiaApp({
  defaults: {
    form: {
      recentlySuccessfulDuration: 5000,
    },
    prefetch: {
      cacheFor: '1m',
      hoverDelay: 150,
    },
    visitOptions: (href, options) => {
      return {
        headers: {
          ...options.headers,
          'X-Custom-Header': 'value',
        },
      }
    },
  },
  // ...
})
```

The `visitOptions` callback receives the target URL and the current visit options, and should return an object with any options you want to override. For more details on the available configuration options, see the [forms](/guide/forms#form-errors), [prefetching](/guide/prefetching), and [manual visits](/guide/manual-visits#global-visit-options) documentation.

### Updating Configuration at Runtime

You may also update configuration values at runtime using the exported `config` instance. This is particularly useful when you need to adjust settings based on user preferences or application state.

:::tabs key:frameworks
\== Vue

```js
import { config } from '@inertiajs/vue3'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
  'form.recentlySuccessfulDuration': 1000,
  'prefetch.cacheFor': '5m',
})

// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')
```

\== React

```js
import { config } from '@inertiajs/react'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
  'form.recentlySuccessfulDuration': 1000,
  'prefetch.cacheFor': '5m',
})

// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')
```

\== Svelte

```js
import { config } from '@inertiajs/svelte'

// Set a single value using dot notation...
config.set('form.recentlySuccessfulDuration', 1000)
config.set('prefetch.cacheFor', '5m')

// Set multiple values at once...
config.set({
  'form.recentlySuccessfulDuration': 1000,
  'prefetch.cacheFor': '5m',
})

// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')
```

:::

## Defining a Root Element

By default, Inertia assumes that your application's root template has a root element with an `id` of `app`. If your application's root element has a different `id`, you can provide it using the `id` property.

```js
createInertiaApp({
  id: 'my-app',
  // ...
})
```

If you change the `id` of the root element, be sure to update it [server-side](/guide/configuration#root-dom-id) as well.

## Content Security Policy

@available\_since core=3.1.0

For applications using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) that restricts inline styles, you may pass a `nonce` to `createInertiaApp()`. The nonce is applied to the inline styles Inertia injects for the [progress bar](/guide/progress-indicators) and the [error modal](/guide/error-handling), allowing them through your CSP.

```js
createInertiaApp({
  nonce: 'your-csp-nonce',
  // ...
})
```

In Rails, the nonce comes from your [content security policy](https://guides.rubyonrails.org/security.html#content-security-policy-header) configuration. The nonce must be allowed for inline styles, so include `style-src` in `content_security_policy_nonce_directives`:

```ruby
# config/initializers/content_security_policy.rb
Rails.application.configure do
  config.content_security_policy do |policy|
    policy.script_src :self, :https
    policy.style_src :self, :https
    # ...
  end

  config.content_security_policy_nonce_generator = ->(request) { request.session.id.to_s }
  config.content_security_policy_nonce_directives = %w[script-src style-src]
end
```

To pass the nonce to the client, render `csp_meta_tag` in the `<head>` of your root template. The default Rails layout already includes it.

```erb
<head>
  <%= csp_meta_tag %>
  <!-- ... -->
</head>
```

Then read the nonce from the meta tag when creating your Inertia app. The check for `document` keeps the entry point working during [server-side rendering](/guide/server-side-rendering), where no DOM exists:

```js
const nonce =
  typeof document === 'undefined'
    ? undefined
    : document
        .querySelector('meta[name="csp-nonce"]')
        ?.getAttribute('content') || undefined

createInertiaApp({
  nonce,
  // ...
})
```

@available\_since rails=3.21.2

Inertia Rails also adds the nonce to the `<script>` element that holds the initial page data, so you don't need to configure it yourself.

## HTTP Client

@available\_since core=3.0.0

Unlike Inertia 2 and earlier, Inertia 3 uses a built-in XHR client for all requests. No additional HTTP libraries like Axios are required.

### Using Axios

You may provide the `axiosAdapter` as the `http` option when creating your Inertia app. This is useful when your application requires a custom Axios instance.

```js
import { axiosAdapter } from '@inertiajs/core'

createInertiaApp({
  http: axiosAdapter(),
  // ...
})
```

A custom Axios instance may also be provided to the adapter.

```js
import axios from 'axios'
import { axiosAdapter } from '@inertiajs/core'

const instance = axios.create({
  // ...
})

createInertiaApp({
  http: axiosAdapter(instance),
  // ...
})
```

### Interceptors

The built-in XHR client supports interceptors for modifying requests, inspecting responses, or handling errors. These interceptors apply to all HTTP requests made by Inertia, including those from the router, `useForm`, `<Form>`, and `useHttp`.

:::tabs key:frameworks

\== Vue

```js
import { http } from '@inertiajs/vue3'

const removeRequestHandler = http.onRequest((config) => {
  config.headers['X-Custom-Header'] = 'value'
  return config
})

const removeResponseHandler = http.onResponse((response) => {
  console.log('Response status:', response.status)
  return response
})

const removeErrorHandler = http.onError((error) => {
  console.error('Request failed:', error)
})

// Remove a handler when it's no longer needed...
removeRequestHandler()
```

\== React

```js
import { http } from '@inertiajs/react'

const removeRequestHandler = http.onRequest((config) => {
  config.headers['X-Custom-Header'] = 'value'
  return config
})

const removeResponseHandler = http.onResponse((response) => {
  console.log('Response status:', response.status)
  return response
})

const removeErrorHandler = http.onError((error) => {
  console.error('Request failed:', error)
})

// Remove a handler when it's no longer needed...
removeRequestHandler()
```

\== Svelte

```js
import { http } from '@inertiajs/svelte'

const removeRequestHandler = http.onRequest((config) => {
  config.headers['X-Custom-Header'] = 'value'
  return config
})

const removeResponseHandler = http.onResponse((response) => {
  console.log('Response status:', response.status)
  return response
})

const removeErrorHandler = http.onError((error) => {
  console.error('Request failed:', error)
})

// Remove a handler when it's no longer needed...
removeRequestHandler()
```

:::

Each `on*` method returns a cleanup function that removes the handler when called. Request handlers receive the request config and must return it (modified or not). Response handlers receive the response and must also return it. Handlers may be asynchronous.

### Custom HTTP Client

For full control over how requests are made, you may provide a completely custom HTTP client via the `http` option. A custom client must implement the `request` method, which receives an `HttpRequestConfig` and returns a promise resolving to an `HttpResponse`. Review the [xhrHttpClient.ts](https://github.com/inertiajs/inertia/blob/3.x/packages/core/src/xhrHttpClient.ts) source for a reference implementation.

---

---
url: /guide/code-splitting.md
---
# Code Splitting

By default, Inertia 3.x lazy-loads page components, splitting each page into its own bundle that is loaded on demand. This reduces the initial JavaScript bundle size but requires additional requests when visiting new pages.

You may disable lazy loading to eagerly bundle all pages into a single file. Eager loading eliminates per-page requests but increases the initial bundle size.

## Vite Plugin

@available\_since core=3.0.0

The `lazy` option in the `pages` shorthand controls how page components are loaded. It defaults to `true`.

```js
createInertiaApp({
  pages: {
    lazy: false, // Bundle all pages into a single file
  },
  // ...
})
```

## Manual Vite

You may configure code splitting manually using Vite's `import.meta.glob()` function when not using the Inertia Vite plugin. Pass `{ eager: true }` to bundle all pages, or omit it to lazy-load them.

:::tabs key:frameworks

\== Vue

```js
createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.vue') // [!code --:2]
    return pages[`../pages/${name}.vue`]()
    const pages = import.meta.glob('../pages/**/*.vue', { eager: true }) // [!code ++:2]
    return pages[`../pages/${name}.vue`]
  },
})
```

\== React

```js
createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.jsx') // [!code --:2]
    return pages[`../pages/${name}.jsx`]()
    const pages = import.meta.glob('../pages/**/*.jsx', { eager: true }) // [!code ++:2]
    return pages[`../pages/${name}.jsx`]
  },
})
```

\== Svelte

```js
createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.svelte') // [!code --:2]
    return pages[`../pages/${name}.svelte`]()
    const pages = import.meta.glob('../pages/**/*.svelte', { eager: true }) // [!code ++:2]
    return pages[`../pages/${name}.svelte`]
  },
})
```

:::

## Using Shakapacker

To use code splitting with Webpack, you will first need to enable [dynamic imports](https://github.com/tc39/proposal-dynamic-import) via a Babel plugin. Let's install it now.

```bash
npm install @babel/plugin-syntax-dynamic-import
```

Next, create a `.babelrc` file in your project with the following configuration:

```json
{
  "plugins": ["@babel/plugin-syntax-dynamic-import"]
}
```

Finally, update the `resolve` callback in your app's initialization code to use `import` instead of `require`.

:::tabs key:frameworks

\== Vue

```js
resolve: name => require(`../pages/${name}`), // [!code --]
resolve: name => import(`../pages/${name}`), // [!code ++]
```

\== React

```js
resolve: name => require(`../pages/${name}`), // [!code --]
resolve: name => import(`../pages/${name}`), // [!code ++]
```

\== Svelte

```js
resolve: name => require(`../pages/${name}.svelte`), // [!code --]
resolve: name => import(`../pages/${name}.svelte`), // [!code ++]
```

:::

You should also consider using cache busting to force browsers to load the latest version of your assets. To accomplish this, add the following configuration to your webpack configuration file.

```js
output: {
    chunkFilename: 'js/[name].js?id=[chunkhash]',
}
```

---

---
url: /guide/configuration.md
---
# Configuration

Inertia Rails can be configured globally or in a specific controller (and subclasses).

## Global Configuration

Use the `InertiaRails.configure` method to set global configuration options. If using global configuration, we recommend you place the code inside an initializer:

```ruby
# config/initializers/inertia_rails.rb

InertiaRails.configure do |config|
  # Example: force a full-reload if the deployed assets change.
  config.version = ViteRuby.digest
end
```

The default configuration can be found [here](https://github.com/inertiajs/inertia-rails/blob/master/lib/inertia_rails/configuration.rb#L5).

## Local Configuration

The `inertia_config` method allows you to override global settings in specific controllers. Use this method in your controllers to customize configuration for specific parts of your application:

```ruby
class EventsController < ApplicationController
  inertia_config(
    version: "events-#{InertiaRails.configuration.version}",
    ssr_enabled: -> { action_name == "index" },
  )
end
```

## Setting Configuration via Environment Variables

Inertia Rails supports setting any configuration option via environment variables out of the box. For each option in the configuration, you can set an environment variable prefixed with `INERTIA_` and the option name in uppercase. For example: `INERTIA_SSR_ENABLED`.

**Boolean values** (like `INERTIA_DEEP_MERGE_SHARED_DATA` or `INERTIA_SSR_ENABLED`) are parsed from the strings `"true"` or `"false"` (case-sensitive).

## Configuration Options

### `component_path_resolver`

**Default**: `->(path:, action:) { "#{path}/#{action}" }`

Use `component_path_resolver` to customize component path resolution when [`default_render`](#default-render) config value is set to `true`. The value should be callable and will receive the `path` and `action` parameters, returning a string component path. See [Custom Path Resolver](/guide/responses#custom-path-resolver).

### `prop_transformer`

**Default**: `->(props:) { props }`

Use `prop_transformer` to apply a transformation to your props before they're sent to the view. One use-case this enables is to work with `snake_case` props within Rails while working with `camelCase` in your view:

```ruby
  inertia_config(
    prop_transformer: lambda do |props:|
      props.deep_transform_keys { |key| key.to_s.camelize(:lower) }
    end
  )
```

> \[!NOTE]
> This controls the props provided by Inertia Rails but does not concern itself with props coming *into* Rails. You may want to add a global `before_action` to `ApplicationController`:

```ruby
before_action :underscore_params

# ...

def underscore_params
  params.deep_transform_keys! { |key| key.to_s.underscore }
end
```

### `cache_store`

**Default**: `nil` (falls back to `Rails.cache`)

The cache store used for [cached props](/guide/cached-props) and [SSR response caching](/guide/server-side-rendering). Accepts any `ActiveSupport::Cache::Store` instance.

```ruby
InertiaRails.configure do |config|
  config.cache_store = ActiveSupport::Cache::MemoryStore.new
end
```

### `deep_merge_shared_data`

**Default**: `false`
**ENV**: `INERTIA_DEEP_MERGE_SHARED_DATA`

@available\_since rails=3.8.0

When enabled, props will be deep merged with shared data, combining hashes
with the same keys instead of replacing them.

### `default_render`

**Default**: `false`
**ENV**: `INERTIA_DEFAULT_RENDER`

Overrides Rails default rendering behavior to render using Inertia by default.

### `encrypt_history`

**Default**: `false`
**ENV**: `INERTIA_ENCRYPT_HISTORY`

@available\_since rails=3.7.0 core=2.0.0

When enabled, you instruct Inertia to encrypt your app's history, it uses
the browser's built-in [`crypto` api](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
to encrypt the current page's data before pushing it to the history state.

### `preserve_big_integers`

**Default**: `false`
**ENV**: `INERTIA_PRESERVE_BIG_INTEGERS`

@available\_since rails=3.23.0 core=3.8.0

When enabled, integers outside JavaScript's safe range reach your components as native `BigInt` values instead of losing precision. See [Big Integers](/guide/big-integers) for details.

### `ssr_enabled` *(experimental)*

**Default**: `false`
**ENV**: `INERTIA_SSR_ENABLED`

@available\_since rails=3.6.0 core=2.0.0

Whether to use a JavaScript server to pre-render your JavaScript pages,
allowing your visitors to receive fully rendered HTML when they first visit
your application.

Requires a JavaScript server to be available at `ssr_url`. [*Example*](https://github.com/ElMassimo/inertia-rails-ssr-template)

### `ssr_cache`

**Default**: `nil` (disabled)

@available\_since rails=3.19.0

Cache SSR responses to avoid redundant Node.js render requests for identical page data. Accepts `true`, `false`/`nil`, or a Hash of `Rails.cache.fetch` options (e.g. `{ expires_in: 1.hour }`). Lambdas are supported and evaluated in the controller context. Can be overridden per render call.

See [SSR response caching](/guide/server-side-rendering#ssr-response-caching) for usage examples.

### `ssr_url` *(experimental)*

**Default**: `nil` (auto-detects from Vite dev server, falls back to `http://localhost:13714/render`)
**ENV**: `INERTIA_SSR_URL`

The URL of the SSR server. When `nil`, auto-detects from the Vite dev server.

> \[!NOTE]
> Inertia SSR expects the server to respond at `/render` (production) or `/__inertia_ssr` (dev). If you set a server address, `/render` is appended automatically unless the URL already ends with `/render` or `/__inertia_ssr`.

### `ssr_timeout`

**Default**: `10`
**ENV**: `INERTIA_SSR_TIMEOUT`

@available\_since rails=3.23.0

Seconds to wait for the SSR server to connect and respond. When the wait runs out, the page falls back to client-side rendering, as on any other SSR error.

### `ssr_raise_on_error`

**Default**: `false`
**ENV**: `INERTIA_SSR_RAISE_ON_ERROR`

@available\_since rails=3.19.0

When enabled, SSR failures raise `InertiaRails::SSRError` instead of falling back to client-side rendering. The failure is still logged and passed to `on_ssr_error` if you defined one, but it is not reported to `Rails.error`. Not recommended for production.

```ruby
InertiaRails.configure do |config|
  config.ssr_raise_on_error = Rails.env.test?
end
```

See [Raising on Error](/guide/server-side-rendering#raising-on-error).

### `on_ssr_error`

**Default**: `nil`

@available\_since rails=3.19.0

A callable that receives the `InertiaRails::SSRError` and the page hash when SSR fails. Defining it replaces the automatic report to `Rails.error`.

```ruby
InertiaRails.configure do |config|
  config.on_ssr_error = ->(error, page) do
    Rails.logger.warn("SSR failed for #{page[:component]}: #{error.message}")
  end
end
```

See [Customizing Error Handling](/guide/server-side-rendering#customizing-error-handling).

### `ssr_bundle`

**Default**: `nil`
**ENV**: `INERTIA_SSR_BUNDLE`

@available\_since rails=3.19.0

A path, or an array of paths, to your SSR bundle. When set, Inertia Rails only attempts SSR if one of the files exists, and renders on the client otherwise. The check is skipped while the Vite dev server is running. The [Puma plugin](/guide/server-side-rendering#puma-plugin) also starts the first path that exists.

```ruby
InertiaRails.configure do |config|
  config.ssr_bundle = 'public/vite-ssr/ssr.js'
end
```

When `nil`, every render attempts SSR, and the Puma plugin finds the bundle on its own (see [Bundle Resolution](/guide/server-side-rendering#bundle-resolution)). Keep it `nil` when the web server cannot see the bundle, for example when the SSR server runs in a separate container.

### `ssr_runtime`

**Default**: `nil` (auto-detected)
**ENV**: `INERTIA_SSR_RUNTIME`

@available\_since rails=3.20.0

The JavaScript runtime the [Puma plugin](/guide/server-side-rendering#puma-plugin) uses to run the SSR bundle, such as `"node"`, `"bun"`, or `"deno"`. When `nil`, it is detected from your lockfile. The Puma plugin only reads the global setting. See [Runtime Detection](/guide/server-side-rendering#runtime-detection).

### `version` *(recommended)*

**Default**: `nil`
**ENV**: `INERTIA_VERSION`

This allows Inertia to detect if the app running in the client is oudated,
forcing a full page visit instead of an XHR visit on the next request.

See [assets versioning](/guide/asset-versioning).

### `always_include_errors_hash`

**Default**: `nil`
**ENV**: `INERTIA_ALWAYS_INCLUDE_ERRORS_HASH`

@available\_since rails=3.11.0

Whether to include an empty `errors` hash in the props when no validation errors are present.

When set to `true`, an empty `errors: {}` object will always be included in Inertia responses. When set to `false`, the `errors` key will be omitted when there are no errors. The default value `nil` currently behaves like `false` but shows a deprecation warning.

The default value will be changed to `true` in the next major version.

### `xsrf_cookie_refresh`

**Default**: `:always`
**ENV**: `INERTIA_XSRF_COOKIE_REFRESH`

@available\_since rails=3.22.0

Controls when the Rails adapter refreshes the `XSRF-TOKEN` cookie on protected requests.

Supported values:

* `:always` refreshes the cookie on every protected request. This is the default behavior.
* `:lazy` avoids refreshing the cookie on `GET` / `HEAD` when the cookie already exists. Non-safe requests continue refreshing it on every protected request.

```ruby
InertiaRails.configure do |config|
  config.xsrf_cookie_refresh = :lazy
end
```

You may also override this per controller:

```ruby
class CachedPagesController < ApplicationController
  inertia_config xsrf_cookie_refresh: :lazy
end
```

This is useful for applications that serve Inertia pages through a CDN or rely on HTTP conditional caching (`ETag` / `304`): most shared caches refuse to cache responses that carry `Set-Cookie`, and the default policy emits one on every response. See the [HTTP caching and XSRF cookie refresh cookbook note](/cookbook/http-caching-and-xsrf-cookie-refresh) for the full mechanism and caveats.

This setting has no effect on controllers using Rails 8.2's `:header_only` forgery protection strategy — authenticity tokens are never read there, so the adapter skips the `XSRF-TOKEN` cookie entirely. See [Header-Only CSRF Protection](/guide/csrf-protection#header-only-csrf-protection-rails-8-2).

### `convert_external_redirects`

**Default**: `true`
**ENV**: `INERTIA_CONVERT_EXTERNAL_REDIRECTS`

@available\_since rails=3.23.0

Whether to automatically convert redirects to external (cross-origin) URLs into Inertia location responses (`409 Conflict` with the `X-Inertia-Location` header) for Inertia requests.

Browsers follow XHR redirects transparently, so the Inertia client can never see a redirect to another origin — the follow-up request to the external URL fails CORS checks. Converting the redirect lets the client perform a full `window.location` visit instead. See [external redirects](/guide/redirects#external-redirects).

Same-origin redirects are never converted automatically — mark them with [`inertia: { full_page: true }`](/guide/redirects#same-origin-redirects) when the target is not an Inertia endpoint.

Set to `false` to keep plain redirect responses untouched (for example, if your test suite asserts `302` responses for external redirects). The conversion can also be disabled for a specific controller:

```ruby
class OAuthCallbacksController < ApplicationController
  inertia_config convert_external_redirects: false
end
```

> \[!NOTE]
> The origin comparison relies on the request scheme as Rails sees it (`X-Forwarded-Proto` is honored, as it is everywhere in Rails). If your app is behind a proxy, make sure it forwards this header — otherwise every absolute `https://` redirect to your own host will look cross-origin and trigger a full page visit.

### `convert_fragment_redirects`

**Default**: `false`
**ENV**: `INERTIA_CONVERT_FRAGMENT_REDIRECTS`

@available\_since rails=3.23.0 core=3.0.0

Whether to keep URL fragments on Inertia redirects to URLs like `/articles/1#comments`, by responding with `409 Conflict` and the `X-Inertia-Redirect` header. See [Redirecting to Fragments](/guide/redirects#redirecting-to-fragments).

### `flash_keys`

**Default**: `%i[notice alert]`

@available\_since rails=3.17.0 core=2.3.3

Specifies which Rails flash keys are exposed to the frontend. By default, only known-safe keys (`notice`, `alert`) are included.

```ruby
InertiaRails.configure do |config|
  # Default: safe keys only
  config.flash_keys = %i[notice alert]

  # Add your custom keys
  config.flash_keys = %i[notice alert toast message]

  # Disable Rails flash integration (use only flash.inertia)
  config.flash_keys = nil
end
```

See the [flash data documentation](/guide/flash-data) for more details on using flash with Inertia.

### `parent_controller`

**Default**: `'::ApplicationController'`
**ENV**: `INERTIA_PARENT_CONTROLLER`

Specifies the base controller class for the internal `StaticController` used to render [Shorthand routes](/guide/routing#shorthand-routes).

By default, Inertia Rails creates a `StaticController` that inherits from `ApplicationController`. You can use this option to specify a different base controller (for example, to include custom authentication, layout, or before actions).

### `root_dom_id`

**Default**: `'app'`
**ENV**: `INERTIA_ROOT_DOM_ID`

@available\_since rails=3.15.0

Specifies the DOM element ID used for the root Inertia.js element.

```ruby
InertiaRails.configure do |config|
  config.root_dom_id = 'inertia-app'
end
```

> \[!NOTE]
> Make sure your client-side Inertia setup uses the same ID when calling `createInertiaApp`.

### `use_script_element_for_initial_page`

**Default**: `false`
**ENV**: `INERTIA_USE_SCRIPT_ELEMENT_FOR_INITIAL_PAGE`

@available\_since rails=3.15.0 core=2.2.20

When enabled the initial page data is rendered in a `<script type="application/json">` element instead of the `data-page` attribute on the root `<div>`.
This provides two main benefits:

1. **Smaller page size**: JSON data doesn't require HTML entity encoding, reducing the overall HTML payload size.
2. **Faster parsing**: The browser can parse raw JSON directly from the script element, which is more efficient than parsing HTML-encoded JSON from an attribute.

```ruby
InertiaRails.configure do |config|
  config.use_script_element_for_initial_page = true
end
```

When disabled (default), the HTML output looks like:

```html
<div id="app" data-page='{"component":"Users/Index",...}'></div>
```

When enabled, the HTML output looks like:

```html
<script data-page="app" type="application/json">
  {"component":"Users/Index",...}
</script>
<div id="app"></div>
```

> \[!NOTE]
> When using this option make sure your client-side Inertia setup is configured to read the page data from the `<script>` element.
> See the [upgrade guide](/guide/upgrade-guide#future-options-removed) for more details.

### `precognition_prevent_writes`

**Default**: `false`
**ENV**: `INERTIA_PRECOGNITION_PREVENT_WRITES`

When enabled, any database write during a precognition request will raise `ActiveRecord::ReadOnlyError`. This helps catch accidental side effects in your controller actions during validation-only requests.

```ruby
InertiaRails.configure do |config|
  config.precognition_prevent_writes = true
end
```

> \[!NOTE]
> This option requires ActiveRecord. It uses `ActiveRecord::Base.while_preventing_writes` to block writes during precognition requests.

> \[!WARNING]
> This only prevents database writes. If your action has other side effects (e.g., sending emails, calling third-party APIs, enqueuing jobs), you should guard those manually. Place `precognition!` before any side-effect-producing code to ensure the action halts before reaching them.

### `use_data_inertia_head_attribute`

**Default**: `false`
**ENV**: `INERTIA_USE_DATA_INERTIA_HEAD_ATTRIBUTE`

@available\_since rails=3.17

Controls which HTML attribute is used to mark Inertia-managed `<head>` tags.

When set to `false` (default), Inertia Rails uses the `inertia` attribute:

```html
<meta name="description" content="Inertia rules" inertia="meta-12345678" />
```

When set to `true`, Inertia Rails uses the [`data-*` attribute](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) `data-inertia` instead:

```html
<meta name="description" content="Inertia rules" data-inertia="meta-12345678" />
```

### `server_head`

**Default**: `false`
**ENV**: `INERTIA_SERVER_HEAD`

@available\_since rails=3.23.0 core=3.5.0

When enabled, [server driven meta tags](/cookbook/server-managed-meta-tags) are serialized into the `head` prop as ready-to-render HTML strings for the `serverHead` option of `createInertiaApp` (Inertia.js v3.5+), instead of structured objects for the client-side cookbook component.

```ruby
InertiaRails.configure do |config|
  config.server_head = true
end
```

```js
createInertiaApp({
  serverHead: true,
  // ...
})
```

Set it to a string to use a custom prop name — for example, when your app already uses a `head` prop (the prop name is reserved while `server_head` is enabled, and Inertia Rails raises an error if a page defines a prop with that name):

```ruby
config.server_head = 'server_meta'
```

```js
createInertiaApp({
  serverHead: 'server_meta',
  // ...
})
```

> \[!NOTE]
> With this option enabled, head elements are always marked with the `data-inertia` attribute regardless of the `use_data_inertia_head_attribute` setting, since Inertia.js v3 only recognizes `data-inertia`.

### `meta_title_template`

**Default**: `nil`

@available\_since rails=3.23.0

A callable applied to the `<title>` tag of [server driven meta tags](/cookbook/server-managed-meta-tags). It receives the current title (or `nil` when the page sets none), runs in the controller context, and its result becomes the title — so it can also provide a default for pages without one:

```ruby
InertiaRails.configure do |config|
  config.meta_title_template = ->(title) { title ? "#{title} - My App" : 'My App' }
end
```

See [Title Template](/cookbook/server-managed-meta-tags#title-template) for details.

### `devtools.enabled`

**Default**: `nil`

@available\_since rails=3.23.0 core=3.6.0

Whether to record requests for the [Inertia DevTools](/guide/devtools) extension. `nil` records in development only; `true` or `false` force it on or off everywhere. Also settable with the `INERTIA_DEVTOOLS_ENABLED` environment variable.

DevTools settings live under `config.devtools` and are global: `inertia_config` does not take them. `enabled`, `storage_path`, `ttl`, and `limit` can also be set with `INERTIA_DEVTOOLS_<NAME>` environment variables.

See [DevTools](/guide/devtools) for the rest of the `devtools` settings.

---

---
url: /guide/csrf-protection.md
---
# CSRF Protection

## Making Requests

Inertia's Rails adapter automatically includes the proper CSRF token when making requests via Inertia or Axios. Therefore, **no additional configuration is required**.

However, if you need to handle CSRF protection manually, one approach is to include the CSRF token as a prop on every response. You can then use the token when making Inertia requests.

:::tabs key:frameworks
\== Vue

```js
import { router, usePage } from '@inertiajs/vue3'

const page = usePage()

router.post('/users', {
  authenticity_token: page.props.csrf_token,
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

\== React

```js
import { router, usePage } from '@inertiajs/react'

const props = usePage().props

router.post('/users', {
  authenticity_token: props.csrf_token,
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

\== Svelte

```js
import { page, router } from '@inertiajs/svelte'

router.post('/users', {
  authenticity_token: page.props.csrf_token,
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

:::

You can even use Inertia's [shared data](/guide/shared-data) functionality to automatically include the `csrf_token` with each response.

A better approach is to use Inertia's built-in XSRF token handling. Inertia's HTTP client automatically checks for the existence of an `XSRF-TOKEN` cookie and, when present, includes the token in an `X-XSRF-TOKEN` header for every request it makes.

By default, the Rails adapter refreshes the `XSRF-TOKEN` cookie on every protected request so Inertia can send it back as `X-XSRF-TOKEN`.

If your app uses browser HTTP conditional caching (`ETag` / `304`) on Inertia pages, you may prefer a less aggressive policy:

```ruby
InertiaRails.configure do |config|
  config.xsrf_cookie_refresh = :lazy
end
```

That keeps the default behavior for non-safe requests while avoiding unnecessary XSRF cookie rewrites on steady-state `GET` / `HEAD` requests once the cookie already exists. See the cookbook note on [HTTP caching and XSRF cookie refresh](/cookbook/http-caching-and-xsrf-cookie-refresh) for validation details and caveats.

## Header-Only CSRF Protection (Rails 8.2+)

@available\_since rails=3.23.0

Rails 8.2 introduces a new default forgery protection strategy, `:header_only`, which verifies requests using the `Sec-Fetch-Site` header sent by modern browsers instead of authenticity tokens. Under this strategy Rails never reads a token, so there is nothing for the client to send back.

The Rails adapter detects the strategy on each responding controller and stops issuing the `XSRF-TOKEN` cookie entirely — no token is generated or exchanged, and no `Set-Cookie` header is emitted. Inertia's HTTP client only sends `X-XSRF-TOKEN` when the cookie exists, so no client-side configuration is required.

This follows the strategy configured in Rails, per controller:

```ruby
# Application-wide, via the Rails 8.2 defaults (config.load_defaults 8.2)
# or explicitly:
config.action_controller.forgery_protection_verification_strategy = :header_only
```

```ruby
# Or per controller:
class ModernController < ApplicationController
  protect_from_forgery using: :header_only
end
```

Controllers using `:header_or_legacy_token` (the strategy Rails falls back to without the 8.2 defaults) still rely on authenticity tokens for browsers that don't send `Sec-Fetch-Site`, so the adapter keeps refreshing the `XSRF-TOKEN` cookie for them. On Rails versions without verification strategies, behavior is unchanged.

## Sessionless Controllers in Hybrid Applications

When Inertia coexists with sessionless controllers in the same Rails application — such as token-authenticated API endpoints, webhook receivers, or any controller that does not rely on the session — it's important to configure CSRF protection correctly on those controllers.

A common pattern is to reach for `skip_forgery_protection`:

```ruby
class SessionlessController < ApplicationController
  skip_forgery_protection
end
```

However, `skip_forgery_protection` only removes the `verify_authenticity_token` before-action — it does not disable the CSRF infrastructure. Rails' `protect_against_forgery?` still returns `true`, so InertiaRails' after-action fires and calls `form_authenticity_token`, which reads and writes `session[:_csrf_token]`. This causes a session record to be loaded (and created, if one doesn't exist) for every request, even though the controller has explicitly opted out of CSRF.

The correct approach is to set `allow_forgery_protection` to `false` on the controller class:

```ruby
class SessionlessController < ApplicationController
  self.allow_forgery_protection = false
end
```

`allow_forgery_protection` is a per-class setting — it does not affect other controllers in the application. Setting it to `false` makes `protect_against_forgery?` return `false`, so InertiaRails' after-action is unconditionally skipped — no XSRF cookie is set, `form_authenticity_token` is never called, and no session I/O occurs.

## Handling Mismatches

When a CSRF token mismatch occurs, Rails raises the `ActionController::InvalidAuthenticityToken` error which results in a `422` error page. Since that isn't a valid Inertia response, the error is shown in a modal.

Obviously, this isn't a great user experience. A better way to handle these errors is to return a redirect back to the previous page, along with a flash message that the page expired. This will result in a valid Inertia response with the flash message available as a prop which you can then display to the user. Of course, you'll need to share your [flash messages](/guide/flash-data) with Inertia for this to work.

You may modify your application's exception handler to automatically redirect the user back to the page they were previously on while flashing a message to the session. To accomplish this, you can use Rails' `rescue_from` (or by overriding `handle_unverified_request`) in your base controller.

```ruby
class InertiaController < ApplicationController
  rescue_from ActionController::InvalidAuthenticityToken do
    redirect_back_or_to root_path, alert: "The page expired, please try again."
  end
end
```

The end result is a much better experience for your users. Instead of seeing the error modal, the user is instead presented with a message that the page "expired" and are asked to try again.

---

---
url: /guide/deferred-props.md
---
# Deferred Props

@available\_since rails=3.6.0 core=2.0.0

Inertia's deferred props feature allows you to defer the loading of certain page data until after the initial page render. This can be useful for improving the perceived performance of your app by allowing the initial page render to happen as quickly as possible.

## Server Side

To defer a prop, you can use the `InertiaRails.defer` method when returning your response. This method receives a callback that returns the prop data. The callback will be executed in a separate request after the initial page render.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: -> { User.all },
      roles: -> { Role.all },
      permissions: InertiaRails.defer { Permission.all },
    }
  end
end
```

### Grouping Requests

By default, all deferred props get fetched in one request after the initial page is rendered, but you can choose to fetch data in parallel by grouping props together using the `group` option with the `InertiaRails.defer` method.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: -> { User.all },
      roles: -> { Role.all },
      permissions: InertiaRails.defer { Permission.all },
      teams: InertiaRails.defer(group: 'attributes') { Team.all },
      projects: InertiaRails.defer(group: 'attributes') { Project.all },
      tasks: InertiaRails.defer(group: 'attributes') { Task.all },
    }
  end
end
```

In the example above, the `teams`, `projects`, and `tasks` props will be fetched in one request, while the `permissions` prop will be fetched in a separate request in parallel. Group names are arbitrary strings and can be anything you choose.

### Combining with Mergeable Props

Deferred props can be combined with mergeable props. You can learn more about this feature in the [Merging props](/guide/merging-props) section.

## Client Side

On the client side, Inertia provides the `Deferred` component to help you manage deferred props. This component will automatically wait for the specified deferred props to be available before rendering its children.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Deferred } from '@inertiajs/vue3'
</script>

<template>
  <Deferred data="permissions">
    <template #fallback>
      <div>Loading...</div>
    </template>

    <div v-for="permission in permissions">
      <!-- ... -->
    </div>
  </Deferred>
</template>
```

\== React

```jsx
import { Deferred } from '@inertiajs/react'

export default () => (
  <Deferred data="permissions" fallback={<div>Loading...</div>}>
    <PermissionsChildComponent />
  </Deferred>
)
```

\== Svelte

```svelte
<script>
  import { Deferred } from '@inertiajs/svelte'

  let { permissions } = $props()
</script>

<Deferred data="permissions">
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  {#each permissions as permission}
    <!-- ... -->
  {/each}
</Deferred>
```

:::

## Multiple Deferred Props

If you need to wait for multiple deferred props to become available, you can specify an array to the `data` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Deferred } from '@inertiajs/vue3'
</script>

<template>
  <Deferred :data="['teams', 'users']">
    <template #fallback>
      <div>Loading...</div>
    </template>

    <!-- Props are now loaded -->
  </Deferred>
</template>
```

\== React

```jsx
import { Deferred } from '@inertiajs/react'

export default () => (
  <Deferred data={['teams', 'users']} fallback={<div>Loading...</div>}>
    <ChildComponent />
  </Deferred>
)
```

\== Svelte

```svelte
<script>
  import { Deferred } from '@inertiajs/svelte'

  let { teams, users } = $props()
</script>

<Deferred data={['teams', 'users']}>
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  <!-- Props are now loaded -->
</Deferred>
```

:::

## Reloading Indicator

@available\_since core=3.0.0

When deferred props are being reloaded via a partial reload, the `Deferred` component exposes a `reloading` boolean through its slot. This allows you to show a loading indicator while still displaying the previously loaded data.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Deferred } from '@inertiajs/vue3'
</script>

<template>
  <Deferred data="permissions" #default="{ reloading }">
    <template #fallback>
      <div>Loading...</div>
    </template>

    <div :class="{ 'opacity-50': reloading }">
      <div v-for="permission in permissions">
        <!-- ... -->
      </div>
    </div>
  </Deferred>
</template>
```

\== React

```jsx
import { Deferred } from '@inertiajs/react'

export default () => (
  <Deferred data="permissions" fallback={<div>Loading...</div>}>
    {({ reloading }) => (
      <div className={reloading ? 'opacity-50' : ''}>
        <PermissionsChildComponent />
      </div>
    )}
  </Deferred>
)
```

\== Svelte

```svelte
<script>
  import { Deferred } from '@inertiajs/svelte'

  let { permissions } = $props()
</script>

<Deferred data="permissions">
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  {#snippet children({ reloading })}
    <div class:opacity-50={reloading}>
      {#each permissions as permission}
        <!-- ... -->
      {/each}
    </div>
  {/snippet}
</Deferred>
```

:::

The `reloading` prop is `false` on the initial load and becomes `true` whenever a partial reload is in progress for the deferred keys. It returns to `false` once the reload completes.

## Error Handling

@available\_since rails=3.21.2 core=3.1.0

By default, exceptions thrown while resolving a deferred prop result in an error response. You may instruct Inertia to rescue these exceptions by passing `rescue: true` to `InertiaRails.defer`.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      permissions: InertiaRails.defer(rescue: true) { current_user.permissions },
    }
  end
end
```

When a deferred prop is rescued, it is omitted from the response and the exception is reported via Rails's [Error Reporter](https://guides.rubyonrails.org/error_reporting.html#using-the-error-reporter).

> \[!NOTE]
> To catch errors reliably, Inertia serializes the rescued prop (by calling `as_json` on its value) within the rescued scope. This means lazy values such as `ActiveRecord::Relation`s have their queries executed, and serialization errors are caught too — not just exceptions raised directly within the block.

On the client side, you may provide a `rescue` slot to the `Deferred` component to render a fallback UI when a prop fails to load.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Deferred, router } from '@inertiajs/vue3'
</script>
<template>
  <Deferred data="permissions">
    <template #fallback>
      <div>Loading...</div>
    </template>
    <template #rescue="{ reloading }">
      <div>
        <p>Failed to load permissions.</p>
        <button
          :disabled="reloading"
          @click="router.reload({ only: ['permissions'] })"
        >
          Retry
        </button>
      </div>
    </template>
    <div v-for="permission in permissions">
      <!-- ... -->
    </div>
  </Deferred>
</template>
```

\== React

```jsx
import { Deferred, router } from '@inertiajs/react'

export default () => (
  <Deferred
    data="permissions"
    fallback={<div>Loading...</div>}
    rescue={({ reloading }) => (
      <div>
        <p>Failed to load permissions.</p>
        <button
          disabled={reloading}
          onClick={() => router.reload({ only: ['permissions'] })}
        >
          Retry
        </button>
      </div>
    )}
  >
    <PermissionsChildComponent />
  </Deferred>
)
```

\== Svelte

```svelte
<script>
  import { Deferred, router } from '@inertiajs/svelte'
  let { permissions } = $props()
</script>

<Deferred data="permissions">
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}
  {#snippet rescue({ reloading })}
    <div>
      <p>Failed to load permissions.</p>
      <button
        disabled={reloading}
        onclick={() => router.reload({ only: ['permissions'] })}>Retry</button
      >
    </div>
  {/snippet}
  {#each permissions as permission}
    <!-- ... -->
  {/each}
</Deferred>
```

:::

The rescue state is preserved until you explicitly reload the rescued prop. The `rescue` slot receives a `reloading` boolean, allowing you to disable the retry button or show a loading indicator while the reload is in progress.

## Combining with Once Props

@available\_since rails=3.15.0 core=2.2.20

You may pass the `once: true` argument to a deferred prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      stats: InertiaRails.defer(once: true) { Stats.generate },
    }
  end
end
```

For more information on once props, see the [once props](/guide/once-props) documentation.

## Combining with Caching

@available\_since rails=3.21.0

You may pass the `cache` option to a deferred prop to cache the resolved value on the server side. On cache hits, the block is not evaluated.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      feed: InertiaRails.defer(cache: { key: 'feed', expires_in: 5.minutes }, group: 'feed') { current_user.feed },
    }
  end
end
```

For more information on cache keys and options, see the [cached props](/guide/cached-props) documentation.

---

---
url: /guide/demo-application.md
---
# Demo Application

The official Inertia.js v3 demo application is a comprehensive [Kitchen Sink](https://demo-v3.inertiajs.com) app built with Laravel and Vue. It includes a mini CRM with contacts, organizations, and notes, along with dedicated feature showcase pages covering forms, navigation, data loading, prefetching, state management, layouts, events, error handling, and more. You may find the source code on [GitHub](https://github.com/inertiajs/demo-v3).

The demo is hosted on [Laravel Cloud](https://cloud.laravel.com) and the database is reset every midnight. Please be respectful when editing data.

## Inertia 1.x-2.x Demo App

The previous demo app for Inertia.js is called [Ping CRM](https://demo.inertiajs.com). This application is built using Laravel and Vue. You can find the source code on [GitHub](https://github.com/inertiajs/pingcrm).

In addition to the Vue version of Ping CRM, we also maintain a Svelte version of the application, which you can find [on GitHub](https://github.com/inertiajs/pingcrm-svelte).

### Third Party

Beyond our official demo app, Ping CRM has also been translated into numerous different languages and frameworks.

| Platform                                                                | Author            |
| :---------------------------------------------------------------------- | :---------------- |
| [Ruby on Rails/Vue](https://github.com/ledermann/pingcrm)               | Georg Ledermann   |
| [Ruby on Rails/Vue SSR/Vite](https://github.com/ElMassimo/pingcrm-vite) | Máximo Mussini    |
| [Clojure/React](https://github.com/prestancedesign/pingcrm-clojure)     | Michaël Salihi    |
| [Echo/Vue](https://github.com/kohkimakimoto/pingcrm-echo)               | Kohki Makimoto    |
| [Grails/Vue](https://github.com/matrei/pingcrm-grails)                  | Mattias Reichel   |
| [Laravel/React](https://github.com/Landish/pingcrm-react)               | Lado Lomidze      |
| [Laravel/Mithril.js](https://github.com/tbreuss/pingcrm-mithril)        | Thomas Breuss     |
| [Laravel/Svelte](https://github.com/zgabievi/pingcrm-svelte)            | Zura Gabievi      |
| [Symfony/Vue](https://github.com/aleksblendwerk/pingcrm-symfony)        | Aleks Seltenreich |
| [Yii 2/Vue](https://github.com/tbreuss/pingcrm-yii2)                    | Thomas Breuss     |

---

---
url: /guide/devtools.md
---
# DevTools

@available\_since rails=3.23.0 core=3.6.0

[Inertia DevTools](https://inertiajs.com/docs/v3/advanced/devtools) is a browser extension that records every Inertia request your app makes and shows you its props, headers, route, and merged page state. Inertia Rails implements the server half of the [DevTools protocol](https://inertiajs.com/docs/v3/advanced/devtools-protocol), so recording works with no setup in development.

## Installation

Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/inertiajs-devtools/cbaffpghpcbmgbnlpamegieokkpdlnih) or [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/inertia-js-devtools/), or load a [GitHub release](https://github.com/inertiajs/inertia-devtools/releases) unpacked. The client-side integrations follow the `dev` option of `createInertiaApp`, which defaults to `import.meta.env.DEV`, so Vite apps need nothing else. With another bundler, turn it on for development builds:

```js
createInertiaApp({
  // ...
  dev: true,
})
```

Open your browser's DevTools on your app and pick the **Inertia** panel. Navigate around your application and each visit will appear in the timeline.

> \[!NOTE]
> Run the Vite development server for full functionality. In dev mode Inertia exposes the hooks the panel relies on for client-side detail such as visit options and request grouping. Without them, requests are still recorded, but some client-side features are unavailable.

## The Timeline

Every Inertia request is listed in the timeline on the left, with a live indicator while it is in flight. You may filter by method, request type, or status, or search by URL and component. Request types include full visits, [partial reloads](/guide/partial-reloads), [deferred prop loads](/guide/deferred-props), [polls](/guide/polling), [prefetches](/guide/prefetching), and [Precognition validation](/guide/precognition). Related requests are grouped rather than listed separately, so a page visit and its follow-up requests appear together. The grouping is determined on the client because only the browser can tell a poll from a full navigation or know whether a prefetch was served from cache.

## Inspecting a Request

Selecting a request opens its detail, split into four tabs.

The **Props** tab lists every prop as a tree, with a badge indicating whether it is deferred, optional, merged, or shared with `inertia_share`, and a `file:line` link into your editor. Values expand inline. Alongside it, the **HTTP** tab shows the request and response headers and bodies with sensitive values [redacted](#redaction), and the **Route** tab shows the matched route name, URI, and controller action.

The **Page** tab shows the full page state after Inertia has handled the response. A partial reload might send only one prop over the wire, but Inertia merges it into the existing page, so this tab shows the complete result, not only what arrived in the response.

[What gets recorded](#what-gets-recorded) lists the server data behind each tab.

## Client-Side Events

Some interactions never reach the server, so the Network tab shows nothing for them. The extension records them as their own timeline entries: [client-side visits](/guide/manual-visits#client-side-visits) and requests served from the [prefetch](/guide/prefetching) cache.

## Editor Links

File references throughout the panel link directly to your editor. You may use the editor picker in the toolbar to choose your editor. VS Code, PhpStorm, Cursor, and Zed register their URL schemes on install and work out of the box. Sublime Text ships no URL-scheme handler, so its links do nothing until you install one such as [SublimeUrl](https://github.com/inopinatus/sublime_url).

## What gets recorded

Every response is recorded as the browser receives it, whether or not it is an Inertia response, and stamped with an `X-Inertia-Devtools-Id` header. Requests the browser makes for images, stylesheets, scripts, fonts, and sockets are left out. Initial Inertia page loads also render a `<script data-inertia-devtools-id>` tag next to the root element (`inertia_root` does this; call `inertia_devtools_tag` yourself if your layout builds the root element), so the extension can find the entry before any XHR happens.

An app mounted under a path prefix (`map '/admin'` in `config.ru`) also sends the prefix in an `X-Inertia-Devtools-Base-Path` header and on the tag, so the extension reads entries from beneath it.

Requests rendered by Rails exception handling are recorded with their final status. If exceptions are configured to propagate instead, no response comes back to record.

For Inertia renders, the entry also carries:

* **Props** — every top-level prop, and every nested one that has a type or comes from `inertia_share`, keyed by its dot path and badged with its type (`always`, `optional`, `defer`, `merge`, `scroll`, `once`), its defer group, merge direction, and whether it came from `inertia_share`.
* **Editor links** — the file and line of the `render inertia:` call (the action itself for an implicit render, or the `inertia` route definition in development on Rails 8.1+), of the `inertia_share` block each shared prop came from, and of the controller action. Each prop links to the line of its own key on Ruby 3.3+ or with the `prism` gem in your bundle, and to the `render inertia:` call otherwise.
* **Route** — the matched URI pattern (Rails 7.1+), route name (Rails 8.1+), and `Controller#action`.
* **Page** — the full page object the client received.

Deferred and optional props are skipped before resolution on a first load, so they show up on the request that actually delivers them, not on the initial one.

Props renamed by [`prop_transformer`](/guide/configuration#prop-transformer) are shown with their values but without their type, source, or `inertia_share` badge.

## Linking props to serializers

An object that responds to `to_inertia` can be passed as `props:` or used as a prop value, including inside an array or returned from a closure or a prop type's block; Inertia Rails renders the hash it returns. Its props link to the `render inertia:` call by default. To link each one to where the serializer declares it, also define `inertia_prop_sources`, returning `[file, line]` pairs keyed like that hash:

```ruby
class CourseSerializer
  def initialize(course)
    @course = course
  end

  def to_inertia
    { title: title }
  end

  def title
    @course.title
  end

  def inertia_prop_sources
    { 'title' => method(:title).source_location }
  end
end
```

A serializer nested in another one reports its own keys; DevTools adds the path it sits under. `inertia_prop_sources` is only called while DevTools records, and an error inside it is reported and ignored, so the page still renders.

## Enabling and disabling

DevTools has two independent switches, one on the server and one on the client. Both default to on in development and off in production.

Recording is on in development and off everywhere else. Set `config.devtools.enabled` (or the `INERTIA_DEVTOOLS_ENABLED` environment variable, `true` or `false`) to override:

```ruby
InertiaRails.configure do |config|
  config.devtools.enabled = true
end
```

DevTools settings live under `config.devtools` and are global rather than per controller, since recording runs in middleware, so `inertia_config` does not take them. While DevTools is off, the `/_inertia/devtools` paths are not claimed at all: requests to them fall through to your app's own routes.

In development every request is recorded and the read API is open. Everywhere else, the test environment included, nothing is recorded or served until you name who may use DevTools:

```ruby
InertiaRails.configure do |config|
  config.devtools.enabled = true
  config.devtools.authorize = -> { Current.user&.admin? }
  config.devtools.base_controller = 'ApplicationController'
end
```

The callable runs in your own controllers, after their filters, so `Current.user` or Devise's `current_user` is set. It runs on every request while DevTools is enabled, so keep it cheap.

It decides whose requests are recorded: everyone else gets no DevTools headers, tag, or entry. Requests no controller handled, such as routing errors, are recorded only in development without a callable.

It also decides who may read entries. The read API inherits `base_controller`, a bare `ActionController::API` by default, so point it at a controller whose filters sign users in, such as `ApplicationController` or your admin base controller, for the callable to see the same user there. The read API never writes the session back.

> \[!NOTE]
> The base controller's filters run on every entry the extension fetches. A filter that expects every action to authorize something, such as Pundit's `verify_authorized`, needs a skip in `InertiaRails::Devtools::EntriesController`. The base controller is read when the app boots: set it in an initializer and restart the server after changing it.

The extension reads an entry for every response it sees, so those requests are kept out of the log. Only the `/_inertia/devtools` paths are silenced; your app's own requests log normally.

On the client, the hooks follow the `dev` option of `createInertiaApp()` shown in [Installation](#installation). These hooks expose the visit options and request grouping described above, so turning them off leaves the timeline recording requests without that client-side detail.

To disable the panel itself, toggle the extension off from your browser's extensions page, such as `chrome://extensions`.

## Redaction

Values under a sensitive key are replaced with `[REDACTED]` before anything is written to disk — in props, request and response bodies, and the query parameters of the request URL, the page URL, redirect locations, and URL headers such as `Referer`. Sensitive request and response headers are redacted too.

`devtools.redact_keys` match exactly and case-insensitively, so `api_key` is redacted but `stripe_api_key` is not. Extend the lists rather than replacing them if you only mean to add:

```ruby
InertiaRails.configure do |config|
  config.devtools.redact_keys += %w[stripe_api_key]
end
```

Request parameters and URL query parameters also honor your app's `config.filter_parameters`, with their standard Rails matching semantics, so what is filtered from your logs is filtered there too. Props and response bodies use only `devtools.redact_keys`: log filters match partially (`:email`, `:_key`) and would hide the values you came to inspect.

Redaction is key-based, so it needs a structure to walk. A body Rails has no parser for is parsed as JSON and redacted; if it isn't JSON, it is recorded as omitted rather than written out raw. That applies in both directions — an HTML page or a text blob could embed a CSRF token or a secret under no key we can match, so non-Inertia responses are only stored when they are JSON. Likewise, the request body of a non-Inertia `POST`, `PUT`, `PATCH`, or `DELETE`, such as a plain Rails form or an API call, is recorded as omitted.

A URL inside a prop or a body is stored as is, query string included. A token in a URL is not a secret anyway: browsers cache it, servers log it, and the `Referer` header passes it on.

## Storage

Entries are written to `tmp/inertia-devtools` as one JSON file each, in a directory per browser tab, before the response is sent: the extension reads each entry once, as soon as the response headers arrive. At most 100 entries are kept per tab — requests the extension has not tagged with a tab, such as the first page load on a host, form their own group under the same cap — and entries older than 24 hours are removed whenever a new tab starts recording. A write failure is reported once and suppresses recording for 30 seconds rather than retrying on every request.

Request bodies other than form data, and buffered non-Inertia response bodies, are recorded as omitted when over 256 KB. Inertia pages retain their complete page and prop payloads so the panel sees the same data as the client.

Recording never breaks a response: if anything in the recorder raises, the error is reported and the entry is dropped, so the extension finds nothing under that response's id.

## Configuration

Settings take plain values; only `authorize` is a callable. `enabled`, `storage_path`, `ttl`, and `limit` can also be set with the `INERTIA_DEVTOOLS_ENABLED`, `INERTIA_DEVTOOLS_STORAGE_PATH`, `INERTIA_DEVTOOLS_TTL`, and `INERTIA_DEVTOOLS_LIMIT` environment variables.

| Option                     | Default                                                        | Description                                                                                                                                     |
| -------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `devtools.enabled`         | `nil`                                                          | `nil` records in development only; `true` or `false` force it on or off.                                                                        |
| `devtools.except`          | `[]`                                                           | Request paths never recorded. Strings such as `admin/*` are matched with `File.fnmatch`; regexps work too.                                      |
| `devtools.storage_path`    | `tmp/inertia-devtools`                                         | Where entries are written, relative to the app root.                                                                                            |
| `devtools.ttl`             | `24`                                                           | Hours an entry is kept. Fractional values are allowed.                                                                                          |
| `devtools.limit`           | `100`                                                          | Entries kept per browser tab, and per the tab-less group. `0` disables the cap.                                                                 |
| `devtools.authorize`       | `nil`                                                          | Callable, run in your controllers, deciding whose requests are recorded and who may read them. Without one, DevTools works in development only. |
| `devtools.base_controller` | `'ActionController::API'`                                      | Controller the read API inherits. Set it to one that signs users in when you use `authorize`.                                                   |
| `devtools.redact_keys`     | passwords, tokens, secrets                                     | Prop, body, and query keys replaced with `[REDACTED]`.                                                                                          |
| `devtools.redact_headers`  | cookie, authorization, CSRF                                    | Header names replaced with `[REDACTED]`.                                                                                                        |
| `devtools.component_paths` | `app/frontend/pages`, `app/javascript/pages` (and capitalized) | Directories searched for the page file backing a component.                                                                                     |

---

---
url: /guide/error-handling.md
---
# Error Handling

## Development

One of the advantages to working with a robust server-side framework is the built-in exception handling you get for free.

The challenge is, if you're making an XHR request (which Inertia does) and you hit a server-side error, you're typically left digging through the network tab in your browser's devtools to diagnose the problem.

Inertia solves this issue by showing all non-Inertia responses in a modal. This means you get the same beautiful error-reporting you're accustomed to, even though you've made that request over XHR.

For applications using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) that restricts inline styles, you may pass a `nonce` to `createInertiaApp()` to permit the inline styles the error modal injects. See [Content Security Policy](/guide/client-side-setup#content-security-policy) for details.

## Dialog element

@available\_since core=2.2.13

By default, Inertia < 3.x displays error modals using a custom `<div>` overlay. However, you can opt-in to using the native HTML `<dialog>` element instead, which provides built-in modal functionality including backdrop handling.

To enable this, configure the `future.useDialogForErrorModal` option in your [application defaults](/guide/client-side-setup#configuring-defaults).

```js
createInertiaApp({
  // resolve, setup, etc.
  defaults: {
    future: {
      useDialogForErrorModal: true,
    },
  },
})
```

## Production

In production you will want to return a proper Inertia error response instead of relying on the modal-driven error reporting that is present during development. To accomplish this, use the `rescue_from` method in your `ApplicationController`.

```ruby
class ApplicationController < ActionController::Base
  rescue_from StandardError, with: :inertia_error_page

  private

  def inertia_error_page(exception)
    raise exception if Rails.env.local?

    status = ActionDispatch::ExceptionWrapper.new(nil, exception).status_code

    render inertia: 'ErrorPage', props: { status: }, status:
  end
end
```

Since `rescue_from` runs inside the controller, shared data defined via `inertia_share` is available automatically.

### Error Page Example

You'll need to create the error page components referenced above. Here's an example you may use as a starting point.

:::tabs key:frameworks

\== Vue

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

const props = defineProps({ status: Number })

const title = computed(() => {
  return {
    503: '503: Service Unavailable',
    500: '500: Server Error',
    404: '404: Page Not Found',
    403: '403: Forbidden',
  }[props.status]
})

const description = computed(() => {
  return {
    503: 'Sorry, we are doing some maintenance. Please check back soon.',
    500: 'Whoops, something went wrong on our servers.',
    404: 'Sorry, the page you are looking for could not be found.',
    403: 'Sorry, you are forbidden from accessing this page.',
  }[props.status]
})
</script>

<template>
  <div>
    <h1>{{ title ?? `${status}: Error` }}</h1>
    <div>{{ description ?? 'Sorry, something went wrong.' }}</div>
  </div>
</template>
```

\== React

```jsx
export default function ErrorPage({ status }) {
  const title = {
    503: '503: Service Unavailable',
    500: '500: Server Error',
    404: '404: Page Not Found',
    403: '403: Forbidden',
  }[status]

  const description = {
    503: 'Sorry, we are doing some maintenance. Please check back soon.',
    500: 'Whoops, something went wrong on our servers.',
    404: 'Sorry, the page you are looking for could not be found.',
    403: 'Sorry, you are forbidden from accessing this page.',
  }[status]

  return (
    <div>
      <h1>{title ?? `${status}: Error`}</h1>
      <div>{description ?? 'Sorry, something went wrong.'}</div>
    </div>
  )
}
```

\== Svelte

```svelte
<script>
  let { status } = $props()

  const title = {
    503: '503: Service Unavailable',
    500: '500: Server Error',
    404: '404: Page Not Found',
    403: '403: Forbidden',
  }

  const description = {
    503: 'Sorry, we are doing some maintenance. Please check back soon.',
    500: 'Whoops, something went wrong on our servers.',
    404: 'Sorry, the page you are looking for could not be found.',
    403: 'Sorry, you are forbidden from accessing this page.',
  }
</script>

<div>
  <h1>{title[status] ?? `${status}: Error`}</h1>
  <div>{description[status] ?? 'Sorry, something went wrong.'}</div>
</div>
```

:::

### Routing-level exceptions

Some exceptions (for example, routing 404s) occur before a controller is instantiated, so `rescue_from` won't catch them. Rails handles these via static files in `public/` by default, which is fine for most apps.

If you want routing-level errors to render as Inertia pages too, point `exceptions_app` at your router and add error routes.

```ruby
# config/application.rb
config.exceptions_app = routes
```

```ruby
# config/routes.rb
match '/404', to: 'errors#show', defaults: { status: 404 }, via: :all
match '/422', to: 'errors#show', defaults: { status: 422 }, via: :all
match '/500', to: 'errors#show', defaults: { status: 500 }, via: :all
```

```ruby
# app/controllers/errors_controller.rb
class ErrorsController < ApplicationController
  def show
    status = params[:status].to_i
    render inertia: 'ErrorPage', props: { status: }, status:
  end
end
```

Since this goes through the full Rails stack, shared data from `inertia_share` is available on error pages as well.

---

---
url: /guide/events.md
---
# Events

Inertia provides an event system that allows you to "hook into" the various lifecycle events of the library.

## Registering Listeners

To register an event listener, use the `router.on()` method.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

:::

Under the hood, Inertia uses native browser events, so you can also interact with Inertia events using the typical event methods you may already be familiar with - just be sure to prepend `inertia:` to the event name.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

document.addEventListener('inertia:start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

document.addEventListener('inertia:start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

document.addEventListener('inertia:start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

:::

## Removing Listeners

When you register an event listener, Inertia automatically returns a callback that can be invoked to remove the event listener.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

let removeStartEventListener = router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener...
removeStartEventListener()
```

\== React

```jsx
import { router } from '@inertiajs/react'

let removeStartEventListener = router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener...
removeStartEventListener()
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

let removeStartEventListener = router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener...
removeStartEventListener()
```

:::

Combined with hooks, you can automatically remove the event listener when components unmount.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { router } from '@inertiajs/vue3'
import { onUnmounted } from 'vue'

onUnmounted(
  router.on('start', (event) => {
    console.log(`Starting a visit to ${event.detail.visit.url}`)
  }),
)
</script>
```

\== React

```jsx
import { useEffect } from 'react'
import { router } from '@inertiajs/react'

useEffect(() => {
  return router.on('start', (event) => {
    console.log(`Starting a visit to ${event.detail.visit.url}`)
  })
}, [])
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

$effect(() => {
  return router.on('start', (event) => {
    console.log(`Starting a visit to ${event.detail.visit.url}`)
  })
})
```

:::

Alternatively, if you're using native browser events, you can remove the event listener using `removeEventListener()`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

let startEventListener = (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
}

document.addEventListener('inertia:start', startEventListener)

// Remove the listener...
document.removeEventListener('inertia:start', startEventListener)
```

\== React

```jsx
import { router } from '@inertiajs/react'

let startEventListener = (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
}

document.addEventListener('inertia:start', startEventListener)

// Remove the listener...
document.removeEventListener('inertia:start', startEventListener)
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

let startEventListener = (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
}

document.addEventListener('inertia:start', startEventListener)

// Remove the listener...
document.removeEventListener('inertia:start', startEventListener)
```

:::

## One-time Listeners

@available\_since core=3.2.0

You may register a listener that fires only once using the `router.once()` method. The listener is automatically removed after the first invocation.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

:::

Like `router.on()`, this method returns a callback you may invoke to remove the listener before it fires.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

let removeStartEventListener = router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener before it fires...
removeStartEventListener()
```

\== React

```jsx
import { router } from '@inertiajs/react'

let removeStartEventListener = router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener before it fires...
removeStartEventListener()
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

let removeStartEventListener = router.once('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener before it fires...
removeStartEventListener()
```

:::

## Cancelling Events

Some events, such as `before`, `networkError`, `httpException`, and `location`, support cancellation, allowing you to prevent Inertia's default behavior. Just like native events, the event will be cancelled if only one event listener calls `event.preventDefault()`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  if (!confirm('Are you sure you want to navigate away?')) {
    event.preventDefault()
  }
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('before', (event) => {
  if (!confirm('Are you sure you want to navigate away?')) {
    event.preventDefault()
  }
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('before', (event) => {
  if (!confirm('Are you sure you want to navigate away?')) {
    event.preventDefault()
  }
})
```

:::

For convenience, if you register your event listener using `router.on()`, you can cancel the event by returning `false` from the listener.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

:::

Note, browsers do not allow cancelling the native `popstate` event, so preventing forward and back history visits while using Inertia.js is not possible.

## Before

The `before` event fires when a request is about to be made to the server. This is useful for intercepting visits.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('before', (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('before', (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`)
})
```

:::

The primary purpose of this event is to allow you to prevent a visit from happening.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})
```

:::

## Start

The `start` event fires when a request to the server has started. This is useful for displaying loading indicators.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})
```

:::

The `start` event is not cancelable.

## Progress

The `progress` event fires as progress increments during file uploads.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('progress', (event) => {
  this.form.progress = event.detail.progress.percentage
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('progress', (event) => {
  this.form.progress = event.detail.progress.percentage
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('progress', (event) => {
  this.form.progress = event.detail.progress.percentage
})
```

:::

The `progress` event is not cancelable.

## Success

The `success` event fires on successful page visits, unless validation errors are present. However, this does *not* include history visits.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('success', (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('success', (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('success', (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`)
})
```

:::

The `success` event is not cancelable.

## Flash

@available\_since rails=3.16.0 core=2.3.3

The `flash` event fires when [flash data](/guide/flash-data) is received from the server. This is useful for displaying toast notifications or handling temporary data in a central location.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

:::

The `flash` event is not cancelable and fires on every response that carries flash data.

## Error

The `error` event fires when validation errors are present on "successful" page visits.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('error', (event) => {
  console.log(event.detail.errors)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('error', (event) => {
  console.log(event.detail.errors)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('error', (event) => {
  console.log(event.detail.errors)
})
```

:::

The `error` event is not cancelable.

## HTTP Exception

The `httpException` event (`invalid` in `@inertiajs/core` < 3.0) fires when a non-Inertia response is received from the server, such as an HTML or vanilla JSON response. A valid Inertia response is a response that has the `X-Inertia` header set to `true` with a `json` payload containing [the page object](/guide/the-protocol#the-page-object).

This event is fired for all response types, including `200`, `400`, and `500` response codes.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('httpException', (event) => {
  console.log(`An invalid Inertia response was received.`)
  console.log(event.detail.response)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('httpException', (event) => {
  console.log(`An invalid Inertia response was received.`)
  console.log(event.detail.response)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('httpException', (event) => {
  console.log(`An invalid Inertia response was received.`)
  console.log(event.detail.response)
})
```

:::

You may cancel the `httpException` event to prevent Inertia from showing the non-Inertia response modal.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('httpException', (event) => {
  event.preventDefault()

  // Handle the invalid response yourself...
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('httpException', (event) => {
  event.preventDefault()

  // Handle the invalid response yourself...
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('httpException', (event) => {
  event.preventDefault()

  // Handle the invalid response yourself...
})
```

:::

## Network Error

The `networkError` event (`error` in `@inertiajs/core` < 3.0) fires on unexpected XHR errors such as network interruptions. In addition, this event fires for errors generated when resolving page components.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('networkError', (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`)
  console.log(event.detail.error)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('networkError', (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`)
  console.log(event.detail.error)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('networkError', (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`)
  console.log(event.detail.error)
})
```

:::

You may cancel the `networkError` event to prevent the error from being thrown.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('networkError', (event) => {
  event.preventDefault()
  // Handle the error yourself
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('networkError', (event) => {
  event.preventDefault()
  // Handle the error yourself
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('networkError', (event) => {
  event.preventDefault()
  // Handle the error yourself
})
```

:::

This event will *not* fire for XHR requests that receive `400` and `500` level responses or for non-Inertia responses, as these situations are handled in other ways by Inertia. Please consult the [error handling documentation](/guide/error-handling) for more information.

## Finish

The `finish` event fires after an XHR request has completed for both "successful" and "unsuccessful" responses. This event is useful for hiding loading indicators.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('finish', (event) => {
  NProgress.done()
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('finish', (event) => {
  NProgress.done()
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('finish', (event) => {
  NProgress.done()
})
```

:::

The `finish` event is not cancelable.

## Navigate

The `navigate` event fires on successful page visits, as well as when navigating through history.

@available\_since core=3.9.0

The event detail includes a `type` value describing how the navigation happened: `initial` for the first page load, `visit` for Inertia visits, and `history` for back and forward navigation.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('navigate', (event) => {
  console.log(`Navigated to ${event.detail.page.url}`)
  console.log(`Navigation type: ${event.detail.type}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('navigate', (event) => {
  console.log(`Navigated to ${event.detail.page.url}`)
  console.log(`Navigation type: ${event.detail.type}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('navigate', (event) => {
  console.log(`Navigated to ${event.detail.page.url}`)
  console.log(`Navigation type: ${event.detail.type}`)
})
```

:::

The `navigate` event is not cancelable.

## Location

@available\_since core=3.6.0

The `location` event fires whenever Inertia is about to force a full page visit, either because the [asset version](/guide/asset-versioning) changed or because the server returned an [external redirect](/guide/redirects#external-redirects), such as `inertia_location`. The event detail includes a `versionChange` boolean so you may tell an automatic asset version change apart from a manual redirect.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('location', (event) => {
  console.log(`Navigating to ${event.detail.url}`)
  console.log(`Triggered by a version change: ${event.detail.versionChange}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('location', (event) => {
  console.log(`Navigating to ${event.detail.url}`)
  console.log(`Triggered by a version change: ${event.detail.versionChange}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('location', (event) => {
  console.log(`Navigating to ${event.detail.url}`)
  console.log(`Triggered by a version change: ${event.detail.versionChange}`)
})
```

:::

@available\_since rails=3.23.0

Inertia Rails sends the `X-Inertia-Version` header that `versionChange` relies on. With older versions of the gem, `versionChange` is always `false`.

You may cancel the `location` event to take over the navigation yourself, for example to show a "new version available" banner instead of reloading.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('location', (event) => {
  if (event.detail.versionChange) {
    event.preventDefault()
    showBanner('A new version is available.')
  }
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('location', (event) => {
  if (event.detail.versionChange) {
    event.preventDefault()
    showBanner('A new version is available.')
  }
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('location', (event) => {
  if (event.detail.versionChange) {
    event.preventDefault()
    showBanner('A new version is available.')
  }
})
```

:::

## Prefetching

The `prefetching` event fires when the router starts prefetching a page.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('prefetching', (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('prefetching', (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('prefetching', (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`)
})
```

:::

The `prefetching` event is not cancelable.

## Prefetched

The `prefetched` event fires when the router has successfully prefetched a page.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('prefetched', (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`)
})
```

\== React

```jsx
import { router } from '@inertiajs/react'

router.on('prefetched', (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`)
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('prefetched', (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`)
})
```

:::

The `prefetched` event is not cancelable.

## Event Callbacks

In addition to the global events described throughout this page, Inertia also provides a number of [event callbacks](/guide/manual-visits#event-callbacks) that fire when manually making Inertia visits.

---

---
url: /guide/file-uploads.md
---
# File Uploads

## `FormData` Conversion

When making Inertia requests that include files (even nested files), Inertia will automatically convert the request data into a `FormData` object. This conversion is necessary in order to submit a `multipart/form-data` request via XHR.

If you would like the request to always use a `FormData` object regardless of whether a file is present in the data, you may provide the `forceFormData` option when making the request.

:::tabs key:frameworks
\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  forceFormData: true,
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  forceFormData: true,
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  forceFormData: true,
})
```

:::

You can learn more about the `FormData` interface via its [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/FormData).

## File Upload Example

Let's examine a complete file upload example using Inertia. This example includes both a `name` text input and an `avatar` file input.

:::tabs key:frameworks
\== Vue

```vue
<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm({
  name: null,
  avatar: null,
})

function submit() {
  form.post('/users')
}
</script>

<template>
  <form @submit.prevent="submit">
    <input type="text" v-model="form.name" />
    <input type="file" @input="form.avatar = $event.target.files[0]" />
    <progress v-if="form.progress" :value="form.progress.percentage" max="100">
      {{ form.progress.percentage }}%
    </progress>
    <button type="submit">Submit</button>
  </form>
</template>
```

\== React

```jsx
import { useForm } from '@inertiajs/react'

const { data, setData, post, progress } = useForm({
  name: null,
  avatar: null,
})

function submit(e) {
  e.preventDefault()
  post('/users')
}

return (
  <form onSubmit={submit}>
    <input
      type="text"
      value={data.name}
      onChange={(e) => setData('name', e.target.value)}
    />
    <input type="file" onChange={(e) => setData('avatar', e.target.files[0])} />
    {progress && (
      <progress value={progress.percentage} max="100">
        {progress.percentage}%
      </progress>
    )}
    <button type="submit">Submit</button>
  </form>
)
```

\== Svelte

```svelte
<script>
  import { useForm } from '@inertiajs/svelte'

  const form = useForm({
    name: null,
    avatar: null,
  })

  function submit(e) {
    e.preventDefault()
    form.post('/users')
  }
</script>

<form onsubmit={submit}>
  <input type="text" bind:value={form.name} />
  <input type="file" oninput={(e) => (form.avatar = e.target.files[0])} />
  {#if form.progress}
    <progress value={form.progress.percentage} max="100">
      {form.progress.percentage}%
    </progress>
  {/if}
  <button type="submit">Submit</button>
</form>
```

:::

This example uses the [Inertia form helper](/guide/forms#form-helper) for convenience, since the form helper provides easy access to the current upload progress. However, you are free to submit your forms using [manual Inertia visits](/guide/manual-visits) as well.

## Multipart Limitations

Some server-side frameworks, such as Laravel, can't read `multipart/form-data` requests sent with the `PUT`, `PATCH`, or `DELETE` HTTP methods, and have to upload files with `POST` instead. Rails has no such limitation, so you can upload files with any method:

:::tabs key:frameworks
\== Vue

```js
import { router } from '@inertiajs/vue3'

router.patch(`/users/${user.id}`, {
  avatar: form.avatar,
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.patch(`/users/${user.id}`, {
  avatar: form.avatar,
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.patch(`/users/${user.id}`, {
  avatar: form.avatar,
})
```

:::

If you still need to send a `POST` request that Rails handles as `PUT` or `PATCH`, use the `X-HTTP-Method-Override` header. A `_method` attribute in the data only works in form and multipart requests: Inertia sends JSON when the data contains no files, and [`Rack::MethodOverride`](https://github.com/rack/rack/blob/main/lib/rack/method_override.rb) ignores `_method` in JSON.

---

---
url: /guide/flash-data.md
---
# Flash Data

@available\_since rails=3.16.0 core=2.3.3

Flash data lets you send one-time data to your frontend that won't reappear when users navigate through browser history. Unlike regular props, flash data isn't persisted in history state, making it ideal for success messages, newly created IDs, or other temporary values.

## Flashing Data

Inertia automatically integrates with Rails' standard flash mechanism. Common flash keys like `notice` and `alert` are included in page-level flash data by default.

```ruby
class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      redirect_to users_url, notice: 'User created successfully!'
    else
      redirect_to new_user_url, inertia: { errors: user.errors }
    end
  end
end
```

This works with any Rails flash pattern:

```ruby
flash[:notice] = 'Success!'
flash[:alert] = 'Something went wrong'
redirect_to users_url
```

By default, the following keys are exposed to the frontend: `notice`, `alert`.

## Custom Flash Data

For custom data beyond the default allowlisted keys, use `flash.inertia`:

```ruby
class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      flash.inertia[:new_user_id] = user.id
      flash.inertia[:toast] = { message: 'Created!', type: 'success' }

      redirect_to users_url
    else
      redirect_to new_user_url, inertia: { errors: user.errors }
    end
  end
end
```

This follows standard Rails flash patterns - `flash.inertia` is a scoped namespace within flash.

You can also pass flash data inline with `redirect_to`:

```ruby
redirect_to users_url, flash: { inertia: { new_user_id: user.id } }
```

For current-request-only flash (not persisted across redirects), use `.now`:

```ruby
flash.now.inertia[:temporary] = 'This request only'
render inertia: 'MyComponent'
```

Flash data is scoped to the current request. Rails automatically persists it when redirecting. After the flash data is sent to the client, it is cleared and will not appear in subsequent requests.

## Configuring Allowed Flash Keys

You may customize which Rails flash keys are exposed to the frontend:

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  # Default: Only safe keys
  config.flash_keys = %i[notice alert]
end
```

## Accessing Flash Data

Flash data is available on `page.flash`. You may also listen for the global `flash` event or use the `onFlash` callback.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { usePage } from '@inertiajs/vue3'

const page = usePage()
</script>

<template>
  <div v-if="page.flash.toast" class="toast">
    {{ page.flash.toast.message }}
  </div>
</template>
```

\== React

```jsx
import { usePage } from '@inertiajs/react'

export default function Layout({ children }) {
  const { flash } = usePage()

  return (
    <>
      {flash.toast && <div className="toast">{flash.toast.message}</div>}
      {children}
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { page } from '@inertiajs/svelte'
</script>

{#if page.flash.toast}
  <div class="toast">{page.flash.toast.message}</div>
{/if}
```

:::

## The `onFlash` Callback

You may use the `onFlash` callback to handle flash data when making requests.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  onFlash: ({ newUserId }) => {
    form.userId = newUserId
  },
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  onFlash: ({ newUserId }) => {
    form.userId = newUserId
  },
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  onFlash: ({ newUserId }) => {
    form.userId = newUserId
  },
})
```

:::

## Global Flash Event

You may use the global `flash` event to handle flash data in a central location, such as a layout component. For more information on events, see the [events documentation](/guide/events).

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('flash', (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast)
  }
})
```

:::

> \[!WARNING]
> Event listeners registered inside components should be cleaned up when the
> component unmounts to prevent them from accumulating and firing multiple
> times. This is especially important in non-persistent layouts. See [removing
> event listeners](/guide/events#removing-listeners) for more information.

Native browser events are also supported.

:::tabs key:frameworks

\== Vue

```js
document.addEventListener('inertia:flash', (event) => {
  console.log(event.detail.flash)
})
```

\== React

```js
document.addEventListener('inertia:flash', (event) => {
  console.log(event.detail.flash)
})
```

\== Svelte

```js
document.addEventListener('inertia:flash', (event) => {
  console.log(event.detail.flash)
})
```

:::

The `flash` event is not cancelable and fires on every response that carries flash data.

## Client-Side Flash

You may set flash data on the client without a server request using the `router.flash()` method. Values are merged with existing flash data.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.flash('foo', 'bar')
router.flash({ foo: 'bar' })
```

\== React

```js
import { router } from '@inertiajs/react'

router.flash('foo', 'bar')
router.flash({ foo: 'bar' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.flash('foo', 'bar')
router.flash({ foo: 'bar' })
```

:::

A callback may also be passed to access the current flash data or replace it entirely.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.flash((current) => ({ ...current, bar: 'baz' }))
router.flash(() => ({}))
```

\== React

```js
import { router } from '@inertiajs/react'

router.flash((current) => ({ ...current, bar: 'baz' }))
router.flash(() => ({}))
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.flash((current) => ({ ...current, bar: 'baz' }))
router.flash(() => ({}))
```

:::

## TypeScript

You may configure the flash data type globally using [TypeScript's declaration merging](/guide/typescript#flash-data).

## Testing

For information on testing flash data, see the [testing documentation](/guide/testing#test-flash-messages).

---

---
url: /guide/forms.md
---
# Forms

Inertia provides two primary ways to build forms: the `<Form>` component and the `useForm` helper. Both integrate with your server-side framework's validation and handle form submissions without full page reloads.

## Form Component

@available\_since core=2.1.0

Inertia provides a `<Form>` component that behaves much like a classic HTML form, but uses Inertia under the hood to avoid full page reloads. This is the simplest way to get started with forms in Inertia.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Form } from '@inertiajs/vue3'
</script>

<template>
  <Form action="/users" method="post">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
  </Form>
</template>
```

\== React

```jsx
import { Form } from '@inertiajs/react'

export default () => (
  <Form action="/users" method="post">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
  </Form>
)
```

\== Svelte

```svelte
<script>
  import { Form } from '@inertiajs/svelte'
</script>

<Form action="/users" method="post">
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Create User</button>
</Form>
```

:::

Just like a traditional HTML form, there is no need to attach `v-model`an `onChange` handler`bind:` to your input fields, just give each input a `name` attribute and a `defaultValue` (if applicable) and the `Form` component will handle the data submission for you.

The component also supports nested data structures, file uploads, and dotted key notation.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/reports" method="post">
    <input type="text" name="name" />
    <textarea name="report[description]"></textarea>
    <input type="text" name="report[tags][]" />
    <input type="file" name="documents" multiple />
    <button type="submit">Create Report</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/reports" method="post">
  <input type="text" name="name" />
  <textarea name="report[description]"></textarea>
  <input type="text" name="report[tags][]" />
  <input type="file" name="documents" multiple />
  <button type="submit">Create Report</button>
</Form>
```

\== Svelte

```svelte
<Form action="/reports" method="post">
  <input type="text" name="name" />
  <textarea name="report[description]"></textarea>
  <input type="text" name="report[tags][]" />
  <input type="file" name="documents" multiple />
  <button type="submit">Create Report</button>
</Form>
```

:::

You can pass a `transform` prop to modify the form data before submission. This is useful for injecting additional fields or transforming existing data, although hidden inputs work too.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/posts"
    method="post"
    :transform="(data) => ({ ...data, user_id: 123 })"
  >
    <input type="text" name="title" />
    <button type="submit">Create Post</button>
  </Form>
</template>
```

\== React

```jsx
<Form
  action="/posts"
  method="post"
  transform={(data) => ({ ...data, user_id: 123 })}
>
  <input type="text" name="title" />
  <button type="submit">Create Post</button>
</Form>
```

\== Svelte

```svelte
<Form
  action="/posts"
  method="post"
  transform={(data) => ({ ...data, user_id: 123 })}
>
  <input type="text" name="title" />
  <button type="submit">Create Post</button>
</Form>
```

:::

### Default Values

You can set default values for form inputs using standard HTML attributes. Use `defaultValue``defaultValue``defaultValue` (`value` for Svelte < `5.6.0`) for text inputs and textareas, and `defaultChecked``defaultChecked``defaultChecked` (`checked` for Svelte < `5.6.0`) for checkboxes and radios.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post">
    <input type="text" name="name" defaultValue="John Doe" />

    <select name="country">
      <option value="us">United States</option>
      <option value="ca">Canada</option>
      <option value="uk" selected>United Kingdom</option>
    </select>

    <input type="checkbox" name="subscribe" value="yes" defaultChecked />

    <button type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  <input type="text" name="name" defaultValue="John Doe" />

  <select name="country" defaultValue="uk">
    <option value="us">United States</option>
    <option value="ca">Canada</option>
    <option value="uk">United Kingdom</option>
  </select>

  <input type="checkbox" name="subscribe" value="yes" defaultChecked />

  <button type="submit">Submit</button>
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  <input type="text" name="name" value="John Doe" />

  <select name="country" value="uk">
    <option value="us">United States</option>
    <option value="ca">Canada</option>
    <option value="uk">United Kingdom</option>
  </select>

  <input type="checkbox" name="subscribe" value="yes" checked />

  <button type="submit">Submit</button>
</Form>
```

:::

### Checkbox Inputs

When working with checkboxes, you may want to add an explicit `value` attribute such as `value="1"`. Without a value attribute, checked checkboxes will submit as `"on"`, which some server-side validation rules may not recognize as a proper boolean value.

### Slot Props

The `<Form>` component exposes reactive state and helper methods through its default slot, giving you access to form processing state, errors, and utility functions.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/users"
    method="post"
    #default="{
      errors,
      hasErrors,
      processing,
      progress,
      wasSuccessful,
      recentlySuccessful,
      setError,
      clearErrors,
      resetAndClearErrors,
      defaults,
      isDirty,
      reset,
      submit,
      cancel,
    }"
  >
    <input type="text" name="name" />

    <div v-if="errors.name">
      {{ errors.name }}
    </div>

    <button type="submit" :disabled="processing">
      {{ processing ? 'Creating...' : 'Create User' }}
    </button>

    <div v-if="wasSuccessful">User created successfully!</div>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({
    errors,
    hasErrors,
    processing,
    progress,
    wasSuccessful,
    recentlySuccessful,
    setError,
    clearErrors,
    resetAndClearErrors,
    defaults,
    isDirty,
    reset,
    submit,
    cancel,
  }) => (
    <>
      <input type="text" name="name" />

      {errors.name && <div>{errors.name}</div>}

      <button type="submit" disabled={processing}>
        {processing ? 'Creating...' : 'Create User'}
      </button>

      {wasSuccessful && <div>User created successfully!</div>}
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({
    errors,
    hasErrors,
    processing,
    progress,
    wasSuccessful,
    recentlySuccessful,
    setError,
    clearErrors,
    resetAndClearErrors,
    defaults,
    isDirty,
    reset,
    submit,
    cancel,
  })}
    <input type="text" name="name" />

    {#if errors.name}
      <div>{errors.name}</div>
    {/if}

    <button type="submit" disabled={processing}>
      {processing ? 'Creating...' : 'Create User'}
    </button>

    {#if wasSuccessful}
      <div>User created successfully!</div>
    {/if}
  {/snippet}
</Form>
```

:::

#### `defaults` method

@available\_since core=2.1.1

The `defaults` method allows you to update the form's default values to match the current field values. When called, subsequent `reset()` calls will restore fields to these new defaults, and the `isDirty` property will track changes from these updated defaults. Unlike `useForm`, this method accepts no arguments and always uses all current form values.

#### `errors` object

The `errors` object uses dotted notation for nested fields, allowing you to display validation messages for complex form structures.

:::tabs key:frameworks

\== Vue

```vue
<Form action="/users" method="post" #default="{ errors }">
    <input type="text" name="user.name" />
    <div v-if="errors['user.name']">{{ errors['user.name'] }}</div>
</Form>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ errors }) => (
    <>
      <input type="text" name="user.name" />
      {errors['user.name'] && <div>{errors['user.name']}</div>}
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ errors })}
    <input type="text" name="user.name" />
    {#if errors['user.name']}
      <div>{errors['user.name']}</div>
    {/if}
  {/snippet}
</Form>
```

:::

### Props and Options

In addition to `action` and `method`, the `<Form>` component accepts several props. Many of them are identical to the options available in Inertia's [visit options](/guide/manual-visits).

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/profile"
    method="put"
    error-bag="profile"
    query-string-array-format="indices"
    :headers="{ 'X-Custom-Header': 'value' }"
    :show-progress="false"
    :transform="(data) => ({ ...data, timestamp: Date.now() })"
    :optimistic="(props, data) => ({ ...props })"
    :invalidate-cache-tags="['users', 'dashboard']"
    disable-while-processing
    cancel-on-unmount
    :options="{
      preserveScroll: true,
      preserveState: true,
      preserveUrl: true,
      replace: true,
      only: ['users', 'flash'],
      except: ['secret'],
      reset: ['page'],
    }"
  >
    <input type="text" name="name" />
    <button type="submit">Update</button>
  </Form>
</template>
```

\== React

```jsx
<Form
  action="/profile"
  method="put"
  errorBag="profile"
  queryStringArrayFormat="indices"
  headers={{ 'X-Custom-Header': 'value' }}
  showProgress={false}
  transform={(data) => ({ ...data, timestamp: Date.now() })}
  optimistic={(props, data) => ({ ...props })}
  invalidateCacheTags={['users', 'dashboard']}
  disableWhileProcessing
  cancelOnUnmount
  options={{
    preserveScroll: true,
    preserveState: true,
    preserveUrl: true,
    replace: true,
    only: ['users', 'flash'],
    except: ['secret'],
    reset: ['page'],
  }}
>
  <input type="text" name="name" />
  <button type="submit">Update</button>
</Form>
```

\== Svelte

```svelte
<Form
  action="/profile"
  method="put"
  errorBag="profile"
  queryStringArrayFormat="indices"
  headers={{ 'X-Custom-Header': 'value' }}
  showProgress={false}
  transform={(data) => ({ ...data, timestamp: Date.now() })}
  optimistic={(props, data) => ({ ...props })}
  invalidateCacheTags={['users', 'dashboard']}
  disableWhileProcessing
  cancelOnUnmount
  options={{
    preserveScroll: true,
    preserveState: true,
    preserveUrl: true,
    replace: true,
    only: ['users', 'flash'],
    except: ['secret'],
    reset: ['page'],
  }}
>
  <input type="text" name="name" />
  <button type="submit">Update</button>
</Form>
```

:::

Some props are intentionally grouped under `options` instead of being top-level to avoid confusion. For example, `only`, `except`, and `reset` relate to *partial reloads*, not *partial submissions*. The general rule: top-level props are for the form submission itself, while `options` control how Inertia handles the subsequent visit.

When setting the `disableWhileProcessing``disableWhileProcessing``disable-while-processing` prop, the `Form` component will add the `inert` attribute to the HTML `form` tag while the form is processing to prevent user interaction.

To style the form while it's processing, you can target the inert form in the following ways.

:::tabs key:css

\== Tailwind 4

```jsx
<Form
  action="/profile"
  method="put"
  disableWhileProcessing
  className="inert:pointer-events-none inert:opacity-50"
>
  {/* Your form fields here */}
</Form>
```

\== CSS

```css
form[inert] {
  opacity: 0.5;
  pointer-events: none;
}
```

:::

### Events

The `<Form>` component emits all the standard visit [events](/guide/events) for form submissions.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/users"
    method="post"
    @before="handleBefore"
    @start="handleStart"
    @progress="handleProgress"
    @success="handleSuccess"
    @error="handleError"
    @finish="handleFinish"
    @cancel="handleCancel"
    @cancelToken="handleCancelToken"
  >
    <input type="text" name="name" />
    <button type="submit">Create User</button>
  </Form>
</template>
```

\== React

```jsx
<Form
  action="/users"
  method="post"
  onCancelToken={handleCancelToken}
  onBefore={handleBefore}
  onStart={handleStart}
  onProgress={handleProgress}
  onCancel={handleCancel}
  onSuccess={handleSuccess}
  onError={handleError}
  onFinish={handleFinish}
>
  <input type="text" name="name" />
  <button type="submit">Create User</button>
</Form>
```

\== Svelte

```svelte
<Form
  action="/users"
  method="post"
  onCancelToken={handleCancelToken}
  onBefore={handleBefore}
  onStart={handleStart}
  onProgress={handleProgress}
  onCancel={handleCancel}
  onSuccess={handleSuccess}
  onError={handleError}
  onFinish={handleFinish}
>
  <input type="text" name="name" />
  <button type="submit">Create User</button>
</Form>
```

:::

### Resetting the Form

@available\_since core=2.1.2

The `Form` component provides several attributes that allow you to reset the form after a submission.

`resetOnSuccess` may be used to reset the form after a successful submission.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <!-- Reset the entire form on success -->
  <Form action="/users" method="post" resetOnSuccess>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Submit</button>
  </Form>

  <!-- Reset specific fields on success -->
  <Form action="/users" method="post" :resetOnSuccess="['name']">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
// Reset the entire form on success
<Form action="/users" method="post" resetOnSuccess>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>

// Reset specific fields on success
<Form action="/users" method="post" resetOnSuccess={['name']}>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

\== Svelte

```svelte
<!-- Reset the entire form on success -->
<Form action="/users" method="post" resetOnSuccess>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>

<!-- Reset specific fields on success -->
<Form action="/users" method="post" resetOnSuccess={['name']}>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

:::

`resetOnError` may be used to reset the form after errors.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <!-- Reset the entire form on success -->
  <Form action="/users" method="post" resetOnError>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Submit</button>
  </Form>

  <!-- Reset specific fields on success -->
  <Form action="/users" method="post" :resetOnError="['name']">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
// Reset the entire form on success
<Form action="/users" method="post" resetOnError>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>

// Reset specific fields on success
<Form action="/users" method="post" resetOnError={['name']}>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

\== Svelte

```svelte
<!-- Reset the entire form on success -->
<Form action="/users" method="post" resetOnError>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>

<!-- Reset specific fields on success -->
<Form action="/users" method="post" resetOnError={['name']}>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

:::

### Setting New Default Values

@available\_since core=2.1.2

The `Form` component provides the `setDefaultsOnSuccess` attribute to set the current form values as the new defaults after a successful submission.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post" setDefaultsOnSuccess>
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post" setDefaultsOnSuccess>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post" setDefaultsOnSuccess>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Submit</button>
</Form>
```

:::

### Canceling Form Submissions

@available\_since core=3.7.0

The `cancel` method aborts an in-flight submission. It's available through the [slot props](#slot-props), the [component ref](#programmatic-access), and the [form context](#form-context).

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post" #default="{ processing, cancel }">
    <input type="text" name="name" />

    <button v-if="processing" type="button" @click="cancel">Cancel</button>
    <button v-else type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ processing, cancel }) => (
    <>
      <input type="text" name="name" />

      {processing ? (
        <button type="button" onClick={cancel}>
          Cancel
        </button>
      ) : (
        <button type="submit">Submit</button>
      )}
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ processing, cancel })}
    <input type="text" name="name" />

    {#if processing}
      <button type="button" onclick={cancel}>Cancel</button>
    {:else}
      <button type="submit">Submit</button>
    {/if}
  {/snippet}
</Form>
```

:::

Submissions continue running when the form that started them is removed from the page. Navigating away cancels the submission, but closing a modal that contains the form does not, so an abandoned upload still completes. You may use the `cancelOnUnmount``cancelOnUnmount``cancel-on-unmount` attribute to cancel an in-flight submission as soon as the form unmounts.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/avatar" method="post" cancel-on-unmount>
    <input type="file" name="avatar" />
    <button type="submit">Upload</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/avatar" method="post" cancelOnUnmount>
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</Form>
```

\== Svelte

```svelte
<Form action="/avatar" method="post" cancelOnUnmount>
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</Form>
```

:::

### Dotted Key Notation

The `<Form>` component supports dotted key notation for creating nested objects from flat input names. This provides a convenient way to structure form data.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post">
    <input type="text" name="user.name" />
    <input type="text" name="user.skills[]" />
    <input type="text" name="address.street" />
    <button type="submit">Submit</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  <input type="text" name="user.name" />
  <input type="text" name="user.skills[]" />
  <input type="text" name="address.street" />
  <button type="submit">Submit</button>
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  <input type="text" name="user.name" />
  <input type="text" name="user.skills[]" />
  <input type="text" name="address.street" />
  <button type="submit">Submit</button>
</Form>
```

:::

The example above would generate the following data structure.

```json
{
  "user": {
    "name": "John Doe",
    "skills": ["JavaScript"]
  },
  "address": {
    "street": "123 Main St"
  }
}
```

If you need literal dots in your field names (not as nested object separators), you can escape them using backslashes.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/config" method="post">
    <input type="text" name="app\.name" />
    <input type="text" name="settings.theme\.mode" />
    <button type="submit">Save</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/config" method="post">
  <input type="text" name="app\.name" />
  <input type="text" name="settings.theme\.mode" />
  <button type="submit">Save</button>
</Form>
```

\== Svelte

```svelte
<Form action="/config" method="post">
  <input type="text" name="app\.name" />
  <input type="text" name="settings.theme\.mode" />
  <button type="submit">Save</button>
</Form>
```

:::

The example above would generate the following data structure.

```json
{
  "app.name": "My Application",
  "settings": {
    "theme.mode": "dark"
  }
}
```

### Programmatic Access

You can access the form's methods programmatically using refs. This provides an alternative to [slot props](#slot-props) when you need to trigger form actions from outside the form.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { ref } from 'vue'
import { Form } from '@inertiajs/vue3'

const formRef = ref()

const handleSubmit = () => {
  formRef.value.submit()
}
</script>

<template>
  <Form ref="formRef" action="/users" method="post">
    <input type="text" name="name" />
    <button type="submit">Submit</button>
  </Form>

  <button @click="handleSubmit">Submit Programmatically</button>
</template>
```

\== React

```jsx
import { useRef } from 'react'
import { Form } from '@inertiajs/react'

export default function CreateUser() {
  const formRef = useRef()

  const handleSubmit = () => {
    formRef.current.submit()
  }

  return (
    <>
      <Form ref={formRef} action="/users" method="post">
        <input type="text" name="name" />
        <button type="submit">Submit</button>
      </Form>

      <button onClick={handleSubmit}>Submit Programmatically</button>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { Form } from '@inertiajs/svelte'

  let formRef

  function handleSubmit() {
    formRef.submit()
  }
</script>

<Form bind:this={formRef} action="/users" method="post">
  <input type="text" name="name" />
  <button type="submit">Submit</button>
</Form>

<button onclick={handleSubmit}>Submit Programmatically</button>
```

:::

In React and Vue, refs provide access to all form methods and reactive state. In Svelte, refs expose only methods, so reactive state like `isDirty` and `errors` should be accessed via [slot props](#slot-props) instead.

### Form Context

@available\_since core=2.3.9

Deeply nested child components may need access to form state or methods without passing props through multiple levels. The `useFormContext` hook provides access to the parent `<Form>` component's state and methods from any child component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useFormContext } from '@inertiajs/vue3'

const form = useFormContext()
</script>

<template>
  <div v-if="form">
    <span v-if="form.isDirty">Unsaved changes</span>
    <span v-if="form.errors.name">{{ form.errors.name }}</span>
    <button type="button" @click="form.submit()">Submit</button>
    <button type="button" @click="form.reset()">Reset</button>
  </div>
</template>
```

\== React

```jsx
import { useFormContext } from '@inertiajs/react'

export default function FormActions() {
  const form = useFormContext()

  if (!form) {
    return null
  }

  return (
    <div>
      {form.isDirty && <span>Unsaved changes</span>}
      {form.errors.name && <span>{form.errors.name}</span>}
      <button type="button" onClick={() => form.submit()}>
        Submit
      </button>
      <button type="button" onClick={() => form.reset()}>
        Reset
      </button>
    </div>
  )
}
```

\== Svelte

```svelte
<script>
  import { useFormContext } from '@inertiajs/svelte'

  const form = useFormContext()
</script>

{#if form}
  {#if form.isDirty}<span>Unsaved changes</span>{/if}
  {#if form.errors.name}<span>{form.errors.name}</span>{/if}
  <button type="button" onclick={() => form.submit()}>Submit</button>
  <button type="button" onclick={() => form.reset()}>Reset</button>
{/if}
```

:::

The context provides access to all the same properties and methods available through [slot props](#slot-props).

> \[!NOTE]
> Both the `<Form>` component and `useFormContext` accept generic type parameters for type-safe errors and slot props. See the [TypeScript](/guide/typescript#form-component) documentation for details.

### Precognition

@available\_since core=2.3.0

The `<Form>` component includes built-in support for Precognition, enabling real-time form validation without duplicating your server-side validation rules on the client.

> \[!NOTE]
> Precognition requires server-side support. See the [Precognition guide](/guide/precognition) for Rails setup instructions.

Once your server is configured, call `validate()` with a field name to trigger validation for that field. The `invalid()` helper checks if a field has validation errors, while `validating` indicates when a request is in progress.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/users"
    method="post"
    #default="{ errors, invalid, validate, validating }"
  >
    <label for="name">Name:</label>
    <input id="name" name="name" @change="validate('name')" />
    <p v-if="invalid('name')">{{ errors.name }}</p>

    <label for="email">Email:</label>
    <input id="email" name="email" @change="validate('email')" />
    <p v-if="invalid('email')">{{ errors.email }}</p>

    <p v-if="validating">Validating...</p>

    <button type="submit">Create User</button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ errors, invalid, validate, validating }) => (
    <>
      <label htmlFor="name">Name:</label>
      <input id="name" name="name" onChange={() => validate('name')} />
      {invalid('name') && <p>{errors.name}</p>}

      <label htmlFor="email">Email:</label>
      <input id="email" name="email" onChange={() => validate('email')} />
      {invalid('email') && <p>{errors.email}</p>}

      {validating && <p>Validating...</p>}

      <button type="submit">Create User</button>
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ errors, invalid, validate, validating })}
    <label for="name">Name:</label>
    <input id="name" name="name" onchange={() => validate('name')} />
    {#if invalid('name')}
      <p>{errors.name}</p>
    {/if}

    <label for="email">Email:</label>
    <input id="email" name="email" onchange={() => validate('email')} />
    {#if invalid('email')}
      <p>{errors.email}</p>
    {/if}

    {#if validating}
      <p>Validating...</p>
    {/if}

    <button type="submit">Create User</button>
  {/snippet}
</Form>
```

:::

You may also use the `valid()` helper to check if a field has passed validation.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/users"
    method="post"
    #default="{ errors, invalid, valid, validate }"
  >
    <input name="email" @change="validate('email')" />
    <p v-if="valid('email')">Valid email address</p>
    <p v-if="invalid('email')">{{ errors.email }}</p>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ errors, invalid, valid, validate }) => (
    <>
      <input name="email" onChange={() => validate('email')} />
      {valid('email') && <p>Valid email address</p>}
      {invalid('email') && <p>{errors.email}</p>}
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ errors, invalid, valid, validate })}
    <input name="email" onchange={() => validate('email')} />
    {#if valid('email')}
      <p>Valid email address</p>
    {/if}
    {#if invalid('email')}
      <p>{errors.email}</p>
    {/if}
  {/snippet}
</Form>
```

:::

> \[!WARNING]
> A form input will only appear as valid or invalid once it has changed and a
> validation response has been received. Calling `validate('field')` will not send a validation request until the field's value differs from the initial data.

#### Validating Multiple Fields

You may validate multiple fields at once using the `only` option. This is particularly useful when building wizard-style forms where you want to validate all visible fields before proceeding to the next step.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post" #default="{ validate }">
    <!-- Step 1 fields -->
    <input name="name" />
    <input name="email" />

    <button
      type="button"
      @click="
        validate({
          only: ['name', 'email'],
          onSuccess: () => goToNextStep(),
          onValidationError: () => showErrors(),
        })
      "
    >
      Next Step
    </button>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ validate }) => (
    <>
      {/* Step 1 fields */}
      <input name="name" />
      <input name="email" />

      <button
        type="button"
        onClick={() =>
          validate({
            only: ['name', 'email'],
            onSuccess: () => goToNextStep(),
            onValidationError: () => showErrors(),
          })
        }
      >
        Next Step
      </button>
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ validate })}
    <!-- Step 1 fields -->
    <input name="name" />
    <input name="email" />

    <button
      type="button"
      onclick={() =>
        validate({
          only: ['name', 'email'],
          onSuccess: () => goToNextStep(),
          onValidationError: () => showErrors(),
        })}
    >
      Next Step
    </button>
  {/snippet}
</Form>
```

:::

#### Touch and Validate

The `touch()` method marks fields as "touched" without triggering validation. You may then validate all touched fields by calling `validate()` without arguments.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form action="/users" method="post" #default="{ validate, touch, touched }">
    <input name="name" @blur="touch('name')" />
    <input name="email" @blur="touch('email')" />
    <input name="phone" @blur="touch('phone')" />

    <button type="button" @click="validate()">Validate Touched Fields</button>

    <p v-if="touched('name')">Name has been touched</p>
  </Form>
</template>
```

\== React

```jsx
<Form action="/users" method="post">
  {({ validate, touch, touched }) => (
    <>
      <input name="name" onBlur={() => touch('name')} />
      <input name="email" onBlur={() => touch('email')} />
      <input name="phone" onBlur={() => touch('phone')} />

      <button type="button" onClick={() => validate()}>
        Validate Touched Fields
      </button>

      {touched('name') && <p>Name has been touched</p>}
    </>
  )}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post">
  {#snippet children({ validate, touch, touched })}
    <input name="name" onblur={() => touch('name')} />
    <input name="email" onblur={() => touch('email')} />
    <input name="phone" onblur={() => touch('phone')} />

    <button type="button" onclick={() => validate()}
      >Validate Touched Fields</button
    >

    {#if touched('name')}
      <p>Name has been touched</p>
    {/if}
  {/snippet}
</Form>
```

:::

The `touched()` helper may also be called without arguments to check if any field has been touched. The `reset()` method clears the touched state for reset fields.

#### Options

The `validate()` method accepts an options object with callbacks and configuration.

```js
validate('username', {
  onSuccess: () => {
    // Validation passed...
  },
  onValidationError: (response) => {
    // Validation failed (422 response)...
  },
  onBeforeValidation: (newRequest, oldRequest) => {
    // Return false to prevent validation...
  },
  onFinish: () => {
    // Always runs after validation...
  },
})
```

You may also call `validate()` with only an options object to validate specific fields.

```js
validate({
  only: ['name', 'email'],
  onSuccess: () => goToNextStep(),
})
```

Validation requests are automatically debounced. The first request fires immediately, then subsequent changes are debounced (1500ms by default). You may customize this timeout.

:::tabs key:frameworks

\== Vue

```vue
<Form action="/users" method="post" :validation-timeout="500">
  <!-- ... -->
</Form>
```

\== React

```jsx
<Form action="/users" method="post" validationTimeout={500}>
  {/* ... */}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post" validationTimeout={500}>
  <!-- ... -->
</Form>
```

:::

By default, files are excluded from validation requests to avoid unnecessary uploads. You may enable file validation when you need to validate file inputs like size or mime type.

:::tabs key:frameworks

\== Vue

```vue
<Form action="/users" method="post" validate-files>
  <!-- ... -->
</Form>
```

\== React

```jsx
<Form action="/users" method="post" validateFiles>
  {/* ... */}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post" validateFiles>
  <!-- ... -->
</Form>
```

:::

By default, validation errors are simplified to strings (the first error message). You may keep errors as arrays to display all error messages for fields with multiple validation rules.

:::tabs key:frameworks

\== Vue

```vue
<Form action="/users" method="post" with-all-errors>
  <!-- ... -->
</Form>
```

\== React

```jsx
<Form action="/users" method="post" withAllErrors>
  {/* ... */}
</Form>
```

\== Svelte

```svelte
<Form action="/users" method="post" withAllErrors>
  <!-- ... -->
</Form>
```

:::

## Form Helper

In addition to the `<Form>` component, Inertia also provides a `useForm` helper for when you need programmatic control over your form's data and submission behavior.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm({
  email: null,
  password: null,
  remember: false,
})
</script>

<template>
  <form @submit.prevent="form.post('/login')">
    <input type="text" v-model="form.email" />
    <div v-if="form.errors.email">{{ form.errors.email }}</div>
    <input type="password" v-model="form.password" />
    <div v-if="form.errors.password">{{ form.errors.password }}</div>
    <input type="checkbox" v-model="form.remember" /> Remember Me
    <button type="submit" :disabled="form.processing">Login</button>
  </form>
</template>
```

\== React

```jsx
import { useForm } from '@inertiajs/react'

const { data, setData, post, processing, errors } = useForm({
  email: '',
  password: '',
  remember: false,
})

function submit(e) {
  e.preventDefault()
  post('/login')
}

return (
  <form onSubmit={submit}>
    <input
      type="text"
      value={data.email}
      onChange={(e) => setData('email', e.target.value)}
    />
    {errors.email && <div>{errors.email}</div>}
    <input
      type="password"
      value={data.password}
      onChange={(e) => setData('password', e.target.value)}
    />
    {errors.password && <div>{errors.password}</div>}
    <input
      type="checkbox"
      checked={data.remember}
      onChange={(e) => setData('remember', e.target.checked)}
    />
    Remember Me
    <button type="submit" disabled={processing}>
      Login
    </button>
  </form>
)
```

\== Svelte

```svelte
<script>
  import { useForm } from '@inertiajs/svelte'

  const form = useForm({
    email: null,
    password: null,
    remember: false,
  })

  function submit(e) {
    e.preventDefault()
    form.post('/login')
  }
</script>

<form onsubmit={submit}>
  <input type="text" bind:value={form.email} />
  {#if form.errors.email}
    <div class="form-error">{form.errors.email}</div>
  {/if}
  <input type="password" bind:value={form.password} />
  {#if form.errors.password}
    <div class="form-error">{form.errors.password}</div>
  {/if}
  <input type="checkbox" bind:checked={form.remember} /> Remember Me
  <button type="submit" disabled={form.processing}>Submit</button>
</form>
```

:::

To submit the form, you may use the `get`, `post`, `put`, `patch` and `delete` methods.

:::tabs key:frameworks

\== Vue

```js
form.submit(method, url, options)
form.get(url, options)
form.post(url, options)
form.put(url, options)
form.patch(url, options)
form.delete(url, options)
```

\== React

```js
const {
  submit,
  get,
  post,
  put,
  patch,
  delete: destroy,
} = useForm({
  /*...*/
})

submit(method, url, options)
get(url, options)
post(url, options)
put(url, options)
patch(url, options)
destroy(url, options)
```

\== Svelte

```js
form.submit(method, url, options)
form.get(url, options)
form.post(url, options)
form.put(url, options)
form.patch(url, options)
form.delete(url, options)
```

:::

The submit methods support all of the typical [visit options](/guide/manual-visits), such as `preserveState`, `preserveScroll`, and event callbacks, which can be helpful for performing tasks on successful form submissions. For example, you might use the `onSuccess` callback to reset inputs to their original state.

:::tabs key:frameworks

\== Vue

```js
form.post('/profile', {
  preserveScroll: true,
  onSuccess: () => form.reset('password'),
})
```

\== React

```js
const { post, reset } = useForm({
  /*...*/
})

post('/profile', {
  preserveScroll: true,
  onSuccess: () => reset('password'),
})
```

\== Svelte

```js
form.post('/profile', {
  preserveScroll: true,
  onSuccess: () => form.reset('password'),
})
```

:::

You may pass the HTTP method and URL as the first two arguments to `useForm()`, then call `submit()` without arguments to dispatch the request. This also unlocks real-time validation. See [Precognition](#precognition-1) for details.

If you need to modify the form data before it's sent to the server, you can do so via the `transform()` method.

:::tabs key:frameworks

\== Vue

```js
form
  .transform((data) => ({
    ...data,
    remember: data.remember ? 'on' : '',
  }))
  .post('/login')
```

\== React

```js
const { transform } = useForm({
  /*...*/
})

transform((data) => ({
  ...data,
  remember: data.remember ? 'on' : '',
}))
```

\== Svelte

```js
form
  .transform((data) => ({
    ...data,
    remember: data.remember ? 'on' : '',
  }))
  .post('/login')
```

:::

You can use the `processing` property to track if a form is currently being submitted. This can be helpful for preventing double form submissions by disabling the submit button.

:::tabs key:frameworks

\== Vue

```vue
<button type="submit" :disabled="form.processing">Submit</button>
```

\== React

```jsx
const { processing } = useForm({ /*...*/ })

<button type="submit" disabled={processing}>Submit</button>
```

\== Svelte

```svelte
<button type="submit" disabled={form.processing}>Submit</button>
```

:::

If your form is uploading files, the current progress event is available via the `progress` property, allowing you to easily display the upload progress.

:::tabs key:frameworks

\== Vue

```vue
<progress v-if="form.progress" :value="form.progress.percentage" max="100">
    {{ form.progress.percentage }}%
</progress>
```

\== React

```jsx
const { progress } = useForm({
  /*...*/
})

{
  progress && (
    <progress value={progress.percentage} max="100">
      {progress.percentage}%
    </progress>
  )
}
```

\== Svelte

```svelte
{#if form.progress}
  <progress value={form.progress.percentage} max="100">
    {form.progress.percentage}%
  </progress>
{/if}
```

:::

### Form Errors

If there are form validation errors, they are available via the `errors` property. Form errors are populated when your controller redirects with the model errors, such as `redirect_to new_user_url, inertia: { errors: user.errors }`. See [server-side responses](#server-side-responses) for a full example.

:::tabs key:frameworks

\== Vue

```vue
<div v-if="form.errors.email">{{ form.errors.email }}</div>
```

\== React

```jsx
const { errors } = useForm({
  /*...*/
})

{
  errors.email && <div>{errors.email}</div>
}
```

\== Svelte

```svelte
{#if form.errors.email}
  <div>{form.errors.email}</div>
{/if}
```

:::

For a more thorough discussion of form validation and errors, please consult the [validation documentation](/guide/validation).

To determine if a form has any errors, you may use the `hasErrors` property. To clear form errors, use the `clearErrors()` method.

:::tabs key:frameworks

\== Vue

```js
// Clear all errors...
form.clearErrors()

// Clear errors for specific fields...
form.clearErrors('field', 'anotherfield')
```

\== React

```js
const { clearErrors } = useForm({
  /*...*/
})

// Clear all errors...
clearErrors()

// Clear errors for specific fields...
clearErrors('field', 'anotherfield')
```

\== Svelte

```js
// Clear all errors...
form.clearErrors()

// Clear errors for specific fields...
form.clearErrors('field', 'anotherfield')
```

:::

If you're using client-side input validation libraries or do client-side validation manually, you can set your own errors on the form using the `setError()` method.

:::tabs key:frameworks

\== Vue

```js
// Set a single error...
form.setError('field', 'Your error message.')

// Set multiple errors at once...
form.setError({
  foo: 'Your error message for the foo field.',
  bar: 'Some other error for the bar field.',
})
```

\== React

```js
const { setError } = useForm({
  /*...*/
})

// Set a single error...
setError('field', 'Your error message.')

// Set multiple errors at once...
setError({
  foo: 'Your error message for the foo field.',
  bar: 'Some other error for the bar field.',
})
```

\== Svelte

```js
// Set a single error
form.setError('field', 'Your error message.')

// Set multiple errors at once
form.setError({
  foo: 'Your error message for the foo field.',
  bar: 'Some other error for the bar field.',
})
```

:::

Unlike an actual form submission, the page's props remain unchanged when manually setting errors on a form instance.

When a form has been successfully submitted, the `wasSuccessful` property will be `true`. In addition to this, forms have a `recentlySuccessful` property, which will be set to `true` for two seconds after a successful form submission. This property can be utilized to show temporary success messages.

You may customize the duration of the `recentlySuccessful` state by setting the `form.recentlySuccessfulDuration` option in your [application defaults](/guide/client-side-setup#configuring-defaults). The default value is `2000` milliseconds.

### Resetting the Form

To reset the form's values back to their default values, you can use the `reset()` method.

:::tabs key:frameworks

\== Vue

```js
// Reset the form...
form.reset()

// Reset specific fields...
form.reset('field', 'anotherfield')
```

\== React

```js
const { reset } = useForm({
  /*...*/
})

// Reset the form...
reset()

// Reset specific fields...
reset('field', 'anotherfield')
```

\== Svelte

```js
// Reset the form...
form.reset()

// Reset specific fields...
form.reset('field', 'anotherfield')
```

:::

@available\_since core=2.0.15

Sometimes, you may want to restore your form fields to their default values and clear any validation errors at the same time. Instead of calling `reset()` and `clearErrors()` separately, you can use the `resetAndClearErrors()` method, which combines both actions into a single call.

:::tabs key:frameworks

\== Vue

```js
// Reset the form and clear all errors...
form.resetAndClearErrors()

// Reset specific fields and clear their errors...
form.resetAndClearErrors('field', 'anotherfield')
```

\== React

```js
const { resetAndClearErrors } = useForm({
  /*...*/
})

// Reset the form and clear all errors...
resetAndClearErrors()

// Reset specific fields and clear their errors...
resetAndClearErrors('field', 'anotherfield')
```

\== Svelte

```js
// Reset the form and clear all errors...
form.resetAndClearErrors()

// Reset specific fields and clear their errors...
form.resetAndClearErrors('field', 'anotherfield')
```

:::

### Setting New Default Values

If your form's default values become outdated, you can use the `defaults()``setDefaults()``defaults()` method to update them. Then, the form will be reset to the correct values the next time the `reset()` method is invoked.

:::tabs key:frameworks

\== Vue

```js
// Set the form's current values as the new defaults...
form.defaults()

// Update the default value of a single field...
form.defaults('email', 'updated-default@example.com')

// Update the default value of multiple fields...
form.defaults({
  name: 'Updated Example',
  email: 'updated-default@example.com',
})
```

\== React

```js
const { setDefaults } = useForm({
  /*...*/
})

// Set the form's current values as the new defaults...
setDefaults()

// Update the default value of a single field...
setDefaults('email', 'updated-default@example.com')

// Update the default value of multiple fields...
setDefaults({
  name: 'Updated Example',
  email: 'updated-default@example.com',
})
```

\== Svelte

```js
// Set the form's current values as the new defaults...
form.defaults()

// Update the default value of a single field...
form.defaults('email', 'updated-default@example.com')

// Change the default value of multiple fields...
form.defaults({
  name: 'Updated Example',
  email: 'updated-default@example.com',
})
```

:::

### Form Field Change Tracking

To determine if a form has any changes, you may use the `isDirty` property.

:::tabs key:frameworks

\== Vue

```vue
<div v-if="form.isDirty">There are unsaved form changes.</div>
```

\== React

```jsx
const { isDirty } = useForm({
  /*...*/
})

{
  isDirty && <div>There are unsaved form changes.</div>
}
```

\== Svelte

```svelte
{#if form.isDirty}
  <div>There are unsaved form changes.</div>
{/if}
```

:::

### Canceling Form Submissions

To cancel a form submission, use the `cancel()` method.

:::tabs key:frameworks

\== Vue

```js
form.cancel()
```

\== React

```js
const { cancel } = useForm({
  /*...*/
})

cancel()
```

\== Svelte

```js
form.cancel()
```

:::

### Form Data and History State

To instruct Inertia to store a form's data and errors in [history state](/guide/remembering-state), you can provide a unique form key as the first argument when instantiating your form.

:::tabs key:frameworks

\== Vue

```js
import { useForm } from '@inertiajs/vue3'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)
```

\== React

```js
import { useForm } from '@inertiajs/react'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)
```

\== Svelte

```js
import { useForm } from '@inertiajs/svelte'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)
```

:::

#### Excluding Fields

@available\_since core=2.3.7

Sensitive fields like passwords may be excluded from history state using the `dontRemember()` method.

:::tabs key:frameworks

\== Vue

```js
import { useForm } from '@inertiajs/vue3'

const form = useForm('LoginForm', {
  email: '',
  password: '',
}).dontRemember('password')
```

\== React

```js
import { useForm } from '@inertiajs/react'

const form = useForm('LoginForm', {
  email: '',
  password: '',
}).dontRemember('password')
```

\== Svelte

```js
import { useForm } from '@inertiajs/svelte'

const form = useForm('LoginForm', {
  email: '',
  password: '',
}).dontRemember('password')
```

:::

Multiple fields may be excluded by passing additional arguments.

```js
form.dontRemember('password', 'password_confirmation')
```

> \[!NOTE]
> Some browsers trigger a "save password" prompt whenever password field values
> are written to history state, even without form submission. Excluding password
> fields avoids this issue.

### Precognition

@available\_since core=2.3.0

Just like the `<Form>` component, the `useForm` helper supports [Precognition](#precognition) for real-time validation. You may enable it by chaining the `withPrecognition()` method with the HTTP method and endpoint for validation requests.

> \[!NOTE]
> Precognition requires server-side support. See the [Precognition guide](/guide/precognition) for Rails setup instructions.

:::tabs key:frameworks

\== Vue

```js
import { useForm } from '@inertiajs/vue3'

const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')
```

\== React

```js
import { useForm } from '@inertiajs/react'

const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')
```

\== Svelte

```js
import { useForm } from '@inertiajs/svelte'

const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')
```

:::

For backwards compatibility with the `laravel-precognition` packages, you may also pass the method and URL as the first arguments to `useForm()`.

```js
const form = useForm('post', '/users', {
  name: '',
  email: '',
})
```

Once Precognition is enabled, call `validate()` with a field name to trigger validation for that field. The `invalid()` helper checks if a field has validation errors, while `validating` indicates when a request is in progress.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useForm } from '@inertiajs/vue3'

const form = useForm('post', '/users', {
  name: '',
  email: '',
})
</script>

<template>
  <form @submit.prevent="form.submit()">
    <input v-model="form.name" @change="form.validate('name')" />
    <p v-if="form.invalid('name')">{{ form.errors.name }}</p>

    <input v-model="form.email" @change="form.validate('email')" />
    <p v-if="form.invalid('email')">{{ form.errors.email }}</p>

    <p v-if="form.validating">Validating...</p>

    <button type="submit">Create User</button>
  </form>
</template>
```

\== React

```jsx
import { useForm } from '@inertiajs/react'

const { data, setData, submit, errors, validating, validate, invalid } =
  useForm('post', '/users', {
    name: '',
    email: '',
  })

function handleSubmit(e) {
  e.preventDefault()
  submit()
}

return (
  <form onSubmit={handleSubmit}>
    <input
      value={data.name}
      onChange={(e) => setData('name', e.target.value)}
      onBlur={() => validate('name')}
    />
    {invalid('name') && <p>{errors.name}</p>}

    <input
      value={data.email}
      onChange={(e) => setData('email', e.target.value)}
      onBlur={() => validate('email')}
    />
    {invalid('email') && <p>{errors.email}</p>}

    {validating && <p>Validating...</p>}

    <button type="submit">Create User</button>
  </form>
)
```

\== Svelte

```svelte
<script>
  import { useForm } from '@inertiajs/svelte'

  const form = useForm('post', '/users', {
    name: '',
    email: '',
  })
</script>

<form
  onsubmit={(e) => {
    e.preventDefault()
    form.submit()
  }}
>
  <input bind:value={form.name} onchange={() => form.validate('name')} />
  {#if form.invalid('name')}
    <p>{form.errors.name}</p>
  {/if}

  <input bind:value={form.email} onchange={() => form.validate('email')} />
  {#if form.invalid('email')}
    <p>{form.errors.email}</p>
  {/if}

  {#if form.validating}
    <p>Validating...</p>
  {/if}

  <button type="submit">Create User</button>
</form>
```

:::

You may also use the `valid()` helper to check if a field has passed validation.

#### Touch and Validate

The `touch()` method marks fields as "touched" without triggering validation. You may then validate all touched fields by calling `validate()` without arguments. The `touched()` helper checks if a field has been touched. The `reset()` method clears the touched state for reset fields.

:::tabs key:frameworks

\== Vue

```vue
<input v-model="form.name" @blur="form.touch('name')" />
<input v-model="form.email" @blur="form.touch('email')" />

<button type="button" @click="form.validate()">Validate Touched Fields</button>

<p v-if="form.touched('name')">Name has been touched</p>
```

\== React

```jsx
<input value={data.name} onChange={e => setData('name', e.target.value)} onBlur={() => touch('name')} />
<input value={data.email} onChange={e => setData('email', e.target.value)} onBlur={() => touch('email')} />

<button type="button" onClick={() => validate()}>Validate Touched Fields</button>

{touched('name') && <p>Name has been touched</p>}
```

\== Svelte

```svelte
<input bind:value={form.name} onblur={() => form.touch('name')} />
<input bind:value={form.email} onblur={() => form.touch('email')} />

<button type="button" onclick={() => form.validate()}
  >Validate Touched Fields</button
>

{#if form.touched('name')}
  <p>Name has been touched</p>
{/if}
```

:::

#### Options

Validation requests are automatically debounced. The first request fires immediately, then subsequent changes are debounced (1500ms by default). You may customize this timeout using `setValidationTimeout()`.

:::tabs key:frameworks

\== Vue

```js
const form = useForm('post', '/users', {
  name: '',
}).setValidationTimeout(500)
```

\== React

```js
const form = useForm('post', '/users', {
  name: '',
})

form.setValidationTimeout(500)
```

\== Svelte

```js
const form = useForm('post', '/users', {
  name: '',
})

form.setValidationTimeout(500)
```

:::

By default, files are excluded from validation requests to avoid unnecessary uploads. You may enable file validation using `validateFiles()`.

:::tabs key:frameworks

\== Vue

```js
const form = useForm('post', '/users', {
  avatar: null,
}).validateFiles()
```

\== React

```js
const form = useForm('post', '/users', {
  avatar: null,
})

form.validateFiles()
```

\== Svelte

```js
const form = useForm('post', '/users', {
  avatar: null,
})

form.validateFiles()
```

:::

By default, validation errors are simplified to strings (the first error message). You can indicate you would like all errors as arrays using `withAllErrors()`.

:::tabs key:frameworks

\== Vue

```js
const form = useForm('post', '/users', {
  name: '',
}).withAllErrors()
```

\== React

```js
const form = useForm('post', '/users', {
  name: '',
})

form.withAllErrors()
```

\== Svelte

```js
const form = useForm('post', '/users', {
  name: '',
})

form.withAllErrors()
```

:::

With Precognition enabled, you may call `submit()` without arguments to dispatch the request to the configured endpoint.

## Server-Side Responses

When using Inertia, you don't typically inspect form responses client-side like you would with traditional XHR/fetch requests. Instead, your server-side route or controller issues a [redirect](/guide/redirects) response after processing the form, often redirecting to a success page.

```ruby
class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      redirect_to users_url
    else
      redirect_to new_user_url, inertia: { errors: user.errors }
    end
  end

  private

  def user_params
    params.expect(user: [:name, :email])
  end
end
```

This redirect-based approach works with all form submission methods: the `<Form>` component, `useForm` helper, and manual router submissions. It makes handling Inertia forms feel very similar to classic server-side form submissions.

## Server-Side Validation

Both the `<Form>` component and `useForm` helper automatically handle server-side validation errors. When your server returns validation errors, they're automatically available in the `errors` object without any additional configuration.

Unlike traditional XHR/fetch requests where you might check for a `422` status code, Inertia handles validation errors as part of its redirect-based flow, just like classic server-side form submissions, but without the full page reload.

For a complete guide on validation error handling, including error bags and advanced scenarios, see the [validation documentation](/guide/validation).

## Manual Form Submissions

It's also possible to submit forms manually using Inertia's `router` methods directly, without using the `<Form>` component or `useForm` helper:

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { reactive } from 'vue'
import { router } from '@inertiajs/vue3'

const form = reactive({
  first_name: null,
  last_name: null,
  email: null,
})

function submit() {
  router.post('/users', form)
}
</script>

<template>
  <form @submit.prevent="submit">
    <label for="first_name">First name:</label>
    <input id="first_name" v-model="form.first_name" />
    <label for="last_name">Last name:</label>
    <input id="last_name" v-model="form.last_name" />
    <label for="email">Email:</label>
    <input id="email" v-model="form.email" />
    <button type="submit">Submit</button>
  </form>
</template>
```

\== React

```jsx
import { useState } from 'react'
import { router } from '@inertiajs/react'

export default function Edit() {
  const [values, setValues] = useState({
    first_name: '',
    last_name: '',
    email: '',
  })

  function handleChange(e) {
    const key = e.target.id
    const value = e.target.value
    setValues((values) => ({
      ...values,
      [key]: value,
    }))
  }

  function handleSubmit(e) {
    e.preventDefault()
    router.post('/users', values)
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="first_name">First name:</label>
      <input
        id="first_name"
        value={values.first_name}
        onChange={handleChange}
      />
      <label htmlFor="last_name">Last name:</label>
      <input id="last_name" value={values.last_name} onChange={handleChange} />
      <label htmlFor="email">Email:</label>
      <input id="email" value={values.email} onChange={handleChange} />
      <button type="submit">Submit</button>
    </form>
  )
}
```

\== Svelte

```svelte
<script>
  import { router } from '@inertiajs/svelte'

  let values = {
    first_name: null,
    last_name: null,
    email: null,
  }

  function submit(e) {
    e.preventDefault()
    router.post('/users', values)
  }
</script>

<form onsubmit={submit}>
  <label for="first_name">First name:</label>
  <input id="first_name" bind:value={values.first_name} />

  <label for="last_name">Last name:</label>
  <input id="last_name" bind:value={values.last_name} />

  <label for="email">Email:</label>
  <input id="email" bind:value={values.email} />

  <button type="submit">Submit</button>
</form>
```

:::

## File Uploads

When making requests or form submissions that include files, Inertia will automatically convert the request data into a `FormData` object. This works with the `<Form>` component, `useForm` helper, and manual router submissions.

For more information on file uploads, including progress tracking, see the [file uploads documentation](/guide/file-uploads).

## Optimistic Updates

Both the `<Form>` component and `useForm` helper support optimistic updates, allowing you to update the UI immediately before the server responds. For more details, see the [optimistic updates](/guide/optimistic-updates) documentation.

## Non-Inertia Submissions

Using Inertia to submit forms works great for the vast majority of situations. For standalone HTTP requests that don't trigger page visits, you may use the [`useHttp`](/guide/http-requests) hook, which provides the same developer experience as `useForm`. You're also free to make plain XHR or `fetch` requests using the library of your choice.

---

---
url: /cookbook/handling-validation-error-types.md
---
# Handling Rails validation error types

When using Inertia Rails with TypeScript, you might encounter a mismatch between the way Rails and Inertia handle validation errors.

* Inertia's `useForm` hook expects the `errors` object to have values as single strings (e.g., `"This field is required"`).
* Rails model errors (`model.errors`), however, provide an array of strings for each field (e.g., `["This field is required", "Must be unique"]`).

If you pass `inertia: { errors: user.errors }` directly from a Rails controller, this mismatch will cause a type conflict.

We'll explore two options to resolve this issue.

## Option 1: Adjust Inertia types

You can update the TypeScript definitions to match the Rails error format (arrays of strings).

Create a custom type definition file in your project:

:::tabs key:frameworks
\== Vue

```typescript
// frontend/app/types/inertia-rails.d.ts
import type { FormDataConvertible, FormDataKeys } from '@inertiajs/core'
import type { InertiaFormProps as OriginalProps } from '@inertiajs/vue3'

type FormDataType = Record<string, FormDataConvertible>

declare module '@inertiajs/vue3' {
  interface InertiaFormProps<TForm extends FormDataType> extends Omit<
    OriginalProps<TForm>,
    'errors' | 'setError'
  > {
    errors: Partial<Record<FormDataKeys<TForm>, string[]>>

    setError(field: FormDataKeys<TForm>, value: string[]): this

    setError(errors: Record<FormDataKeys<TForm>, string[]>): this
  }

  export type InertiaForm<TForm extends FormDataType> = TForm &
    InertiaFormProps<TForm>

  export { InertiaFormProps, InertiaForm }

  export function useForm<TForm extends FormDataType>(
    data: TForm | (() => TForm),
  ): InertiaForm<TForm>
  export function useForm<TForm extends FormDataType>(
    rememberKey: string,
    data: TForm | (() => TForm),
  ): InertiaForm<TForm>
}
```

\== React

```typescript
// frontend/app/types/inertia-rails.d.ts
import type { FormDataConvertible, FormDataKeys } from '@inertiajs/core'
import type { InertiaFormProps as OriginalProps } from '@inertiajs/react'

type FormDataType = Record<string, FormDataConvertible>

declare module '@inertiajs/react' {
  interface InertiaFormProps<TForm extends FormDataType> extends Omit<
    OriginalProps<TForm>,
    'errors' | 'setError'
  > {
    errors: Partial<Record<FormDataKeys<TForm>, string[]>>

    setError(field: FormDataKeys<TForm>, value: string[]): void

    setError(errors: Record<FormDataKeys<TForm>, string[]>): void
  }

  export { InertiaFormProps }

  export function useForm<TForm extends FormDataType>(
    initialValues?: TForm,
  ): InertiaFormProps<TForm>
  export function useForm<TForm extends FormDataType>(
    rememberKey: string,
    initialValues?: TForm,
  ): InertiaFormProps<TForm>
}
```

\== Svelte

```typescript
// frontend/app/types/inertia-rails.d.ts
import type { FormDataConvertible, FormDataKeys } from '@inertiajs/core'
import type { InertiaFormProps as OriginalProps } from '@inertiajs/svelte'
import type { Writable } from 'svelte/store'

type FormDataType = Record<string, FormDataConvertible>

declare module '@inertiajs/svelte' {
  interface InertiaFormProps<TForm extends FormDataType> extends Omit<
    OriginalProps<TForm>,
    'errors' | 'setError'
  > {
    errors: Partial<Record<FormDataKeys<TForm>, string[]>>

    setError(field: FormDataKeys<TForm>, value: string[]): this

    setError(errors: Record<FormDataKeys<TForm>, string[]>): this
  }

  type InertiaForm<TForm extends FormDataType> = InertiaFormProps<TForm> & TForm

  export { InertiaFormProps, InertiaForm }

  export function useForm<TForm extends FormDataType>(
    data: TForm | (() => TForm),
  ): Writable<InertiaForm<TForm>>
  export function useForm<TForm extends FormDataType>(
    rememberKey: string,
    data: TForm | (() => TForm),
  ): Writable<InertiaForm<TForm>>
}
```

:::

This tells TypeScript to expect errors as arrays of strings, matching Rails' format.

> \[!NOTE]
> Make sure that `d.ts` files are referenced in your `tsconfig.json` or `tsconfig.app.json`. If it reads something like `"include": ["app/frontend/**/*.ts"]` or `"include": ["app/frontend/**/*"]` and your `d.ts` file is inside `app/frontend`, it should work.

## Option 2: Serialize errors in Rails

You can add a helper on the Rails backend to convert error arrays into single strings before sending them to Inertia.

1. Add a helper method (e.g., in `ApplicationController`):

   ```ruby
   def inertia_errors(model)
     {
       errors: model.errors.to_hash(true).transform_values(&:to_sentence)
     }
   end
   ```

   This combines multiple error messages for each field into a single string.

2. Use the helper when redirecting with errors:

   ```ruby
   redirect_back_or_to root_path, inertia: inertia_errors(model)
   ```

This ensures the errors sent to the frontend are single strings, matching Inertia's default expectations.

---

---
url: /guide/history-encryption.md
---
# History Encryption

Imagine a scenario where your user is authenticated, browses privileged information on your site, then logs out. If they press the back button, they can still see the privileged information that is stored in the window's history state. This is a security risk. To prevent this, Inertia.js provides a history encryption feature.

## How It Works

When you instruct Inertia to encrypt your app's history, it uses the browser's built-in [`crypto` api](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) to encrypt the current page's data before pushing it to the history state. We store the corresponding key in the browser's session storage. When the user navigates back to a page, we decrypt the data using the key stored in the session storage.

Once you instruct Inertia to clear your history state, we simply clear the existing key from session storage roll a new one. If we attempt to decrypt the history state with the new key, it will fail and Inertia will make a fresh request back to your server for the page data.

History encryption relies on `window.crypto.subtle` which is only available in secure environments (sites with SSL enabled).

## Opting in

History encryption is disabled by default in the Rails adapter. The [Rails generator](/guide/server-side-setup#rails-generator) enables it globally in new apps. There are several methods for enabling it:

### Global Encryption

If you'd like to enable history encryption globally, set the `encrypt_history` config value to `true`.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.encrypt_history = true
end
```

You are able to opt out of encryption on specific pages by passing `false` to the `encrypt_history` option.

```ruby
render inertia: {}, encrypt_history: false
```

### Per-request Encryption

To encrypt the history of an individual request, simply pass `true` to the `encrypt_history` option.

```ruby
render inertia: {}, encrypt_history: true
```

### Encrypt Middleware

You can also enable history encryption for all actions in a controller by setting the `encrypt_history` config value in the controller.

```ruby
class DashboardController < ApplicationController
  inertia_config(encrypt_history: true)

  # ...
end
```

## Clearing History

To clear the history state on the server side, you can pass the `clear_history` option to the `render` method.

```ruby
render inertia: {}, clear_history: true
```

You can also pass the option to `redirect_to`, for example in a logout action. The flag survives the redirect and is applied by the next rendered page:

```ruby
def destroy
  terminate_session
  redirect_to new_session_path, status: :see_other, inertia: { clear_history: true }
end
```

Once the response has rendered on the client, the encryption key will be rotated, rendering the previous history state unreadable.

> \[!NOTE]
> Clearing history only protects pages that were stored encrypted. With `encrypt_history` disabled, history entries are stored in plain text and remain readable after the key rotation, so the Back button will still restore them.

You can also clear history on the client side by calling `router.clearHistory()`.

---

---
url: /guide/how-it-works.md
---
# How it works

## Use the Tools You Love

With Inertia you build applications just like you've always done with your server-side web framework of choice. You use your framework's existing functionality for routing, controllers, middleware, authentication, authorization, data fetching, and more.

However, Inertia replaces your application's view layer. Instead of using server-side rendering via PHP or Ruby templates, the views returned by your application are JavaScript page components. This allows you to build your entire frontend using React, Vue, or Svelte, while still enjoying the productivity of Laravel or your preferred server-side framework.

## Intercepting Requests

As you might expect, simply creating your frontend in JavaScript doesn't give you a single-page application experience. If you were to click a link, your browser would make a full page visit, which would then cause your client-side framework to reboot on the subsequent page load. This is where Inertia changes everything.

At its core, Inertia is essentially a client-side routing library. It allows you to make page visits without forcing a full page reload. This is done using the `<Link>` component, a light-weight wrapper around a normal anchor link. When you click an Inertia link, Inertia intercepts the click and makes the visit via XHR instead. You can even make these visits programmatically in JavaScript using `router.visit()`.

When Inertia makes an XHR visit, the server detects that it's an Inertia visit and, instead of returning a full HTML response, it returns a JSON response with the JavaScript page component name and data (props). Inertia then dynamically swaps out the previous page component with the new page component and updates the browser's history state.

**The end result is a silky smooth single-page experience.**

To learn more about the nitty-gritty, technical details of how Inertia works under the hood, check out the [protocol page](/guide/the-protocol).

---

---
url: /cookbook/http-caching-and-xsrf-cookie-refresh.md
---
# HTTP caching and XSRF cookie refresh

By default, Inertia Rails rewrites the `XSRF-TOKEN` cookie on every protected request. Each rewrite emits a `Set-Cookie` header — including on otherwise cacheable `GET` responses and even on `304 Not Modified` responses. If your app relies on HTTP caching for Inertia pages, that header can quietly defeat it. This page explains why it happens and how to opt into a less aggressive refresh policy. For the broader caching picture, see the [caching guide](/guide/caching).

> \[!NOTE]
> On Rails 8.2+ with the `:header_only` forgery protection strategy (the 8.2 default), none of this applies: authenticity tokens are never read, so the adapter skips the `XSRF-TOKEN` cookie entirely and no `Set-Cookie` is emitted at all. See [Header-Only CSRF Protection](/guide/csrf-protection#header-only-csrf-protection-rails-8-2). The refresh policies below matter only for token-based strategies.

## Symptom

The problem shows up in two places:

* **CDNs and shared caches.** Most shared caches refuse to cache responses that carry `Set-Cookie`. For example, Cloudflare either strips the header or [sets the cache status to `BYPASS`](https://developers.cloudflare.com/cache/concepts/cache-behavior/), depending on cache settings. `rack-cache`, Varnish, and Fastly behave similarly by default. If every response carries a fresh `XSRF-TOKEN`, your cacheable pages never get cached.
* **Browser conditional caching.** Apps using `fresh_when` / `stale?` expect reloads to settle into a clean `If-None-Match` / `304` loop. Repeated cookie writes on cacheable responses have been observed to prevent that, most notably in Safari/WebKit (Chrome and Firefox usually revalidate cookie-bearing responses correctly).

## Why it happens

The adapter refreshes the `XSRF-TOKEN` cookie in an `after_action` on every request where forgery protection is active, so Inertia's HTTP client can read it and send it back as an `X-XSRF-TOKEN` header.

Rails normally suppresses `Set-Cookie` when a cookie is written with its existing value — but that never applies here. Rails masks CSRF tokens with a random one-time pad on every call (a BREACH mitigation), so `form_authenticity_token` returns a *different* string on every request even though the underlying token hasn't changed. The cookie jar sees a new value every time and emits `Set-Cookie` on every response, including `304`s.

Because the value is re-masked on every call, the only way to know whether the cookie actually needs a refresh is to unmask and compare it against the session token — which is exactly what the `:lazy` policy does when it can.

## The `:lazy` policy

To skip unnecessary rewrites on steady-state safe requests, opt into the `:lazy` policy:

```ruby
InertiaRails.configure do |config|
  config.xsrf_cookie_refresh = :lazy
end
```

You can also enable it for specific controllers only:

```ruby
class CachedPagesController < ApplicationController
  inertia_config xsrf_cookie_refresh: :lazy
end
```

Under `:lazy`, the adapter behaves as follows:

* `GET` / `HEAD` requests with no `XSRF-TOKEN` cookie: set the cookie, as before.
* `GET` / `HEAD` requests with an existing cookie, when the session or CSRF token is already loaded: validate the cookie against the session and refresh it only if it's stale.
* `GET` / `HEAD` requests with an existing cookie, when nothing has loaded the session: trust the cookie and skip the write (see the caveat below).
* Non-safe requests (`POST`, `PATCH`, and so on): always refresh, as before.

Conditionally cached pages take the validation path, not the trust path: `fresh_when` and `stale?` load the session (flash is part of the default ETag), so a stale cookie is detected and refreshed even on a `304` response.

## When this matters

This option matters most when all of the following are true:

* your app uses `fresh_when` / `stale?` on Inertia pages, or serves them through a CDN
* the route is a cacheable `GET`
* you expect reloads or revisits to produce `304`s or CDN cache hits

It usually does **not** matter for apps that rely only on Inertia prefetching or server-side caching.

## What this does not solve

This option only addresses `XSRF-TOKEN` churn.

Cookie-backed sessions are a separate source of `Set-Cookie` churn: the session cookie is re-encrypted on every response that touches the session, and `fresh_when` / `stale?` touch the session. If your app stores sessions in cookies, `:lazy` alone won't produce fully `Set-Cookie`-free `304`s — moving session storage to Redis or a database removes that second source.

The adapter also deliberately does *not* load a lazy session just to validate an existing cookie: loading a cookie-backed session emits its own session `Set-Cookie`, which would reintroduce the exact churn this option removes.

## Caveat: stale cookies on session-less requests

On `GET` / `HEAD` requests where nothing loads the session — no Inertia render, no flash, no `fresh_when` — an existing cookie is trusted without validation. A stale cookie (for example, after a `secret_key_base` rotation) is not detected on those requests, so the next protected request fails with `InvalidAuthenticityToken`.

This failure is loud, never a silent CSRF bypass: the cookie is not a server-side validation input (the server checks the `X-XSRF-TOKEN` *header* against the session). And it self-heals — any request that loads the session, including every rendered Inertia response, validates and refreshes the cookie.

## Security tradeoff

The tradeoff is compatibility, not reduced CSRF protection:

* Rails still validates CSRF tokens on all non-GET requests.
* Existing cookies are validated whenever validation is possible without loading the session solely for that check.
* Legitimate failures appear as `InvalidAuthenticityToken`, not as a silent bypass.

If you need every safe request to refresh the XSRF cookie from the current session state, keep the default `:always` policy.

> \[!NOTE]
> Rails 8.2 introduces `protect_from_forgery using: :header_only`, which verifies requests with the `Sec-Fetch-Site` header instead of tokens. On apps using that strategy the `XSRF-TOKEN` cookie serves no purpose at all, and a policy to skip it entirely may be added in a future release. `:lazy` targets today's token-based apps, including Rails 8.2's `:header_or_legacy_token` upgrade path.

---

---
url: /guide/http-requests.md
---
# HTTP Requests

@available\_since core=3.0.0

Not every request needs to trigger an Inertia page visit. For calls to an external API or fetching data from a non-Inertia endpoint, the `useHttp` hook provides the same developer experience as `useForm`, but for standalone HTTP requests.

## Basic Usage

The `useHttp` hook accepts initial data and returns reactive state along with methods for making HTTP requests.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
  query: '',
})

function search() {
  http.get('/api/search', {
    onSuccess: (response) => {
      console.log(response)
    },
  })
}
</script>

<template>
  <input v-model="http.query" @input="search" />
  <div v-if="http.processing">Searching...</div>
</template>
```

\== React

```jsx
import { useHttp } from '@inertiajs/react'

export default function Search() {
  const { data, setData, get, processing } = useHttp({
    query: '',
  })

  function search(e) {
    setData('query', e.target.value)
    get('/api/search', {
      onSuccess: (response) => {
        console.log(response)
      },
    })
  }

  return (
    <>
      <input value={data.query} onChange={search} />
      {processing && <div>Searching...</div>}
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { useHttp } from '@inertiajs/svelte'

  const http = useHttp({
    query: '',
  })

  function search() {
    http.get('/api/search', {
      onSuccess: (response) => {
        console.log(response)
      },
    })
  }
</script>

<input bind:value={http.query} oninput={search} />
{#if http.processing}
  <div>Searching...</div>
{/if}
```

:::

Unlike router visits, `useHttp` requests do not trigger page navigation or interact with Inertia's page lifecycle. They are plain HTTP requests that return JSON responses.

## Submitting Data

The hook provides `get`, `post`, `put`, `patch`, and `delete` convenience methods. A generic `submit` method is also available for dynamic HTTP methods.

:::tabs key:frameworks

\== Vue

```js
http.get(url, options)
http.post(url, options)
http.put(url, options)
http.patch(url, options)
http.delete(url, options)
http.submit(method, url, options)
```

\== React

```js
const {
  get,
  post,
  put,
  patch,
  delete: destroy,
  submit,
} = useHttp({
  /*...*/
})

get(url, options)
post(url, options)
put(url, options)
patch(url, options)
destroy(url, options)
submit(method, url, options)
```

\== Svelte

```js
http.get(url, options)
http.post(url, options)
http.put(url, options)
http.patch(url, options)
http.delete(url, options)
http.submit(method, url, options)
```

:::

Each method returns a `Promise` that resolves with the parsed JSON response data. TypeScript users may [type the request data and response](/guide/typescript#http-helper).

### Pre-binding the Endpoint

You may pass the HTTP method and URL as the first two arguments to `useHttp()`, then call `submit()` without arguments to dispatch the request. This also unlocks real-time validation. See [Precognition](#precognition) for details.

:::tabs key:frameworks

\== Vue

```js
const http = useHttp('post', '/api/comments', {
  body: '',
})

const response = await http.submit()
```

\== React

```js
const { submit } = useHttp('post', '/api/comments', {
  body: '',
})

const response = await submit()
```

\== Svelte

```js
const http = useHttp('post', '/api/comments', {
  body: '',
})

const response = await http.submit()
```

:::

## Multiple Requests

Each `useHttp` instance tracks its own `processing`, `errors`, and other reactive state. When making independent requests, you may create a separate instance for each one so their states don't collide.

:::tabs key:frameworks

\== Vue

```js
const search = useHttp({ query: '' })
const upload = useHttp({ file: null })
```

\== React

```js
const search = useHttp({ query: '' })
const upload = useHttp({ file: null })
```

\== Svelte

```js
const search = useHttp({ query: '' })
const upload = useHttp({ file: null })
```

:::

## Reactive State

The `useHttp` hook exposes the same reactive properties as `useForm`:

| Property             | Type             | Description                                       |
| -------------------- | ---------------- | ------------------------------------------------- |
| `errors`             | `object`         | Validation errors keyed by field name             |
| `hasErrors`          | `boolean`        | Whether validation errors exist                   |
| `processing`         | `boolean`        | Whether a request is in progress                  |
| `progress`           | `object \| null` | Upload progress with `percentage` and `total`     |
| `wasSuccessful`      | `boolean`        | Whether the last request was successful           |
| `recentlySuccessful` | `boolean`        | `true` for two seconds after a successful request |
| `isDirty`            | `boolean`        | Whether the data differs from its defaults        |

## Validation Errors

When a request returns a `422` status code, the hook automatically parses validation errors and makes them available through the `errors` property.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
  name: '',
  email: '',
})

function save() {
  http.post('/api/users')
}
</script>

<template>
  <input v-model="http.name" />
  <div v-if="http.errors.name">{{ http.errors.name }}</div>

  <input v-model="http.email" />
  <div v-if="http.errors.email">{{ http.errors.email }}</div>

  <button @click="save" :disabled="http.processing">Save</button>
</template>
```

\== React

```jsx
import { useHttp } from '@inertiajs/react'

export default function CreateUser() {
  const { data, setData, post, errors, processing } = useHttp({
    name: '',
    email: '',
  })

  function save(e) {
    e.preventDefault()
    post('/api/users')
  }

  return (
    <form onSubmit={save}>
      <input
        value={data.name}
        onChange={(e) => setData('name', e.target.value)}
      />
      {errors.name && <div>{errors.name}</div>}

      <input
        value={data.email}
        onChange={(e) => setData('email', e.target.value)}
      />
      {errors.email && <div>{errors.email}</div>}

      <button type="submit" disabled={processing}>
        Save
      </button>
    </form>
  )
}
```

\== Svelte

```svelte
<script>
  import { useHttp } from '@inertiajs/svelte'

  const http = useHttp({
    name: '',
    email: '',
  })

  function save() {
    http.post('/api/users')
  }
</script>

<input bind:value={http.name} />
{#if http.errors.name}
  <div>{http.errors.name}</div>
{/if}

<input bind:value={http.email} />
{#if http.errors.email}
  <div>{http.errors.email}</div>
{/if}

<button onclick={save} disabled={http.processing}>Save</button>
```

:::

## Displaying All Errors

By default, validation errors are simplified to the first error message for each field. You may chain `withAllErrors()` to receive all error messages as arrays, which is useful for fields with multiple validation rules.

:::tabs key:frameworks

\== Vue

```js
const http = useHttp({
  name: '',
  email: '',
}).withAllErrors()

// http.errors.name === ['Name is required.', 'Name must be at least 3 characters.']
```

\== React

```js
const http = useHttp({
  name: '',
  email: '',
}).withAllErrors()

// http.errors.name === ['Name is required.', 'Name must be at least 3 characters.']
```

\== Svelte

```js
const http = useHttp({
  name: '',
  email: '',
}).withAllErrors()

// http.errors.name === ['Name is required.', 'Name must be at least 3 characters.']
```

:::

The same method is available on the [`useForm`](/guide/forms#options-1) helper and the [`<Form>`](/guide/forms#options) component.

## File Uploads

When the data includes files, the hook automatically sends the request as `multipart/form-data`. Upload progress is available through the `progress` property.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
  file: null,
})

function upload() {
  http.post('/api/uploads')
}
</script>

<template>
  <input type="file" @change="http.file = $event.target.files[0]" />
  <progress v-if="http.progress" :value="http.progress.percentage" max="100" />
  <button @click="upload" :disabled="http.processing">Upload</button>
</template>
```

\== React

```jsx
import { useHttp } from '@inertiajs/react'

export default function Upload() {
  const { setData, post, progress, processing } = useHttp({
    file: null,
  })

  return (
    <>
      <input type="file" onChange={(e) => setData('file', e.target.files[0])} />
      {progress && <progress value={progress.percentage} max="100" />}
      <button onClick={() => post('/api/uploads')} disabled={processing}>
        Upload
      </button>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { useHttp } from '@inertiajs/svelte'

  const http = useHttp({
    file: null,
  })

  function upload() {
    http.post('/api/uploads')
  }
</script>

<input type="file" onchange={(e) => (http.file = e.target.files[0])} />
{#if http.progress}
  <progress value={http.progress.percentage} max="100" />
{/if}
<button onclick={upload} disabled={http.processing}>Upload</button>
```

:::

## Cancelling Requests

You may cancel an in-progress request using the `cancel()` method.

:::tabs key:frameworks

\== Vue

```js
http.cancel()
```

\== React

```js
const { cancel } = useHttp({
  /*...*/
})

cancel()
```

\== Svelte

```js
http.cancel()
```

:::

## Optimistic Updates

The `useHttp` hook supports [optimistic updates](/guide/optimistic-updates) via the `optimistic()` method. The callback receives the current data and should return a partial update to apply immediately.

:::tabs key:frameworks

\== Vue

```js
http
  .optimistic((data) => ({
    likes: data.likes + 1,
  }))
  .post('/api/likes')
```

\== React

```js
const { optimistic, post } = useHttp({ likes: 0 })

optimistic((data) => ({
  likes: data.likes + 1,
}))
post('/api/likes')
```

\== Svelte

```js
http
  .optimistic((data) => ({
    likes: data.likes + 1,
  }))
  .post('/api/likes')
```

:::

The update is applied synchronously. If the request fails, the data is rolled back to its previous state.

## Event Callbacks

Each submit method accepts an options object with lifecycle callbacks:

```js
http.post('/api/users', {
  onBefore: () => {
    /*...*/
  },
  onStart: () => {
    /*...*/
  },
  onProgress: (progress) => {
    /*...*/
  },
  onSuccess: (data, response) => {
    /*...*/
  },
  onError: (errors) => {
    /*...*/
  },
  onHttpException: (response) => {
    /*...*/
  },
  onNetworkError: (error) => {
    /*...*/
  },
  onCancel: () => {
    /*...*/
  },
  onFinish: () => {
    /*...*/
  },
})
```

You may return `false` from `onBefore` to cancel the request.

### Accessing the HTTP response

@available\_since core=3.0.3

The `onSuccess` callback receives the parsed response data as its first argument and the HTTP response object as its second argument. The response object contains `status`, `data`, and `headers` properties, which is useful when you need to inspect the status code or response headers.

```js
http.post('/api/users', {
  onSuccess: (data, response) => {
    console.log(response.status) // 200, 201, etc.
  },
})
```

### HTTP exceptions

@available\_since core=3.0.3

The `onHttpException` callback fires when the server returns a non-422 HTTP error, such as a `500` or `403`. The callback receives the HTTP response object, giving you access to the status code, response body, and headers.

```js
http.post('/api/users', {
  onHttpException: (response) => {
    console.log(response.status) // 500, 403, etc.
    console.log(response.data) // Response body
  },
})
```

### Network errors

@available\_since core=3.0.3

The `onNetworkError` callback fires when the request fails due to a network issue, such as when the user loses their internet connection. The callback receives the `Error` object.

```js
http.post('/api/users', {
  onNetworkError: (error) => {
    console.log(error.message)
  },
})
```

## Precognition

The `useHttp` hook supports Precognition for real-time validation. Enable it by chaining `withPrecognition()` with the HTTP method and validation endpoint.

> \[!NOTE]
> Precognition requires server-side support. See the [Precognition guide](/guide/precognition) for Rails setup instructions.

:::tabs key:frameworks

\== Vue

```js
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
  name: '',
  email: '',
}).withPrecognition('post', '/api/users')
```

\== React

```js
import { useHttp } from '@inertiajs/react'

const http = useHttp({
  name: '',
  email: '',
}).withPrecognition('post', '/api/users')
```

\== Svelte

```js
import { useHttp } from '@inertiajs/svelte'

const http = useHttp({
  name: '',
  email: '',
}).withPrecognition('post', '/api/users')
```

:::

Once enabled, the `validate()`, `touch()`, `touched()`, `valid()`, and `invalid()` methods become available, working identically to [form precognition](/guide/forms#precognition).

## History State

You may persist data and errors in browser history state by providing a remember key as the first argument.

:::tabs key:frameworks

\== Vue

```js
const http = useHttp('SearchData', {
  query: '',
})
```

\== React

```js
const http = useHttp('SearchData', {
  query: '',
})
```

\== Svelte

```js
const http = useHttp('SearchData', {
  query: '',
})
```

:::

You may exclude sensitive fields from being stored in history state using the `dontRemember()` method.

```js
const http = useHttp('Login', {
  email: '',
  token: '',
}).dontRemember('token')
```

---

---
url: /cookbook/inertia-modal.md
---
# Inertia Modal

[Inertia Modal](https://inertiaui.com/inertia-modal) is a powerful library that enables you to render any Inertia page
as a modal dialog. It seamlessly integrates with your existing Inertia Rails application, allowing you to create modal
workflows without the complexity of managing modal state manually.

Here's a summary of the features:

* Supports React and Vue
* Zero backend configuration
* Super simple frontend API
* Support for Base Route / URL
* Modal and slideover support
* Headless support
* Nested/stacked modals support
* Reusable modals
* Multiple sizes and positions
* Reload props in modals
* Easy communication between nested/stacked modals
* Prefetch support for faster modal loading
* Native HTML dialog support for better accessibility
* TypeScript type definitions included
* Highly configurable

While you can use Inertia Modal without changes on the backend, we recommend using the Rails gem
[`inertia_rails-contrib`](https://github.com/skryukov/inertia_rails-contrib) to enhance your modals with base URL support. This ensures that your modals are accessible,
SEO-friendly, and provide a better user experience.

> \[!NOTE]
> Svelte is not supported by Inertia Modal.

## Requirements

* React 19+ with `@inertiajs/react` 3.0+, or Vue 3.4+ with `@inertiajs/vue3` 3.0+ — Inertia Modal's major
  version follows the Inertia.js version it supports, so on Inertia.js v2, install Inertia Modal 2.x and
  follow the [2.x documentation](https://inertiaui.com/inertia-modal/docs/v2/introduction) instead
* Tailwind CSS 4 for the default modal UI. If you're on Tailwind CSS 3 (or don't use Tailwind at all), you can
  still use Inertia Modal in [headless mode](https://inertiaui.com/inertia-modal/docs/headless-mode) with your own UI.
* For base URL support: [`inertia_rails-contrib`](https://github.com/skryukov/inertia_rails-contrib) 0.6+

## Installation

### 1. Install the NPM Package

:::tabs key:frameworks
\== Vue

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

\== React

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

:::

Inertia Modal 3.0+ comes with TypeScript support.

### 2. Configure Inertia

Update your Inertia app setup to mount the modal root component:

:::tabs key:frameworks
\== Vue

```js
// app/frontend/entrypoints/inertia.js
import { createInertiaApp } from '@inertiajs/vue3'
import { withInertiaModal } from '@inertiaui/modal-vue' // [!code ++]

createInertiaApp({
  pages: '../pages',
  // [!code ++:3]
  withApp(app) {
    withInertiaModal(app)
  },
})
```

\== React

```jsx
// app/frontend/entrypoints/inertia.jsx
import { createInertiaApp } from '@inertiajs/react'
import { ModalStackProvider, ModalRoot } from '@inertiaui/modal-react' // [!code ++]

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

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

:::

> \[!NOTE]
> If your app already defines a `setup` callback, per-page layouts, or a `layout` option in `createInertiaApp`,
> render `<ModalRoot />` inside your existing layout component instead. See the
> [Custom App Mounting](https://inertiaui.com/inertia-modal/docs/custom-app-mounting) documentation for details.

> \[!TIP]
> In a TypeScript app, annotate the layout's `children` prop:
> `function ModalLayout({ children }: { children: React.ReactNode })`.

### 3. Tailwind CSS Configuration

The default modal UI is built for Tailwind CSS 4. Tell Tailwind to scan the package's source files by adding an
`@source` directive to your CSS entrypoint:

:::tabs key:frameworks
\== Vue

```css
/* app/frontend/entrypoints/application.css */
@source '../../../node_modules/@inertiaui/modal-vue/src';
```

\== React

```css
/* app/frontend/entrypoints/application.css */
@source '../../../node_modules/@inertiaui/modal-react/src';
```

:::

> \[!WARNING]
> The path must point to the `src` directory inside the package and must be relative to the CSS file itself.
> If your CSS entrypoint is located elsewhere, adjust the number of `../` segments accordingly, otherwise
> the modal will render without styles.

If you're on Tailwind CSS 3, the default UI is not supported — use
[headless mode](https://inertiaui.com/inertia-modal/docs/headless-mode) and provide your own markup.

### 4. Add the Ruby Gem (optional but recommended)

Install the [`inertia_rails-contrib`](https://github.com/skryukov/inertia_rails-contrib) gem to your Rails application
to enable base URL support for modals:

```bash
bundle add inertia_rails-contrib
```

Then, enable the InertiaUI Modal integration in an initializer:

```ruby
# config/initializers/inertia_rails_contrib.rb
InertiaRailsContrib.configure do |config|
  config.enable_inertia_ui_modal = true
end
```

## Basic example

The package comes with two components: `Modal` and `ModalLink`. `ModalLink` is very similar to Inertia's [built-in
`Link` component](/guide/links), but it opens the linked route in a modal instead of a full page load. So, if you have a
link that you want to open in a modal, you can simply replace `Link` with `ModalLink`.

:::tabs key:frameworks
\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3' // [!code --]
import { ModalLink } from '@inertiaui/modal-vue' // [!code ++]
</script>

<template>
  <!-- [!code --] -->
  <Link href="/users/create">Create User</Link>
  <!-- [!code ++] -->
  <ModalLink href="/users/create">Create User</ModalLink>
</template>
```

\== React

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

export const CreateUserButton = () => {
  return (
    <Link href="/users/create">Create User</Link> // [!code --]
    <ModalLink href="/users/create">Create User</ModalLink> // [!code ++]
  )
}
```

:::

The page you linked can then use the `Modal` component to wrap its content in a modal.

:::tabs key:frameworks
\== Vue

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

<template>
  <!-- [!code ++] -->
  <Modal>
    <h1>Create User</h1>
    <form>
      <!-- Form fields -->
    </form>
    <!-- [!code ++] -->
  </Modal>
</template>
```

\== React

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

export const CreateUser = () => {
  return (
    {/* [!code --] */}
    <>
    {/* [!code ++] */}
    <Modal>
      <h1>Create User</h1>
      <form>
        {/* Form fields */}
      </form>
      {/* [!code --] */}
    </Modal>
    {/* [!code ++] */}
    </>
  )
}
```

:::

That's it! There is no need to change anything about your routes or controllers!

## Enhanced Usage With Base URL Support

By default, Inertia Modal doesn't change the URL when opening a modal. It just stays on the same page and displays the
modal content. However, you may want to change this behavior and update the URL when opening a modal. This has a few
benefits:

* It allows users to bookmark the modal and share the URL with others.
* The modal becomes part of the browser history, so users can use the back and forward buttons.
* It makes the modal content accessible to search engines (when using [SSR](/guide/server-side-rendering)).
* It allows you to open the modal in a new tab.

> \[!NOTE]
> To enable this feature, you need to use the [`inertia_rails-contrib`](https://github.com/skryukov/inertia_rails-contrib) gem, which provides base URL support for modals.

## Define a Base Route

To define the base route for your modal, you need to use the `inertia_modal` renderer in your controller instead of the
`inertia` one. It accepts the same arguments as the `inertia` renderer:

```ruby
class UsersController < ApplicationController
  def edit
    render inertia: { # [!code --]
    render inertia_modal: { # [!code ++]
      user:,
      roles: -> { Role.all },
    }
  end
end
```

Then, you can pass the `base_url` parameter to the `inertia_modal` renderer to define the base route for your modal:

```ruby
class UsersController < ApplicationController
  def edit
    render inertia_modal: {
      user:,
      roles: -> { Role.all },
    } # [!code --]
    }, base_url: users_path # [!code ++]
  end
end
```

> \[!WARNING] Reusing the Modal URL with different Base Routes
> The `base_url` parameter acts merely as a fallback when the modal is directly opened using a URL. If you open the
> modal from a different route, the URL will be generated based on the current route.

## Open a Modal with a Base Route

Finally, the frontend needs to know that we're using the browser history to navigate between modals. To do this, you need
to add the `navigate` attribute to the `ModalLink` component:

:::tabs key:frameworks
\== Vue

```vue
<template>
  <ModalLink navigate href="/users/create"> Create User </ModalLink>
</template>
```

\== React

```jsx
export default function UserIndex() {
  return (
    <ModalLink navigate href="/users/create">
      Create User
    </ModalLink>
  )
}
```

:::

Now, when you click the "Create User" link, it will open the modal and update the URL to `/users/create`.

## Further Reading

For advanced usage, configuration options, and additional features, check out [the official Inertia Modal documentation](https://inertiaui.com/inertia-modal/docs).

---

---
url: /guide/starter-kits.md
---
# Inertia Rails Starter Kits

## Overview

Inertia Rails starter kits provide modern, full-stack scaffolding for building Rails applications with React, Vue, or Svelte frontends using Inertia.js. These starter kits are inspired by Laravel's starter kit ecosystem and offer the fastest way to begin building Inertia-powered Rails applications.

## Key Features

* [Inertia Rails](https://inertia-rails.dev) & [Vite Rails](https://vite-ruby.netlify.app) setup
* [React](https://react.dev) frontend with TypeScript & [shadcn/ui](https://ui.shadcn.com) component library
* User authentication system (based on [Authentication Zero](https://github.com/lazaronixon/authentication-zero))
* [Kamal](https://kamal-deploy.org/) for deployment
* Optional SSR support

## Available Starter Kits

### React Starter Kit

**Repository:** [inertia-rails/react-starter-kit](https://github.com/inertia-rails/react-starter-kit)

### Vue Starter Kit

**Repository:** [inertia-rails/vue-starter-kit](https://github.com/inertia-rails/vue-starter-kit)

### Svelte Starter Kit

**Repository:** [inertia-rails/svelte-starter-kit](https://github.com/inertia-rails/svelte-starter-kit)

## Getting Started

Each starter kit repository includes detailed setup instructions. The typical workflow:

1. Clone the desired starter kit repository
2. Run `bin/setup`

---

---
url: /guide/infinite-scroll.md
---
# Infinite Scroll

Inertia's infinite scroll feature loads additional pages of content as users scroll, replacing traditional pagination controls. This is great for applications like chat interfaces, social feeds, photo grids, and product listings.

## Server-Side

To configure your paginated data for infinite scrolling, you should use the `InertiaRails.scroll` method when returning your response. This method automatically configures the proper merge behavior and normalizes pagination metadata for the frontend component.

:::tabs key:pagination\_gems

\== Pagy

```ruby
class UsersController < ApplicationController
  include Pagy::Method

  def index
    pagy, records = pagy(:countless, User.all)

    render inertia: {
      users: InertiaRails.scroll(pagy) { records.as_json(...) }
    }
  end
end
```

\== Kaminari

```ruby

class UsersController < ApplicationController
  def index
    users = User.page(params[:page])

    render inertia: {
      # Pass collection to the scroll method to extract pagination metadata
      users: InertiaRails.scroll(users) { users.as_json(...) },
    }
  end
end
```

\== Manual

```ruby
class UsersController < ApplicationController
  def index
    meta, users = paginate(User.order(:name))

    render inertia: {
      users: InertiaRails.scroll(meta) { users.as_json(...) }
    }
  end

  private

  PER_PAGE = 20

  def paginate(scope, page_param: :page)
    page = [params.fetch(page_param, 1).to_i, 1].max

    records = scope.offset((page - 1) * PER_PAGE).limit(PER_PAGE + 1)

    meta = {
      page_name: page_param.to_s,
      previous_page: page > 1 ? page - 1 : nil,
      next_page: records.length > PER_PAGE ? page + 1 : nil,
      current_page: page
    }

    [meta, records.first(PER_PAGE)]
  end
end
```

:::

The `InertiaRails.scroll` method works with [Pagy](https://github.com/ddnexus/pagy) and [Kaminari](https://github.com/kaminari/kaminari) gems out of the box. For more details, check out the [`InertiaRails.scroll` method](#inertiarails-scroll-method) documentation.

## Client-Side

On the client side, Inertia provides the `<InfiniteScroll>` component to automatically load additional pages of content. The component accepts a `data` prop that specifies the key of the prop containing your paginated data. The `<InfiniteScroll>` component should wrap the content that depends on the paginated data.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { InfiniteScroll } from '@inertiajs/vue3'

defineProps({ users: Array })
</script>

<template>
  <InfiniteScroll data="users">
    <div v-for="user in users" :key="user.id">
      {{ user.name }}
    </div>
  </InfiniteScroll>
</template>
```

\== React

```jsx
import { InfiniteScroll } from '@inertiajs/react'

export default function Users({ users }) {
  return (
    <InfiniteScroll data="users">
      {users.map((user) => (
        <div key={user.id}>{user.name}</div>
      ))}
    </InfiniteScroll>
  )
}
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll } from '@inertiajs/svelte'
  let { users } = $props()
</script>

<InfiniteScroll data="users">
  {#each users as user (user.id)}
    <div>{user.name}</div>
  {/each}
</InfiniteScroll>
```

:::

The component uses [intersection observers](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to detect when users scroll near the end of the content and automatically triggers requests to load the next page. New data is merged with existing content rather than replacing it.

## Loading Buffer

You can control how early content begins loading by setting a buffer distance. The buffer specifies how many pixels before the end of the content loading should begin.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users" :buffer="500">
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users" buffer={500}>
  {/* ... */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users" buffer={500}>
  <!-- ... -->
</InfiniteScroll>
```

:::

In the example above, content will start loading 500 pixels before reaching the end of the current content. A larger buffer loads content earlier but potentially loads content that users may never see.

## URL Synchronization

The infinite scroll component updates the browser URL's query string (`?page=...`) as users scroll through content. The URL reflects which page has the most visible items on screen, updating in both directions as users scroll up or down. This allows users to bookmark or share links to specific pages. You can disable this behavior to maintain the original page URL.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users" preserve-url>
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users" preserveUrl>
  {/* ... */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users" preserve-url>
  <!-- ... -->
</InfiniteScroll>
```

:::

This is useful when infinite scroll is used for secondary content that shouldn't affect the main page URL, such as comments on a blog post or related products on a product page.

## Resetting

When filters or other parameters change, you may need to reset the infinite scroll data to start from the beginning. Without resetting, new results will merge with existing content instead of replacing it.

You can reset data using the `reset` visit option.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { router } from '@inertiajs/vue3'

const show = (role) => {
  router.visit(route('users'), {
    data: { filter: { role } },
    only: ['users'],
    reset: ['users'],
  })
}
</script>

<template>
  <button @click="show('admin')">Show admins</button>
  <button @click="show('customer')">Show customers</button>

  <InfiniteScroll data="users">
    <div v-for="user in users" :key="user.id">
      {{ user.name }}
    </div>
  </InfiniteScroll>
</template>
```

\== React

```jsx
import { InfiniteScroll, router } from '@inertiajs/react'

export default function Users({ users }) {
  const show = (role) => {
    router.visit(route('users'), {
      data: { filter: { role } },
      only: ['users'],
      reset: ['users'],
    })
  }

  return (
    <>
      <button onClick={() => show('admin')}>Show admins</button>
      <button onClick={() => show('customer')}>Show customers</button>

      <InfiniteScroll data="users">
        {users.map((user) => (
          <div key={user.id}>{user.name}</div>
        ))}
      </InfiniteScroll>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll, router } from '@inertiajs/svelte'
  let { users } = $props()

  const show = (role) => {
    router.visit(route('users'), {
      data: { filter: { role } },
      only: ['users'],
      reset: ['users'],
    })
  }
</script>

<button onclick={() => show('admin')}>Show admins</button>
<button onclick={() => show('customer')}>Show customers</button>

<InfiniteScroll data="users">
  {#each users as user (user.id)}
    <div>{user.name}</div>
  {/each}
</InfiniteScroll>
```

:::

For more information about the reset option, see the [Resetting props](/guide/merging-props#resetting-props) documentation.

## Loading Direction

The infinite scroll component loads content in both directions when you scroll near the start or end. You can control this behavior using the `only-next` and `only-previous` props.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <!-- Only load the next page -->
  <InfiniteScroll data="users" only-next>
    <!-- ... -->
  </InfiniteScroll>

  <!-- Only load the previous page -->
  <InfiniteScroll data="messages" only-previous>
    <!-- ... -->
  </InfiniteScroll>

  <!-- Load in both directions (default) -->
  <InfiniteScroll data="posts">
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
/* Only load the next page */
export default () => (
<InfiniteScroll data="users" onlyNext>
  {/* ... */}
</InfiniteScroll>
)

/* Only load the previous page */
export default () => (
<InfiniteScroll data="messages" onlyPrevious>
  {/* ... */}
</InfiniteScroll>
)

/* Load in both directions (default) */
export default () => (
<InfiniteScroll data="posts">{/* ... */}</InfiniteScroll>
)
```

\== Svelte

```svelte
<!-- Only load the next page -->
<InfiniteScroll data="users" only-next>
  <!-- ... -->
</InfiniteScroll>

<!-- Only load the previous page -->
<InfiniteScroll data="messages" only-previous>
  <!-- ... -->
</InfiniteScroll>

<!-- Load in both directions (default) -->
<InfiniteScroll data="posts">
  <!-- ... -->
</InfiniteScroll>
```

:::

The default option is particularly useful when users start on a middle page and need to scroll in both directions to access all content.

## Reverse Mode

For chat applications, timelines, or interfaces where content is sorted descendingly (newest items at the bottom), you can enable reverse mode. This configures the component to load older content when scrolling upward.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="messages" reverse>
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="messages" reverse>
  {/* ... */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="messages" reverse>
  <!-- ... -->
</InfiniteScroll>
```

:::

In reverse mode, the component flips the loading directions so that scrolling up loads the next page (older content) and scrolling down loads the previous page (newer content). The component handles the loading positioning, but you are responsible for reversing your content to display in the correct order.

Reverse mode also enables automatic scrolling to the bottom on initial load, which you can disable with `:auto-scroll="false"``autoScroll={false}``auto-scroll={false}`.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="messages" reverse :auto-scroll="false">
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="messages" reverse autoScroll={false}>
  {/* ... */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="messages" reverse auto-scroll={false}>
  <!-- ... -->
</InfiniteScroll>
```

:::

## Manual Mode

Manual mode disables automatic loading when scrolling and allows you to control when content loads through the `next` and `previous` slots. For more details about available slot properties and customization options, see the [Slots](#slots) documentation.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users" manual>
    <template #previous="{ loading, fetch, hasMore }">
      <button v-if="hasMore" @click="fetch" :disabled="loading">
        {{ loading ? 'Loading...' : 'Load previous' }}
      </button>
    </template>

    <!-- Your content -->

    <template #next="{ loading, fetch, hasMore }">
      <button v-if="hasMore" @click="fetch" :disabled="loading">
        {{ loading ? 'Loading...' : 'Load more' }}
      </button>
    </template>
  </InfiniteScroll>
</template>
```

\== React

```jsx
import { InfiniteScroll } from '@inertiajs/react'

export default ({ users }) => (
  <InfiniteScroll
    data="users"
    manual
    previous={({ loading, fetch, hasMore }) =>
      hasMore && (
        <button onClick={fetch} disabled={loading}>
          {loading ? 'Loading...' : 'Load previous'}
        </button>
      )
    }
    next={({ loading, fetch, hasMore }) =>
      hasMore && (
        <button onClick={fetch} disabled={loading}>
          {loading ? 'Loading...' : 'Load more'}
        </button>
      )
    }
  >
    {users.map((user) => (
      <div key={user.id}>{user.name}</div>
    ))}
  </InfiniteScroll>
)
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll } from '@inertiajs/svelte'
  let { users } = $props()
</script>

<InfiniteScroll data="users" manual>
  {#snippet previous({ hasMore, fetch, loading })}
    {#if hasMore}
      <button onclick={fetch} disabled={loading}>
        {loading ? 'Loading...' : 'Load previous'}
      </button>
    {/if}
  {/snippet}

  {#each users as user (user.id)}
    <div>{user.name}</div>
  {/each}

  {#snippet next({ hasMore, fetch, loading })}
    {#if hasMore}
      <button onclick={fetch} disabled={loading}>
        {loading ? 'Loading...' : 'Load more'}
      </button>
    {/if}
  {/snippet}
</InfiniteScroll>
```

:::

You can also configure the component to automatically switch to manual mode after a certain number of pages using the `:manual-after``manualAfter``manual-after` prop.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users" :manual-after="3">
    <!-- ... -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users" manualAfter={3}>
  {/* ... */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users" manual-after={3}>
  <!-- ... -->
</InfiniteScroll>
```

:::

## Slots

The infinite scroll component provides several slots to customize the loading experience. These slots allow you to display custom loading indicators and create manual load controls. Each slot receives properties that provide loading state information and functions to trigger content loading.

### Default Slot

The main content area where you render your data items. This slot receives loading state information.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll
    data="users"
    #default="{ loading, loadingPrevious, loadingNext }"
  >
    <!-- Your content with access to loading states -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users">
  {({ loading, loadingPrevious, loadingNext }) => (
    <div>{/* Your content with access to loading states */}</div>
  )}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users">
  {#snippet children({ loading, loadingPrevious, loadingNext })}
    <!-- Your content with access to loading states -->
  {/snippet}
</InfiniteScroll>
```

:::

### Loading Slot

The loading slot is used as a fallback when loading content and no custom `before` or `after` slots are provided. This creates a default loading indicator.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users">
    <!-- Your content -->
    <template #loading> Loading more users... </template>
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users" loading={() => 'Loading more users...'}>
  {/* Your content */}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users">
  <!-- Your content -->

  {#snippet loading()}
    Loading more users...
  {/snippet}
</InfiniteScroll>
```

:::

### Previous and Next Slots

The `previous` and `next` slots are rendered above and below the main content, typically used for manual load controls. These slots receive several properties including loading states, fetch functions, and mode indicators.

:::tabs key:frameworks
\== Vue

```vue
<template>
  <InfiniteScroll data="users" :manual-after="3">
    <template #previous="{ loading, fetch, hasMore, manualMode }">
      <button v-if="manualMode && hasMore" @click="fetch" :disabled="loading">
        {{ loading ? 'Loading...' : 'Load previous' }}
      </button>
    </template>

    <!-- Your content -->

    <template #next="{ loading, fetch, hasMore, manualMode }">
      <button v-if="manualMode && hasMore" @click="fetch" :disabled="loading">
        {{ loading ? 'Loading...' : 'Load more' }}
      </button>
    </template>
  </InfiniteScroll>
</template>
```

\== React

```jsx
import { InfiniteScroll } from '@inertiajs/react'

export default ({ users }) => (
  <InfiniteScroll
    data="users"
    manual
    previous={({ loading, fetch, hasMore, manualMode }) =>
      manualMode &&
      hasMore && (
        <button onClick={fetch} disabled={loading}>
          {loading ? 'Loading...' : 'Load previous'}
        </button>
      )
    }
    next={({ loading, fetch, hasMore, manualMode }) =>
      manualMode &&
      hasMore && (
        <button onClick={fetch} disabled={loading}>
          {loading ? 'Loading...' : 'Load more'}
        </button>
      )
    }
  >
    {users.map((user) => (
      <div key={user.id}>{user.name}</div>
    ))}
  </InfiniteScroll>
)
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll } from '@inertiajs/svelte'
  let { users } = $props()
</script>

<InfiniteScroll data="users" manual>
  {#snippet previous({ hasMore, fetch, loading, manualMode })}
    {#if manualMode && hasMore}
      <button onclick={fetch} disabled={loading}>
        {loading ? 'Loading...' : 'Load previous'}
      </button>
    {/if}
  {/snippet}
  {#each users as user (user.id)}
    <div>{user.name}</div>
  {/each}
  {#snippet next({ hasMore, fetch, loading, manualMode })}
    {#if manualMode && hasMore}
      <button onclick={fetch} disabled={loading}>
        {loading ? 'Loading...' : 'Load more'}
      </button>
    {/if}
  {/snippet}
</InfiniteScroll>
```

:::

The `loading`, `previous`, and `next` slots receive the following properties:

| Property          | Description                                    |
| :---------------- | :--------------------------------------------- |
| `loading`         | Whether the slot is currently loading content  |
| `loadingPrevious` | Whether previous content is loading            |
| `loadingNext`     | Whether next content is loading                |
| `fetch`           | Function to trigger loading for the slot       |
| `hasMore`         | Whether more content is available for the slot |
| `hasPrevious`     | Whether more previous content is available     |
| `hasNext`         | Whether more next content is available         |
| `manualMode`      | Whether manual mode is active                  |
| `autoMode`        | Whether automatic loading is active            |

## Custom Element

The `InfiniteScroll` component renders as a `<div>` element. You may customize this to use any HTML element using the `as` prop.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="products" as="ul">
    <li v-for="product in products" :key="product.id">
      {{ product.name }}
    </li>
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="products" as="ul">
  {products.map((product) => (
    <li key={product.id}>{product.name}</li>
  ))}
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="products" as="ul">
  {#each products as product (product.id)}
    <li>{product.name}</li>
  {/each}
</InfiniteScroll>
```

:::

## Element Targeting

The infinite scroll component automatically tracks content and assigns page numbers to elements for [URL synchronization](#url-synchronization). When your data items are not direct children of the component's root element, you need to specify which element contains the actual data items using the `items-element``itemsElement``items-element` prop.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll data="users" items-element="#table-body">
    <table>
      <thead>
        <tr>
          <th>Name</th>
        </tr>
      </thead>
      <tbody id="table-body">
        <tr v-for="user in users" :key="user.id">
          <td>{{ user.name }}</td>
        </tr>
      </tbody>
    </table>
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll data="users" itemsElement="#table-body">
  <table>
    <thead>
      <tr>
        <th>Name</th>
      </tr>
    </thead>
    <tbody id="table-body">
      {users.map((user) => (
        <tr key={user.id}>
          <td>{user.name}</td>
        </tr>
      ))}
    </tbody>
  </table>
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll data="users" items-element="#table-body">
  <table>
    <thead>
      <tr><th>Name</th></tr>
    </thead>
    <tbody id="table-body">
      {#each users as user (user.id)}
        <tr>
          <td>{user.name}</td>
        </tr>
      {/each}
    </tbody>
  </table>
</InfiniteScroll>
```

:::

In this example, the component monitors the `#table-body` element and automatically tags each `<tr>` with a page number as new content loads. This enables proper URL updates based on which page's content is most visible in the viewport.

You can also specify custom trigger elements for loading more content using CSS selectors. This prevents the default trigger elements from being rendered and uses intersection observers on your custom elements instead.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <InfiniteScroll
    data="users"
    items-element="#table-body"
    start-element="#table-header"
    end-element="#table-footer"
  >
    <table>
      <thead id="table-header">
        <tr>
          <th>Name</th>
        </tr>
      </thead>
      <tbody id="table-body">
        <tr v-for="user in users" :key="user.id">
          <td>{{ user.name }}</td>
        </tr>
      </tbody>
      <tfoot id="table-footer">
        <tr>
          <td>Footer</td>
        </tr>
      </tfoot>
    </table>
  </InfiniteScroll>
</template>
```

\== React

```jsx
<InfiniteScroll
  data="users"
  itemsElement="#table-body"
  startElement="#table-header"
  endElement="#table-footer"
>
  <table>
    <thead id="table-header">
      <tr>
        <th>Name</th>
      </tr>
    </thead>
    <tbody id="table-body">
      {users.map((user) => (
        <tr key={user.id}>
          <td>{user.name}</td>
        </tr>
      ))}
    </tbody>
    <tfoot id="table-footer">
      <tr>
        <td>Footer</td>
      </tr>
    </tfoot>
  </table>
</InfiniteScroll>
```

\== Svelte

```svelte
<InfiniteScroll
  data="users"
  items-element="#table-body"
  start-element="#table-header"
  end-element="#table-footer"
>
  <table>
    <thead id="table-header">
      <tr><th>Name</th></tr>
    </thead>
    <tbody id="table-body">
      {#each users as user (user.id)}
        <tr>
          <td>{user.name}</td>
        </tr>
      {/each}
    </tbody>
    <tfoot id="table-footer">
      <tr><td>Footer</td></tr>
    </tfoot>
  </table>
</InfiniteScroll>
```

:::

Alternatively, you can use template refs instead of CSS selectors. This avoids adding HTML attributes and provides direct element references.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { ref } from 'vue'
const tableHeader = ref()
const tableFooter = ref()
const tableBody = ref()
</script>

<template>
  <InfiniteScroll
    data="users"
    :items-element="() => tableBody"
    :start-element="() => tableHeader"
    :end-element="() => tableFooter"
  >
    <table>
      <thead ref="tableHeader">
        <tr>
          <th>Name</th>
        </tr>
      </thead>
      <tbody ref="tableBody">
        <tr v-for="user in users" :key="user.id">
          <td>{{ user.name }}</td>
        </tr>
      </tbody>
      <tfoot ref="tableFooter">
        <tr>
          <td>Footer</td>
        </tr>
      </tfoot>
    </table>
  </InfiniteScroll>
</template>
```

\== React

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

export default ({ users }) => {
  const tableHeader = useRef()
  const tableFooter = useRef()
  const tableBody = useRef()

  return (
    <InfiniteScroll
      data="users"
      itemsElement={tableBody}
      startElement={tableHeader}
      endElement={tableFooter}
    >
      <table>
        <thead ref={tableHeader}>
          <tr>
            <th>Name</th>
          </tr>
        </thead>
        <tbody ref={tableBody}>
          {users.map((user) => (
            <tr key={user.id}>
              <td>{user.name}</td>
            </tr>
          ))}
        </tbody>
        <tfoot ref={tableFooter}>
          <tr>
            <td>Footer</td>
          </tr>
        </tfoot>
      </table>
    </InfiniteScroll>
  )
}
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll } from '@inertiajs/svelte'
  let { users } = $props()

  let tableHeader
  let tableFooter
  let tableBody
</script>

<InfiniteScroll
  data="users"
  items-element={() => tableBody}
  start-element={() => tableHeader}
  end-element={() => tableFooter}
>
  <table>
    <thead bind:this={tableHeader}>
      <tr><th>Name</th></tr>
    </thead>
    <tbody bind:this={tableBody}>
      {#each users as user (user.id)}
        <tr>
          <td>{user.name}</td>
        </tr>
      {/each}
    </tbody>
    <tfoot bind:this={tableFooter}>
      <tr><td>Footer</td></tr>
    </tfoot>
  </table>
</InfiniteScroll>
```

:::

## Scroll Containers

The infinite scroll component works within any scrollable container, not just the main document. The component automatically adapts to use the custom scroll container for trigger detection and calculations instead of the main document scroll.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <div style="height: 400px; overflow-y: auto;">
    <InfiniteScroll data="users">
      <div v-for="user in users" :key="user.id">
        {{ user.name }}
      </div>
    </InfiniteScroll>
  </div>
</template>
```

\== React

```jsx
<div style={{ height: '400px', overflowY: 'auto' }}>
  <InfiniteScroll data="users">
    {users.map((user) => (
      <div key={user.id}>{user.name}</div>
    ))}
  </InfiniteScroll>
</div>
```

\== Svelte

```svelte
<div style="height: 400px; overflow-y: auto;">
  <InfiniteScroll data="users">
    {#each users as user (user.id)}
      <div>{user.name}</div>
    {/each}
  </InfiniteScroll>
</div>
```

:::

### Multiple Scroll Containers

Sometimes you may need to render multiple infinite scroll components on a single page. However, if both components use the default `page` query parameter for [URL synchronization](#url-synchronization), they will conflict with each other. To resolve this, instruct each paginator to use a custom `page_name`.

:::tabs key:pagination\_gems

\== Pagy

```ruby
class DashboardController < ApplicationController
  include Pagy::Method

  def index
    pagy_users, users = pagy(:countless, User.all, page_key: 'users')
    pagy_orders, orders = pagy(:countless, Order.all, page_key: 'orders')

    render inertia: {
      users: InertiaRails.scroll(pagy_users) { users.as_json(...) },
      orders: InertiaRails.scroll(pagy_orders) { orders.as_json(...) }
    }
  end
end
```

\== Kaminari

```ruby

class DashboardController < ApplicationController
  def index
    users = User.page(params[:users])
    orders = Order.page(params[:orders])

    render inertia: {
      users: InertiaRails.scroll(users, page_name: 'users') { users.as_json(...) },
      orders: InertiaRails.scroll(orders, page_name: 'orders') { orders.as_json(...) }
    }
  end
end
```

\== Manual

```ruby
class DashboardController < ApplicationController
  def index
    users_meta, users = paginate(User.order(:name), page_param: :users)
    orders_meta, orders = paginate(Order.order(:created_at), page_param: :orders)

    render inertia: {
      users: InertiaRails.scroll(users_meta) { users.as_json(...) },
      orders: InertiaRails.scroll(orders_meta) { orders.as_json(...) }
    }
  end

  private

  PER_PAGE = 20

  def paginate(scope, page_param: :page)
    page = [params.fetch(page_param, 1).to_i, 1].max

    records = scope.offset((page - 1) * PER_PAGE).limit(PER_PAGE + 1)

    meta = {
      page_name: page_param.to_s,
      previous_page: page > 1 ? page - 1 : nil,
      next_page: records.length > PER_PAGE ? page + 1 : nil,
      current_page: page
    }

    [meta, records.first(PER_PAGE)]
  end
end
```

:::

The `InertiaRails.scroll` method automatically detects the `page_name` from each paginator metadata, allowing both scroll containers to maintain independent pagination state. This results in URLs like `?users=2&orders=3` instead of conflicting `?page=` parameters.

## Programmatic Access

When you need to trigger loading actions programmatically, you may use a template ref.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { ref } from 'vue'
const infiniteScrollRef = ref(null)

const fetchNext = () => {
  infiniteScrollRef.value?.fetchNext()
}
</script>

<template>
  <button @click="fetchNext">Load More</button>

  <InfiniteScroll ref="infiniteScrollRef" data="users" manual>
    <!-- Your content -->
  </InfiniteScroll>
</template>
```

\== React

```jsx
import { InfiniteScroll } from '@inertiajs/react'
import { useRef } from 'react'

export default ({ users }) => {
  const infiniteScrollRef = useRef(null)

  const fetchNext = () => {
    infiniteScrollRef.current?.fetchNext()
  }

  return (
    <>
      <button onClick={fetchNext}>Load More</button>

      <InfiniteScroll ref={infiniteScrollRef} data="users" manual>
        {users.map((user) => (
          <div key={user.id}>{user.name}</div>
        ))}
      </InfiniteScroll>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { InfiniteScroll } from '@inertiajs/svelte'
  let { users } = $props()

  let infiniteScrollRef

  const fetchNext = () => {
    infiniteScrollRef?.fetchNext()
  }
</script>

<button onclick={fetchNext}>Load More</button>

<InfiniteScroll bind:this={infiniteScrollRef} data="users" manual>
  {#each users as user (user.id)}
    <div>{user.name}</div>
  {/each}
</InfiniteScroll>
```

:::

The component exposes the following methods:

* `fetchNext()` - Manually fetch the next page
* `fetchPrevious()` - Manually fetch the previous page
* `hasNext()` - Whether there is a next page
* `hasPrevious()` - Whether there is a previous page

## `InertiaRails.scroll` method

The `InertiaRails.scroll` method provides server-side configuration for infinite scrolling. It automatically configures the proper merge behavior so that new data is appended or prepended to existing content instead of replacing it, and normalizes pagination metadata for the frontend component.

```ruby
# Works with Pagy...
InertiaRails.scroll(pagy_instance) { records.as_json(...) }

# Works with Kaminari...
InertiaRails.scroll(kaminari_collection) { kaminari_collection.as_json(...) }

# Works with hash metadata...
InertiaRails.scroll(metadata_hash) { data.as_json(...) }
```

If you don't use Pagy or Kaminari, or need custom pagination behavior, you may use the additional options that `scroll()` accepts.

### Hash Metadata

When using custom pagination libraries or manual pagination, you can provide pagination metadata as a hash:

```ruby
class UsersController < ApplicationController
  def index
    page = params[:page]&.to_i || 1
    users = User.offset((page - 1) * 20).limit(21)
    has_more = users.count > 20

    metadata = {
      page_name: 'page',
      current_page: page,
      previous_page: page > 1 ? page - 1 : nil,
      next_page: has_more ? page + 1 : nil
    }

    render inertia: {
      users: InertiaRails.scroll(metadata) { users.first(20).as_json(...) }
    }
  end
end
```

The hash must include all required keys: `page_name`, `current_page`, `previous_page`, and `next_page`.

### Custom Pagination Adapters

If you're using a pagination library that isn't supported out of the box, you can create and register a custom adapter:

```ruby
class CustomPaginatorAdapter
  def match?(metadata)
    metadata.is_a?(CustomPaginator)
  end

  def call(metadata, **options)
    {
      page_name: options[:page_name] || 'page',
      previous_page: metadata.has_previous? ? metadata.previous_page_number : nil,
      next_page: metadata.has_next? ? metadata.next_page_number : nil,
      current_page: metadata.current_page_number
    }
  end
end

# Register the adapter (typically in an initializer)
InertiaRails::ScrollMetadata.register_adapter(CustomPaginatorAdapter)
```

Adapters are checked in reverse registration order, so custom adapters registered later will take precedence over built-in adapters.

### Overriding Attributes

You can override any of the default attributes by passing a hash of options.

```ruby
class UsersController < ApplicationController
  def index
    users = User.page(params[:page])

    render inertia: {
      users: InertiaRails.scroll(users, page_name: 'page_number') do
        users.as_json(...)
      end
    }
  end
end
```

### Wrapper Option

The `wrapper` option allows you to specify a custom key for nested data structures. This is useful when your data is wrapped in an object with metadata:

```ruby
class UsersController < ApplicationController
  def index
    users = User.page(params[:page])

    render inertia: {
      users: InertiaRails.scroll(users, wrapper: 'items') do
        {
          items: users.as_json(...),
          metadata: { total: users.total_count }
        }
      end
    }
  end
end
```

This example demonstrates how the `wrapper` option works with nested data structures, ensuring that only the `items` array gets merged during infinite scrolling while preserving the `metadata` object.

---

---
url: /guide/instant-visits.md
---
# Instant Visits

@available\_since core=3.0.0

Sometimes you may wish to navigate to a new page without waiting for the server to respond. Instant visits allow Inertia to immediately swap to the target page component while the server request happens in the background. Once the server responds, the real props are merged in.

Unlike [client-side visits](/guide/manual-visits#client-side-visits), which update the page entirely on the client without making a server request, instant visits still make a full server request. The difference is that the user sees the target page right away instead of waiting for the response.

## Basic Usage

To make an instant visit, provide the target `component` name to a `Link` or to `router.visit()`.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/dashboard" component="dashboard/index">Dashboard</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/dashboard" component="dashboard/index">
    Dashboard
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/dashboard" use:inertia={{ component: 'dashboard/index' }}>
  Dashboard
</a>

<Link href="/dashboard" component="dashboard/index">Dashboard</Link>
```

:::

When clicked, Inertia immediately renders the `dashboard/index` component while the server request fires in the background. The full props are merged in when the response arrives.

The target component must be able to render without its page-specific props, as only [shared props](/guide/shared-data) are available on the intermediate page. You may use optional chaining or conditional rendering to handle missing props.

Programmatic instant visits work the same way via the `component` option on `router.visit()`.

```js
router.visit('/dashboard', {
  component: 'dashboard/index',
})
```

## Shared Props

The Rails adapter includes a `sharedProps` metadata key in the page response, listing the top-level prop keys registered via [`inertia_share`](/guide/shared-data).

```json lines
{
  "component": "dashboard/index",
  "props": {
    "auth": { "user": "..." },
    "stats": {
      /*...*/
    }
  },
  "sharedProps": ["auth"]
}
```

Inertia reads this list and carries those props over from the current page to the intermediate page. Props like `auth` are available immediately, while page-specific props like `stats` will be `undefined` until the server responds.

## Page Props

You may provide props for the intermediate page using the `pageProps` option. This is useful for passing data you already have on the current page, or for setting placeholder values to display loading states while the server responds.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link
    href="/posts/1"
    component="posts/show"
    :page-props="{ title: 'Loading...' }"
  >
    View Post
  </Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link
    href="/posts/1"
    component="posts/show"
    pageProps={{ title: 'Loading...' }}
  >
    View Post
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { Link } from '@inertiajs/svelte'
</script>

<Link
  href="/posts/1"
  component="posts/show"
  pageProps={{ title: 'Loading...' }}
>
  View Post
</Link>
```

:::

When `pageProps` is provided as an object, shared props are not automatically carried over. You are in full control of the intermediate page's props.

A callback may also be passed to `pageProps`. The callback receives the current page's props and the shared props as arguments, so you may selectively spread them.

```js
router.visit('/posts/1', {
  component: 'posts/show',
  pageProps: (currentProps, sharedProps) => ({
    ...sharedProps,
    title: 'Loading...',
  }),
})
```

## Disabling Shared Prop Keys

You may disable the `sharedProps` metadata key in your configuration. The server will still resolve and include shared prop values in the response, but the metadata listing which keys are shared will be omitted. Without this list, the client cannot identify which props to carry over during instant visits.

```ruby
# config/initializers/inertia_rails.rb

InertiaRails.configure do |config|
  config.expose_shared_prop_keys = false
end
```

---

---
url: /guide/instrumentation.md
---
# Instrumentation

Inertia Rails emits [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) events around rendering, prop resolution, and SSR requests. Subscribe to them to trace rendering with OpenTelemetry or AppSignal, log slow pages, or measure how much time your prop blocks take.

@available\_since rails=3.23.0

## Events

Events fire on every Inertia render. When no subscribers are attached, the overhead is negligible, so there is nothing to enable or disable.

| Event                         | Wraps                                               | Payload                      |
| ----------------------------- | --------------------------------------------------- | ---------------------------- |
| `render.inertia_rails`        | The entire Inertia render, including view rendering | `:component, :partial, :ssr` |
| `resolve_props.inertia_rails` | Prop resolution, where your prop blocks execute     | `:component, :partial`       |
| `ssr.inertia_rails`           | The HTTP call to the SSR server                     | `:url, :component`           |

The payload keys:

* `:component` — the resolved page component name, such as `"users/show"`.
* `:partial` — `true` on [partial reloads](/guide/partial-reloads).
* `:ssr` — `true` when the response body came from [SSR](/guide/server-side-rendering). It stays `false` for JSON responses, when SSR is disabled, and when a failed SSR call falls back to client-side rendering.
* `:url` — the SSR server endpoint the request was sent to.

> \[!NOTE]
> A [cached SSR response](/guide/caching#ssr-response-caching) emits no `ssr.inertia_rails` event — the cache read is visible through Rails' own `cache_read.active_support` event instead.

If an instrumented block raises, ActiveSupport records the error in the payload under `:exception` and `:exception_object` before re-raising, so failed SSR calls are observable without any extra configuration.

## Subscribing

Use the standard ActiveSupport API to consume the events:

```ruby
ActiveSupport::Notifications.subscribe('ssr.inertia_rails') do |event|
  Rails.logger.info("SSR render of #{event.payload[:component]} took #{event.duration.round(1)}ms")
end
```

## OpenTelemetry

The [opentelemetry-instrumentation-active\_support](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/active_support) gem converts the events into spans nested inside your request traces:

```ruby
tracer = OpenTelemetry.tracer_provider.tracer('inertia_rails')

%w[render.inertia_rails resolve_props.inertia_rails ssr.inertia_rails].each do |event|
  OpenTelemetry::Instrumentation::ActiveSupport.subscribe(tracer, event)
end
```

Each span carries the payload as attributes, so you can group latency by page component, alert on SSR error rates, or see which SQL queries run inside prop resolution. This is also the path to any backend that ingests OpenTelemetry traces, such as Datadog or Sentry.

## APMs

AppSignal needs no wiring: its [Ruby agent](https://docs.appsignal.com/ruby/instrumentation/instrumentation.html) records `ActiveSupport::Notifications` events automatically, and they appear in the timeline of each performance sample grouped under `inertia_rails`. New Relic subscribes natively once you list the event names in [`active_support_custom_events_names`](https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#active_support_custom_events_names). Other APMs consume the events through the OpenTelemetry setup above or their own tracing APIs.

---

---
url: /cookbook/integrating-shadcn-ui.md
---
# Integrating `shadcn/ui`

This guide demonstrates how to integrate [shadcn/ui](https://ui.shadcn.com) - a collection of reusable React components - with your Inertia Rails application.

## Getting Started in 5 Minutes

If you're starting fresh, create a new Rails application with Inertia (or skip this step if you already have one):

:::tabs key:languages

\== TypeScript

```bash
rails new -JA shadcn-inertia-rails
cd shadcn-inertia-rails

bundle add inertia_rails

rails generate inertia:install --framework=react --typescript --vite --tailwind --no-interactive
Installing Inertia's Rails adapter
...
```

\== JavaScript

```bash
rails new -JA shadcn-inertia-rails
cd shadcn-inertia-rails

bundle add inertia_rails

rails generate inertia:install --framework=react --vite --tailwind --no-interactive
Installing Inertia's Rails adapter
...
```

:::

> \[!NOTE]
> You can also run `rails generate inertia:install` to run the installer interactively.
> Need more details on the initial setup? Check out our [server-side setup guide](/guide/server-side-setup.md).

## Setting Up Path Aliases

Let's configure our project to work seamlessly with `shadcn/ui`. Choose your path based on whether you're using TypeScript or JavaScript.

:::tabs key:languages

\== TypeScript

You'll need to configure two files. First, update your `tsconfig.app.json`:

```json lines
{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["./app/frontend/*"]
    }
  }
  // ...
}
```

Then, set up your `tsconfig.json` to match `shadcn/ui`'s requirements (note the `baseUrl` and `paths` properties are different from the `tsconfig.app.json`):

```json lines
{
  //...
  "compilerOptions": {
    /* Required for shadcn-ui/ui */
    "baseUrl": "./app/frontend",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

\== JavaScript

Using JavaScript? It's even simpler! Just create a `jsconfig.json`:

```json
{
  "compilerOptions": {
    "baseUrl": "./app/frontend",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

:::

## Initializing `shadcn/ui`

Now you can initialize `shadcn/ui` with a single command:

```bash
npx shadcn@latest init

✔ Preflight checks.
✔ Verifying framework. Found Vite.
✔ Validating Tailwind CSS.
✔ Validating import alias.
✔ Which style would you like to use? › New York
✔ Which color would you like to use as the base color? › Neutral
✔ Would you like to use CSS variables for theming? … no / yes
✔ Writing components.json.
✔ Checking registry.
✔ Updating tailwind.config.js
✔ Updating app/frontend/entrypoints/application.css
✔ Installing dependencies.
✔ Created 1 file:
  - app/frontend/lib/utils.js

Success! Project initialization completed.
You may now add components.
```

You're all set! Want to try it out? Add your first component:

```shell
npx shadcn@latest add button
```

Now you can import and use your new button component from `@/components/ui/button`. Happy coding!

> \[!NOTE]
> Check out the [`shadcn/ui` components gallery](https://ui.shadcn.com/docs/components/accordion) to explore all the beautiful components at your disposal.

## Troubleshooting

If you're using `vite` and see this error `No Tailwind CSS configuration found at path....` (but do have a `tailwind.config.js`) ensure you've imported the CSS properly.

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

Reference: [Link to Common Github Issue](https://github.com/shadcn-ui/ui/issues/4677)

---

---
url: /guide.md
---

# Introduction

Welcome to the documentation for [inertia\_rails](https://github.com/inertiajs/inertia-rails) adapter for [Ruby on Rails](https://rubyonrails.org/) and [Inertia.js](https://inertiajs.com/).

## Why adapter-specific documentation?

The [official documentation for Inertia.js](https://inertiajs.com) is great, but it's not Rails-specific anymore (see the [legacy docs](https://legacy.inertiajs.com)). This documentation aims to fill in the gaps and provide Rails-specific examples and explanations.

## JavaScript apps the monolith way

Inertia is a new approach to building classic server-driven web apps. We call it the modern monolith.

Inertia allows you to create fully client-side rendered, single-page apps, without the complexity that comes with modern SPAs. It does this by leveraging existing server-side patterns that you already love.

Inertia has no client-side routing, nor does it require an API. Simply build controllers and page views like you've always done! Inertia works great with any backend framework — it was fine-tuned for [Laravel](https://laravel.com), so naturally we had to fine-tune it for [Ruby on Rails](https://rubyonrails.org/) too.

## Not a Framework

Inertia isn't a framework, nor is it a replacement for your existing server-side or client-side frameworks. Rather, it's designed to work with them. Think of Inertia as glue that connects the two. Inertia does this via adapters. We currently have three official client-side adapters (React, Vue, and Svelte) and four server-side adapters (Laravel, Rails, Phoenix, and Django).

## Support Policy

> \[!NOTE]
> The `inertia_rails` gem has been on 3.x for years — long before Inertia.js itself reached 3.x. When Inertia.js 4.x arrives, we'll bump the gem to 4.x to align major version numbers and this policy going forward.

Inertia.js follows the same support policy as [Laravel](https://laravel.com/docs/releases#support-policy). When a new major version is released, the previous version receives bug fixes for 6 months and security fixes for 12 months. Inertia.js v3 was released on March 26, 2026.

| Version | Bug Fixes Until    | Security Fixes Until |
| ------- | ------------------ | -------------------- |
| 0.x     | End of life        | End of life          |
| 1.x     | End of life        | End of life          |
| 2.x     | September 26, 2026 | March 26, 2027       |
| 3.x     | TBD                | TBD                  |

## Next Steps

Want to learn a bit more before diving in? Check out the [who is it for](/guide/who-is-it-for) and [how it works](/guide/how-it-works) pages. Or, if you're ready to get started, jump right into the [installation instructions](/guide/server-side-setup).

---

---
url: /guide/layouts.md
---
# Layouts

Most applications share common UI elements across pages, such as a primary navigation bar, sidebar, or footer. Layout components let you define this shared UI once and wrap your pages with it automatically.

## Creating Layouts

A layout is a standard component that accepts child content. There is nothing Inertia-specific about it.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <main>
    <header>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
      <Link href="/contact">Contact</Link>
    </header>
    <article>
      <slot />
    </article>
  </main>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default function Layout({ children }) {
  return (
    <main>
      <header>
        <Link href="/">Home</Link>
        <Link href="/about">About</Link>
        <Link href="/contact">Contact</Link>
      </header>
      <article>{children}</article>
    </main>
  )
}
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'

  let { children } = $props()
</script>

<main>
  <header>
    <a use:inertia href="/">Home</a>
    <a use:inertia href="/about">About</a>
    <a use:inertia href="/contact">Contact</a>
  </header>
  <article>
    {@render children()}
  </article>
</main>
```

:::

You may use a layout by wrapping your page content with it directly. However, this approach forces the layout instance to be destroyed and recreated between visits.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import Layout from './Layout'

defineProps({ user: Object })
</script>

<template>
  <Layout>
    <h1>Welcome</h1>
    <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
  </Layout>
</template>
```

\== React

```jsx
import Layout from './Layout'

export default function Welcome({ user }) {
  return (
    <Layout>
      <h1>Welcome</h1>
      <p>Hello {user.name}, welcome to your first Inertia app!</p>
    </Layout>
  )
}
```

\== Svelte

```svelte
<script>
  import Layout from './Layout.svelte'

  let { user } = $props()
</script>

<Layout>
  <h1>Welcome</h1>
  <p>Hello {user.name}, welcome to your first Inertia app!</p>
</Layout>
```

:::

## Persistent Layouts

Wrapping a page with a layout as a child component works, but it means the layout is destroyed and recreated on every visit. This prevents maintaining layout state across navigations, such as an audio player that should keep playing or a sidebar that should retain its scroll position.

Persistent layouts solve this by telling Inertia which layout to use for a page. Inertia then manages the layout instance separately, keeping it alive between visits.

:::tabs key:frameworks

\== Vue

```vue
<script>
import Layout from './Layout'

export default {
  layout: Layout,
}
</script>

<script setup>
defineProps({ user: Object })
</script>

<template>
  <h1>Welcome</h1>
  <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
</template>
```

\== React

```jsx
import Layout from './Layout'

const Welcome = ({ user }) => {
  return (
    <>
      <h1>Welcome</h1>
      <p>Hello {user.name}, welcome to your first Inertia app!</p>
    </>
  )
}

Welcome.layout = (page) => <Layout>{page}</Layout>

export default Welcome
```

\== Svelte

```svelte
<script module>
  export { default as layout } from './Layout.svelte'
</script>

<script>
  let { user } = $props()
</script>

<h1>Welcome</h1><p>Hello {user.name}, welcome to your first Inertia app!</p>
```

:::

Vue 3.3+ users may alternatively use [defineOptions](https://vuejs.org/api/sfc-script-setup.html#defineoptions) to define a layout within `<script setup>`:

```vue
<script setup>
import Layout from './Layout'
defineOptions({ layout: Layout })
</script>
```

Arrow function components should be wrapped in an array. Without the array, Inertia cannot distinguish them from render functions at runtime:

```jsx
const ArrowLayout = ({ children }) => <main>{children}</main>

Welcome.layout = [ArrowLayout]
```

### Nested Layouts

You may create more complex layout arrangements using nested layouts. Pass an array of layout components to wrap the page in multiple layers.

:::tabs key:frameworks

\== Vue

```vue
<script>
import SiteLayout from './SiteLayout'
import NestedLayout from './NestedLayout'

export default {
  layout: [SiteLayout, NestedLayout],
}
</script>

<script setup>
defineProps({ user: Object })
</script>

<template>
  <h1>Welcome</h1>
  <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
</template>
```

\== React

```jsx
import SiteLayout from './SiteLayout'
import NestedLayout from './NestedLayout'

const Welcome = ({ user }) => {
  return (
    <>
      <h1>Welcome</h1>
      <p>Hello {user.name}, welcome to your first Inertia app!</p>
    </>
  )
}

Welcome.layout = [SiteLayout, NestedLayout]

export default Welcome
```

\== Svelte

```svelte
<script module>
  import SiteLayout from './SiteLayout.svelte'
  import NestedLayout from './NestedLayout.svelte'

  export const layout = [SiteLayout, NestedLayout]
</script>

<script>
  let { user } = $props()
</script>

<h1>Welcome</h1><p>Hello {user.name}, welcome to your first Inertia app!</p>
```

:::

## Default Layouts

@available\_since core=3.0.0

The `layout` option in `createInertiaApp` lets you define a default layout for all pages, saving you from defining it on every page individually. Per-page layouts always take precedence over the default.

```js
import Layout from './Layout'

createInertiaApp({
  layout: () => Layout,
  // ...
})
```

You may also conditionally return a layout based on the page name. For example, you may wish to exclude public pages from the default layout.

```js
import Layout from './Layout'

createInertiaApp({
  layout: (name) => {
    if (name.startsWith('public/')) {
      return null
    }

    return Layout
  },
  // ...
})
```

The full page object is also available as the second argument, giving you access to the page's URL, props, and other metadata.

The `layout` callback supports all layout formats, including arrays for [nested layouts](#nested-layouts), named objects for [named layouts](#targeting-named-layouts), and tuples for [static props](#static-props).

### Using the Resolve Callback

You may also set a default layout inside the `resolve` callback by mutating the resolved page component. The callback receives the component name and the full page object, which is useful when you need to conditionally apply layouts based on page data.

:::tabs key:frameworks

\== Vue

```js
import Layout from './Layout'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.vue', { eager: true })
    let page = pages[`../pages/${name}.vue`]
    page.default.layout = page.default.layout || Layout
    return page
  },
  // ...
})
```

\== React

```jsx
import Layout from './Layout'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.jsx', { eager: true })
    let page = pages[`../pages/${name}.jsx`]
    page.default.layout =
      page.default.layout || ((page) => <Layout>{page}</Layout>)
    return page
  },
  // ...
})
```

\== Svelte

```js
import Layout from './Layout'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.svelte', { eager: true })
    let page = pages[`../pages/${name}.svelte`]
    return { default: page.default, layout: page.layout || Layout }
  },
  // ...
})
```

:::

## Layout Props

Persistent layouts often need dynamic data from the current page, such as a page title, the active navigation item, or a sidebar toggle. Layout props provide a way to define defaults in your layout and override them from any page.

### Defining Defaults

Layout props are defined as regular component props with default values.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
const props = withDefaults(defineProps<{
    title?: string
    showSidebar?: boolean
}>(), {
    title: 'My App',
    showSidebar: true,
})
</script>

<template>
  <header>{{ title }}</header>
  <aside v-if="showSidebar">Sidebar</aside>
  <main>
    <slot />
  </main>
</template>
```

\== React

```jsx
export default function Layout({
  title = 'My App',
  showSidebar = true,
  children,
}) {
  return (
    <>
      <header>{title}</header>
      {showSidebar && <aside>Sidebar</aside>}
      <main>{children}</main>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  let { title = 'My App', showSidebar = true, children } = $props()
</script>

<header>{title}</header>
{#if showSidebar}
  <aside>Sidebar</aside>
{/if}
<main>
  {@render children()}
</main>
```

:::

### Static Props

You may pass static props directly in your persistent layout definition using a tuple. These props are set once when the layout is defined and don't change between page navigations.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import Layout from './Layout'

defineProps({ user: Object })
defineOptions({
  layout: [Layout, { title: 'Dashboard' }],
})
</script>

<template>
  <h1>Dashboard</h1>
</template>
```

\== React

```jsx
import Layout from './Layout'

const Dashboard = ({ user }) => {
  return <h1>Dashboard</h1>
}

Dashboard.layout = [Layout, { title: 'Dashboard' }]

export default Dashboard
```

\== Svelte

```svelte
<script module>
  import Layout from './Layout.svelte'

  export const layout = [Layout, { title: 'Dashboard' }]
</script>

<script>
  let { user } = $props()
</script>

<h1>Dashboard</h1>
```

:::

### Callback Props

Sometimes layout props need to be derived from the current page's props. A callback function receives the page props and returns a layout definition with computed static props.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import Layout from './Layout'

defineOptions({
  layout: (props) => [Layout, { title: 'Profile: ' + props.auth.user.name }],
})
</script>

<template>
  <h1>Profile</h1>
</template>
```

\== React

```jsx
import Layout from './Layout'

const Profile = () => {
  return <h1>Profile</h1>
}

Profile.layout = (props) => [
  Layout,
  { title: 'Profile: ' + props.auth.user.name },
]

export default Profile
```

\== Svelte

```svelte
<script module>
  import Layout from './Layout.svelte'

  export const layout = (props) => [
    Layout,
    { title: 'Profile: ' + props.auth.user.name },
  ]
</script>

<h1>Profile</h1>
```

:::

The callback receives the page's props and may return any valid layout format: a single component, a tuple with static props, an array for nested layouts, or a named layout object. TypeScript users may use the [`LayoutCallback`](/guide/typescript#layout-callbacks) type for type safety.

#### Returning Props Only

When a [default layout](#default-layouts) is configured in `createInertiaApp`, callbacks may return a plain props object instead of a full layout definition. Inertia will automatically use the default layout and merge the returned props onto it.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
defineOptions({
  layout: (props) => ({
    title: 'Profile: ' + props.auth.user.name,
    showSidebar: false,
  }),
})
</script>

<template>
  <h1>Profile</h1>
</template>
```

\== React

```jsx
const Profile = () => {
  return <h1>Profile</h1>
}

Profile.layout = (props) => ({
  title: 'Profile: ' + props.auth.user.name,
  showSidebar: false,
})

export default Profile
```

\== Svelte

```svelte
<script module>
  export const layout = (props) => ({
    title: 'Profile: ' + props.auth.user.name,
    showSidebar: false,
  })
</script>

<h1>Profile</h1>
```

:::

A static object may also be used when the props don't depend on page data.

```js
Dashboard.layout = { title: 'Dashboard', showSidebar: true }
```

### Dynamic Props

You may also update layout props dynamically from any page component using the `setLayoutProps` function. TypeScript users may [type these props](/guide/typescript#layout-props) globally.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { setLayoutProps } from '@inertiajs/vue3'

setLayoutProps({
  title: 'Dashboard',
  showSidebar: false,
})
</script>

<template>
  <h1>Dashboard</h1>
</template>
```

\== React

```jsx
import { setLayoutProps } from '@inertiajs/react'

export default function Dashboard() {
  setLayoutProps({
    title: 'Dashboard',
    showSidebar: false,
  })

  return <h1>Dashboard</h1>
}
```

\== Svelte

```svelte
<script>
  import { setLayoutProps } from '@inertiajs/svelte'

  setLayoutProps({
    title: 'Dashboard',
    showSidebar: false,
  })
</script>

<h1>Dashboard</h1>
```

:::

### Targeting Named Layouts

[Nested layouts](#nested-layouts) may also be defined as a named object instead of an array, allowing you to target specific layouts with props.

:::tabs key:frameworks

\== Vue

```vue
<script>
import AppLayout from './AppLayout'
import ContentLayout from './ContentLayout'

export default {
  layout: {
    app: AppLayout,
    content: ContentLayout,
  },
}
</script>
```

\== React

```jsx
import AppLayout from './AppLayout'
import ContentLayout from './ContentLayout'

Dashboard.layout = {
  app: AppLayout,
  content: ContentLayout,
}
```

\== Svelte

```svelte
<script module>
  import AppLayout from './AppLayout.svelte'
  import ContentLayout from './ContentLayout.svelte'

  export const layout = {
    app: AppLayout,
    content: ContentLayout,
  }
</script>
```

:::

You may target a specific named layout by passing the layout name as the first argument to `setLayoutProps`.

:::tabs key:frameworks

\== Vue

```js
import { setLayoutProps } from '@inertiajs/vue3'

setLayoutProps('sidebar', {
  collapsed: true,
})
```

\== React

```js
import { setLayoutProps } from '@inertiajs/react'

setLayoutProps('sidebar', {
  collapsed: true,
})
```

\== Svelte

```js
import { setLayoutProps } from '@inertiajs/svelte'

setLayoutProps('sidebar', {
  collapsed: true,
})
```

:::

[Nested layouts](#nested-layouts) and named layouts may also include static props using the tuple syntax.

```js
// Nested layouts with static props
Dashboard.layout = [
  [AppLayout, { title: 'Dashboard' }],
  [ContentLayout, { padding: 'sm' }],
]

// Named layouts with static props
Dashboard.layout = {
  app: [AppLayout, { theme: 'dark' }],
  content: [ContentLayout, { padding: 'sm' }],
}
```

### Merge Priority

Layout props are resolved from multiple sources with the following priority (highest to lowest):

1. **Dynamic props** - set via `setLayoutProps()`
2. **Static props** - defined in the persistent layout definition (including [callback props](#callback-props))
3. **Defaults** - declared as default values on the layout component's props

### Auto-Reset on Navigation

Dynamic layout props are automatically reset when navigating to a new page (unless `preserveState` is enabled). This ensures each page starts with a clean slate and only the layout props explicitly set by that page are applied.

### Resetting Props

You may also manually reset all dynamic layout props using `resetLayoutProps`.

:::tabs key:frameworks

\== Vue

```js
import { resetLayoutProps } from '@inertiajs/vue3'

resetLayoutProps()
```

\== React

```js
import { resetLayoutProps } from '@inertiajs/react'

resetLayoutProps()
```

\== Svelte

```js
import { resetLayoutProps } from '@inertiajs/svelte'

resetLayoutProps()
```

:::

---

---
url: /guide/links.md
---
# Links

To create links to other pages within an Inertia app, you will typically use the Inertia `<Link>` component. This component is a light wrapper around a standard anchor `<a>` link that intercepts click events and prevents full page reloads. This is [how Inertia provides a single-page app experience](/guide/how-it-works) once your application has been loaded.

## Creating Links

To create an Inertia link, use the Inertia `<Link>` component. Any attributes you provide to this component will be proxied to the underlying HTML tag.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/">Home</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => <Link href="/">Home</Link>
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/" use:inertia>Home</a>

<Link href="/">Home</Link>
```

:::

By default, Inertia renders links as anchor `<a>` elements. However, you can change the tag using the `as` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/logout" method="post" as="button">Logout</Link>
  <!-- Renders as... -->
  <!--  <button type="button">Logout</button> -->
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/logout" method="post" as="button">
    Logout
  </Link>
)

// Renders as...
// <button type="button">Logout</button>
```

\== Svelte

```svelte
<script>
  import { Link } from '@inertiajs/svelte'
</script>

<Link href="/logout" method="post" as="button">Logout</Link>

<!-- Renders as... -->
<!-- <button type="button">Logout</button> -->
```

:::

> \[!NOTE]
> Creating `POST/PUT/PATCH/DELETE` anchor `<a>` links is discouraged as it causes "Open Link in New Tab / Window" accessibility issues. The component automatically renders a `<button>` element when using these methods.

## Method

You can specify the HTTP request method for an Inertia link request using the `method` prop. The default method used by links is `GET`, but you can use the `method` prop to make `POST`, `PUT`, `PATCH`, and `DELETE` requests via links.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/logout" method="post" as="button">Logout</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/logout" method="post" as="button">
    Logout
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<button use:inertia={{ href: '/logout', method: 'post' }} type="button">
  Logout
</button>

<Link href="/logout" method="post">Logout</Link>
```

:::

## Typelizer

When using [Typelizer route helpers](/guide/routing#typelizer) with the `Link` component, you can pass the resulting object directly to the `href` prop. The `Link` will infer the HTTP method and URL from the object. This works with any object that has `url` and `method` keys.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
import { users } from '@/routes'
</script>

<template>
  <Link :href="users.show(1)">John Doe</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'
import { users } from '@/routes'

export default () => <Link href={users.show(1)}>John Doe</Link>
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
  import { users } from '@/routes'
</script>

<button use:inertia={{ href: users.show(1) }} type="button">John Doe</button>

<Link href={users.show(1)}>John Doe</Link>
```

:::

## Data

When making `POST` or `PUT` requests, you may wish to add additional data to the request. You can accomplish this using the `data` prop. The provided data can be an `object` or `FormData` instance.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/endpoint" method="post" as="button" :data="{ foo: bar }">
    Save
  </Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/endpoint" method="post" as="button" data={{ foo: bar }}>
    Save
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<button
  use:inertia={{ href: '/endpoint', method: 'post', data: { foo: bar } }}
  type="button"
>
  Save
</button>

<Link href="/endpoint" method="post" data={{ foo: bar }}>Save</Link>
```

:::

## Custom Headers

The `headers` prop allows you to add custom headers to an Inertia link. However, the headers Inertia uses internally to communicate its state to the server take priority and therefore cannot be overwritten.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/endpoint" :headers="{ foo: bar }">Save</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/endpoint" headers={{ foo: bar }}>
    Save
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<button use:inertia={{ href: '/endpoint', headers: { foo: bar } }}>Save</button>

<Link href="/endpoint" headers={{ foo: bar }}>Save</Link>
```

:::

## Browser History

The `replace` prop allows you to specify the browser's history behavior. By default, page visits push (new) state (`window.history.pushState`) into the history; however, it's also possible to replace state (`window.history.replaceState`) by setting the `replace` prop to `true`. This will cause the visit to replace the current history state instead of adding a new history state to the stack.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/" replace>Home</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/" replace>
    Home
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/" use:inertia={{ replace: true }}>Home</a>

<Link href="/" replace>Home</Link>
```

:::

## State Preservation

You can preserve a page component's local state using the `preserveState` prop. This will prevent a page component from fully re-rendering. The `preserveState` prop is especially helpful on pages that contain forms, since you can avoid manually repopulating input fields and can also maintain a focused input.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <input v-model="query" type="text" />

  <Link href="/search" :data="{ query }" preserve-state>Search</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <>
    <input onChange={this.handleChange} value={query} type="text" />

    <Link href="/search" data={query} preserveState>
      Search
    </Link>
  </>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<input bind:value={query} type="text" />

<button use:inertia={{ href: '/search', data: { query }, preserveState: true }}>
  Search
</button>

<Link href="/search" data={{ query }} preserveState>Search</Link>
```

:::

## Scroll Preservation

You can use the `preserveScroll` prop to prevent Inertia from automatically resetting the scroll position when making a page visit.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/" preserve-scroll>Home</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/" preserveScroll>
    Home
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/" use:inertia={{ preserveScroll: true }}>Home</a>

<Link href="/" preserveScroll>Home</Link>
```

:::

For more information on managing scroll position, check out the documentation on [scroll management](/guide/scroll-management).

## Partial Reloads

The `only` prop allows you to specify that only a subset of a page's props (data) should be retrieved from the server on subsequent visits to that page.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users?active=true" :only="['users']">Show active</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users?active=true" only={['users']}>
    Show active
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/users?active=true" use:inertia={{ only: ['users'] }}>Show active</a>

<Link href="/users?active=true" only={['users']}>Show active</Link>
```

:::

For more information on this topic, check out the complete documentation on [partial reloads](/guide/partial-reloads).

## View Transitions

You may enable [View transitions](/guide/view-transitions) for a link by setting the `viewTransition` prop to `true`. This will use the browser's View Transitions API to animate the page transition.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/another-page" view-transition>Navigate</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/another-page" viewTransition>
    Navigate
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { Link } from '@inertiajs/svelte'
</script>

<Link href="/another-page" viewTransition>Navigate</Link>
```

:::

## Active States

It's common to set an active state for navigation links based on the current page. This can be accomplished when using Inertia by inspecting the `page` object and doing string comparisons against the `page.url` and `page.component` properties.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <!-- URL exact match...-->
  <Link href="/users" :class="{ active: $page.url === '/users' }">Users</Link>

  <!-- Component exact match...-->
  <Link href="/users" :class="{ active: $page.component === 'users/index' }">
    Users
  </Link>

  <!-- URL starts with (/users, /users/create, /users/1, etc.)...-->
  <Link href="/users" :class="{ active: $page.url.startsWith('/users') }">
    Users
  </Link>

  <!-- Component starts with (users/index, users/new, users/show, etc.)...-->
  <Link href="/users" :class="{ active: $page.component.startsWith('users/') }">
    Users
  </Link>
</template>
```

\== React

```jsx
import { Link, usePage } from '@inertiajs/react'

export default () => {
  const { url, component } = usePage()

  return (
    <>
      {/* URL exact match... */}
      <Link href="/users" className={url === '/users' ? 'active' : ''}>
        Users
      </Link>
      {/* Component exact match... */}
      <Link
        href="/users"
        className={component === 'users/index' ? 'active' : ''}
      >
        Users
      </Link>
      {/* URL starts with (/users, /users/create, /users/1, etc.)... */}
      <Link href="/users" className={url.startsWith('/users') ? 'active' : ''}>
        Users
      </Link>
      {/* Component starts with (users/index, users/new, users/show, etc.)... */}
      <Link
        href="/users"
        className={component.startsWith('users/') ? 'active' : ''}
      >
        Users
      </Link>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { inertia, Link, page } from '@inertiajs/svelte'
</script>

<!-- URL exact match... -->
<a href="/users" use:inertia class:active={page.url === '/users'}>Users</a>

<!-- Component exact match... -->
<a href="/users" use:inertia class:active={page.component === 'users/index'}>
  Users
</a>

<!-- URL starts with (/users, /users/create, /users/1, etc.)... -->
<Link href="/users" class={page.url.startsWith('/users') ? 'active' : ''}>
  Users
</Link>

<!-- Component starts with (users/index, users/new, users/show, etc.)... -->
<Link href="/users" class={page.component.startsWith('users/') ? 'active' : ''}>
  Users
</Link>
```

:::

You can perform exact match comparisons (`===`), `startsWith()` comparisons (useful for matching a subset of pages), or even more complex comparisons using regular expressions.

Using this approach, you're not limited to just setting class names. You can use this technique to conditionally render any markup on active state, such as different link text or even an SVG icon that represents the link is active.

## Data Loading Attribute

While a link is making an active request, a `data-loading` attribute is added to the link element. This allows you to style the link while it's in a loading state. The attribute is removed once the request is complete.

---

---
url: /guide/load-when-visible.md
---
# Load When Visible

Inertia supports lazy loading data on scroll using the Intersection Observer API. It provides the `WhenVisible` component as a convenient way to load data when an element becomes visible in the viewport.

The `WhenVisible` component accepts a `data` prop that specifies the key of the prop to load. It also accepts a `fallback` prop that specifies a component to render while the data is loading. The `WhenVisible` component should wrap the component that depends on the data.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

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

    <div v-for="permission in permissions">
      <!-- ... -->
    </div>
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible data="permissions" fallback={() => <div>Loading...</div>}>
    <PermissionsChildComponent />
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { permissions } = $props()
</script>

<WhenVisible data="permissions">
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  {#each permissions as permission}
    <!-- ... -->
  {/each}
</WhenVisible>
```

:::

If you'd like to load multiple props when an element becomes visible, you can provide an array to the `data` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

<template>
  <WhenVisible :data="['teams', 'users']">
    <template #fallback>
      <div>Loading...</div>
    </template>

    <!-- Props are now loaded -->
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible data={['teams', 'users']} fallback={() => <div>Loading...</div>}>
    <ChildComponent />
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { teams, users } = $props()
</script>

<WhenVisible data={['teams', 'users']}>
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  <!-- Props are now loaded -->
</WhenVisible>
```

:::

## Loading Before Visible

If you'd like to start loading data before the element is visible, you can provide a value to the `buffer` prop. The buffer value is a number that represents the number of pixels before the element is visible.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

<template>
  <WhenVisible data="permissions" :buffer="500">
    <template #fallback>
      <div>Loading...</div>
    </template>

    <div v-for="permission in permissions">
      <!-- ... -->
    </div>
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible
    data="permissions"
    buffer={500}
    fallback={() => <div>Loading...</div>}
  >
    <PermissionsChildComponent />
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { permissions } = $props()
</script>

<WhenVisible data="permissions" buffer={500}>
  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}

  {#each permissions as permission}
    <!-- ... -->
  {/each}
</WhenVisible>
```

:::

In the above example, the data will start loading 500 pixels before the element is visible.

By default, the `WhenVisible` component wraps the fallback template in a `div` element so it can ensure the element is visible in the viewport. If you want to customize the wrapper element, you can provide the `as` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

<template>
  <WhenVisible data="products" as="span">
    <!-- ... -->
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible data="products" as="span">
    <ProductsChildComponent />
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { products } = $props()
</script>

<WhenVisible data="products" as="span">
  <!-- ... -->
</WhenVisible>
```

:::

## Always Trigger

By default, the `WhenVisible` component will only trigger once when the element becomes visible. If you want to always trigger the data loading when the element is visible, you can provide the `always` prop.

This is useful when you want to load data every time the element becomes visible, such as when the element is at the end of an infinite scroll list and you want to load more data. Alternatively, you can use the [Infinite scroll](/guide/infinite-scroll) component which handles this use case for you.

Note that if the data loading request is already in flight, the component will wait until it is finished to start the next request if the element is still visible in the viewport.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

<template>
  <WhenVisible data="products" always>
    <!-- ... -->
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible data="products" always>
    <ProductsChildComponent />
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { products } = $props()
</script>

<WhenVisible data="products" always>
  <!-- ... -->
</WhenVisible>
```

:::

### Fetching State

@available\_since core=2.3.2

The `WhenVisible` component exposes a `fetching` slot prop that you may use to display a loading indicator during subsequent requests. This is useful because the `fallback` is only shown on the initial load, while `fetching` allows you to indicate that data is being refreshed on subsequent loads.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenVisible } from '@inertiajs/vue3'
</script>

<template>
  <WhenVisible data="permissions" always>
    <template #default="{ fetching }">
      <PermissionsChildComponent />
      <div v-if="fetching">Refreshing...</div>
    </template>

    <template #fallback>
      <div>Loading...</div>
    </template>
  </WhenVisible>
</template>
```

\== React

```jsx
import { WhenVisible } from '@inertiajs/react'

export default () => (
  <WhenVisible data="permissions" always fallback={() => <div>Loading...</div>}>
    {({ fetching }) => (
      <>
        <PermissionsChildComponent />
        {fetching && <div>Refreshing...</div>}
      </>
    )}
  </WhenVisible>
)
```

\== Svelte

```svelte
<script>
  import { WhenVisible } from '@inertiajs/svelte'

  let { permissions } = $props()
</script>

<WhenVisible data="permissions" always>
  {#snippet children({ fetching })}
    <PermissionsChildComponent />
    {#if fetching}
      <div>Refreshing...</div>
    {/if}
  {/snippet}

  {#snippet fallback()}
    <div>Loading...</div>
  {/snippet}
</WhenVisible>
```

:::

## Preserving Errors

@available\_since core=3.0.0

The `WhenVisible` component sets `preserveErrors: true` by default, ensuring that validation errors are not cleared when it triggers a reload. You may override this via the `params` prop.

:::tabs key:frameworks

\== Vue

```vue
<WhenVisible data="comments" :params="{ preserveErrors: false }">
    <!-- ... -->
</WhenVisible>
```

\== React

```jsx
<WhenVisible data="comments" params={{ preserveErrors: false }}>
  {/* ... */}
</WhenVisible>
```

\== Svelte

```svelte
<WhenVisible data="comments" params={{ preserveErrors: false }}>
  <!-- ... -->
</WhenVisible>
```

:::

## Form Submissions

When submitting forms, you may want to use the `except` option to exclude the props that are being used by the `WhenVisible` component. This prevents the props from being reloaded when you get redirected back to the current page because of validation errors.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useForm, WhenVisible } from '@inertiajs/vue3'

const form = useForm({
  name: '',
  email: '',
})

function submit() {
  form.post('/users', {
    except: ['permissions'],
  })
}
</script>

<template>
  <form @submit.prevent="submit">
    <!-- ... -->
  </form>

  <WhenVisible data="permissions">
    <!-- ... -->
  </WhenVisible>
</template>
```

\== React

```jsx
import { useForm, WhenVisible } from '@inertiajs/react'

export default function CreateUser() {
  const { data, setData, post } = useForm({
    name: '',
    email: '',
  })

  function submit(e) {
    e.preventDefault()
    post('/users', {
      except: ['permissions'],
    })
  }

  return (
    <>
      <form onSubmit={submit}>{/* ... */}</form>

      <WhenVisible data="permissions">{/* ... */}</WhenVisible>
    </>
  )
}
```

\== Svelte

```svelte
<script>
  import { useForm, WhenVisible } from '@inertiajs/svelte'

  const form = useForm({
    name: '',
    email: '',
  })

  function submit(e) {
    e.preventDefault()
    form.post('/users', {
      except: ['permissions'],
    })
  }
</script>

<form onsubmit={submit}>
  <!-- ... -->
</form>

<WhenVisible data="permissions">
  <!-- ... -->
</WhenVisible>
```

:::

---

---
url: /guide/manual-visits.md
---
# Manual Visits

In addition to [creating links](/guide/links), it's also possible to manually make Inertia visits / requests programmatically via JavaScript. This is accomplished via the `router.visit()` method.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, {
  method: 'get',
  data: {},
  replace: false,
  preserveState: false,
  preserveScroll: false,
  only: [],
  except: [],
  headers: {},
  errorBag: null,
  forceFormData: false,
  queryStringArrayFormat: 'brackets',
  async: false,
  showProgress: true,
  fresh: false,
  reset: [],
  preserveUrl: false,
  prefetch: false,
  preserveErrors: false,
  viewTransition: false,
  component: null,
  pageProps: null,
  onCancelToken: (cancelToken) => {},
  onCancel: () => {},
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, {
  method: 'get',
  data: {},
  replace: false,
  preserveState: false,
  preserveScroll: false,
  only: [],
  except: [],
  headers: {},
  errorBag: null,
  forceFormData: false,
  queryStringArrayFormat: 'brackets',
  async: false,
  showProgress: true,
  fresh: false,
  reset: [],
  preserveUrl: false,
  prefetch: false,
  preserveErrors: false,
  viewTransition: false,
  component: null,
  pageProps: null,
  onCancelToken: (cancelToken) => {},
  onCancel: () => {},
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, {
  method: 'get',
  data: {},
  replace: false,
  preserveState: false,
  preserveScroll: false,
  only: [],
  except: [],
  headers: {},
  errorBag: null,
  forceFormData: false,
  queryStringArrayFormat: 'brackets',
  async: false,
  showProgress: true,
  fresh: false,
  reset: [],
  preserveUrl: false,
  prefetch: false,
  preserveErrors: false,
  viewTransition: false,
  component: null,
  pageProps: null,
  onCancelToken: (cancelToken) => {},
  onCancel: () => {},
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

:::

However, it's generally more convenient to use one of Inertia's shortcut request methods. These methods share all the same options as `router.visit()`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.get(url, data, options)
router.post(url, data, options)
router.put(url, data, options)
router.patch(url, data, options)
router.delete(url, options)
router.reload(options) // Uses the current URL
```

\== React

```js
import { router } from '@inertiajs/react'

router.get(url, data, options)
router.post(url, data, options)
router.put(url, data, options)
router.patch(url, data, options)
router.delete(url, options)
router.reload(options) // Uses the current URL
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.get(url, data, options)
router.post(url, data, options)
router.put(url, data, options)
router.patch(url, data, options)
router.delete(url, options)
router.reload(options) // Uses the current URL
```

:::

The `reload()` method is a convenient, shorthand method that automatically visits the current page with `preserveState` and `preserveScroll` both set to `true`, making it the perfect method to invoke when you just want to reload the current page's data.

## Method

When making manual visits, you may use the `method` option to set the request's HTTP method to `get`, `post`, `put`, `patch` or `delete`. The default method is `get`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, { method: 'post' })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, { method: 'post' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, { method: 'post' })
```

:::

## Typelizer

When using [Typelizer route helpers](/guide/routing#typelizer), you can pass the resulting object directly to any router method. The router will infer the HTTP method and URL from the object. This works with any object that has `url` and `method` keys.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'
import { users } from '@/routes'

router.visit(users.show(1))
router.post(users.create())
router.delete(users.destroy(1))
```

\== React

```js
import { router } from '@inertiajs/react'
import { users } from '@/routes'

router.visit(users.show(1))
router.post(users.create())
router.delete(users.destroy(1))
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'
import { users } from '@/routes'

router.visit(users.show(1))
router.post(users.create())
router.delete(users.destroy(1))
```

:::

If you provide both a route object and the `method` option, the `method` option will take precedence. For example, `resources` routes send both `PATCH` and `PUT` requests to `update`, so you can make a `PUT` request with the `update` helper.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'
import { users } from '@/routes'

router.visit(users.update(1), { method: 'put' })
```

\== React

```js
import { router } from '@inertiajs/react'
import { users } from '@/routes'

router.visit(users.update(1), { method: 'put' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'
import { users } from '@/routes'

router.visit(users.update(1), { method: 'put' })
```

:::

## Data

You may use the `data` option to add data to the request.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit('/users', {
  method: 'post',
  data: {
    name: 'John Doe',
    email: 'john.doe@example.com',
  },
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit('/users', {
  method: 'post',
  data: {
    name: 'John Doe',
    email: 'john.doe@example.com',
  },
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit('/users', {
  method: 'post',
  data: {
    name: 'John Doe',
    email: 'john.doe@example.com',
  },
})
```

:::

For convenience, the `get()`, `post()`, `put()`, and `patch()` methods all accept `data` as their second argument.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', {
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', {
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', {
  name: 'John Doe',
  email: 'john.doe@example.com',
})
```

:::

## Custom Headers

The `headers` option allows you to add custom headers to a request.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  headers: {
    'Custom-Header': 'value',
  },
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  headers: {
    'Custom-Header': 'value',
  },
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  headers: {
    'Custom-Header': 'value',
  },
})
```

:::

The headers Inertia uses internally to communicate its state to the server take priority and therefore cannot be overwritten.

## Global Visit Options

You may configure a `visitOptions` callback when [initializing your Inertia app](/guide/client-side-setup#configuring-defaults) to modify visit options globally for every request. The callback receives the target URL and the current visit options, and should return an object with any options you want to override.

:::tabs key:frameworks

\== Vue

```js
import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return {
        headers: {
          ...options.headers,
          'X-Custom-Header': 'value',
        },
      }
    },
  },
})
```

\== React

```js
import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return {
        headers: {
          ...options.headers,
          'X-Custom-Header': 'value',
        },
      }
    },
  },
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return {
        headers: {
          ...options.headers,
          'X-Custom-Header': 'value',
        },
      }
    },
  },
})
```

:::

## File Uploads

When making visits / requests that include files, Inertia will automatically convert the request data into a `FormData` object. If you would like the request to always use a `FormData` object, you may use the `forceFormData` option.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/companies', data, {
  forceFormData: true,
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/companies', data, {
  forceFormData: true,
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/companies', data, {
  forceFormData: true,
})
```

:::

For more information on uploading files, check out the dedicated [file uploads](/guide/file-uploads) documentation.

## Browser History

When making visits, Inertia automatically adds a new entry into the browser history. However, it's also possible to replace the current history entry by setting the `replace` option to `true`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.get('/users', { search: 'John' }, { replace: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.get('/users', { search: 'John' }, { replace: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.get('/users', { search: 'John' }, { replace: true })
```

:::

Visits made to the same URL automatically set `replace` to `true`.

## Client Side Visits

You can use the `router.push` and `router.replace` method to make client-side visits. This method is useful when you want to update the browser's history without making a server request.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.push({
  url: '/users',
  component: 'users/index',
  props: { search: 'John' },
  clearHistory: false,
  encryptHistory: false,
  preserveScroll: false,
  preserveState: false,
  errorBag: null,
  onSuccess: (page) => {},
  onError: (errors) => {},
  onFinish: (visit) => {},
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.push({
  url: '/users',
  component: 'users/index',
  props: { search: 'John' },
  clearHistory: false,
  encryptHistory: false,
  preserveScroll: false,
  preserveState: false,
  errorBag: null,
  onSuccess: (page) => {},
  onError: (errors) => {},
  onFinish: (visit) => {},
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.push({
  url: '/users',
  component: 'users/index',
  props: { search: 'John' },
  clearHistory: false,
  encryptHistory: false,
  preserveScroll: false,
  preserveState: false,
  errorBag: null,
  onSuccess: (page) => {},
  onError: (errors) => {},
  onFinish: (visit) => {},
})
```

:::

All the parameters are optional. By default, all passed parameters (except `errorBag`) will be merged with the current page. This means you are responsible for overriding the current page's URL, component, and props.

If you need access to the current page's props, you may pass a function to the `props` option. This function receives the current props (including any [once props](/guide/once-props)) and should return the new props.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.push({ url: '/users', component: 'users/index' })

router.replace({
  props: (currentProps) => ({ ...currentProps, search: 'John' }),
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.push({ url: '/users', component: 'users/index' })

router.replace({
  props: (currentProps) => ({ ...currentProps, search: 'John' }),
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.push({ url: '/users', component: 'users/index' })

router.replace({
  props: (currentProps) => ({ ...currentProps, search: 'John' }),
})
```

:::

@available\_since core=2.3.10

The function also receives [once props](/guide/once-props) as a second argument. This is useful when you want to replace all regular props while still preserving once props.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.replace({
  props: (currentProps, onceProps) => ({ ...onceProps, search: 'John' }),
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.replace({
  props: (currentProps, onceProps) => ({ ...onceProps, search: 'John' }),
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.replace({
  props: (currentProps, onceProps) => ({ ...onceProps, search: 'John' }),
})
```

:::

The `errorBag` option allows you to specify which error bag to use when handling validation errors in the `onError` callback.

Make sure that any route you push on the client side is also defined on the server side. If the user refreshes the page, the server will need to know how to render the page.

> \[!WARNING]
> Some browsers limit the number of `history.pushState()` and
> `history.replaceState()` calls allowed within a short time period. Inertia
> catches this error and logs it to the console, but the state update will be
> lost. Avoid calling `router.push()` or `router.replace()` too frequently, and
> consider debouncing or batching updates in high-frequency scenarios.

### Prop Helpers

@available\_since core=2.2.0

Inertia provides three helper methods for updating page props without making server requests. These methods are shortcuts to `router.replace()` and automatically set `preserveScroll` and `preserveState` to `true`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

// Replace a prop value...
router.replaceProp('user.name', 'Jane Smith')

// Append to an array prop...
router.appendToProp('messages', { id: 4, text: 'New message' })

// Prepend to an array prop...
router.prependToProp('tags', 'urgent')
```

\== React

```js
import { router } from '@inertiajs/react'

// Replace a prop value...
router.replaceProp('user.name', 'Jane Smith')

// Append to an array prop...
router.appendToProp('messages', { id: 4, text: 'New message' })

// Prepend to an array prop...
router.prependToProp('tags', 'urgent')
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

// Replace a prop value...
router.replaceProp('user.name', 'Jane Smith')

// Append to an array prop...
router.appendToProp('messages', { id: 4, text: 'New message' })

// Prepend to an array prop...
router.prependToProp('tags', 'urgent')
```

:::

All three methods support dot notation for nested props and can accept a callback function that receives the current value as the first argument and the current page props as the second argument.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.prependToProp('notifications', (current, props) => {
  return {
    id: Date.now(),
    message: `Hello ${props.user.name}`,
  }
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.prependToProp('notifications', (current, props) => {
  return {
    id: Date.now(),
    message: `Hello ${props.user.name}`,
  }
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.prependToProp('notifications', (current, props) => {
  return {
    id: Date.now(),
    message: `Hello ${props.user.name}`,
  }
})
```

:::

## State Preservation

By default, page visits to the same page create a fresh page component instance. This causes any local state, such as form inputs, scroll positions, and focus states to be lost.

However, in some situations, it's necessary to preserve the page component state. For example, when submitting a form, you need to preserve your form data in the event that form validation fails on the server.

For this reason, the `post`, `put`, `patch`, `delete`, and `reload` methods all set the `preserveState` option to `true` by default.

You can instruct Inertia to preserve the component's state when using the `get` method by setting the `preserveState` option to `true`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.get('/users', { search: 'John' }, { preserveState: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.get('/users', { search: 'John' }, { preserveState: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.get('/users', { search: 'John' }, { preserveState: true })
```

:::

If you'd like to only preserve state if the response includes validation errors, set the `preserveState` option to "errors".

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.get('/users', { search: 'John' }, { preserveState: 'errors' })
```

\== React

```js
import { router } from '@inertiajs/react'

router.get('/users', { search: 'John' }, { preserveState: 'errors' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.get('/users', { search: 'John' }, { preserveState: 'errors' })
```

:::

You can also lazily evaluate the `preserveState` option based on the response by providing a callback.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  preserveState: (page) => page.props.someProp === 'value',
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  preserveState: (page) => page.props.someProp === 'value',
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  preserveState: (page) => page.props.someProp === 'value',
})
```

:::

## Scroll Preservation

When navigating between pages, Inertia mimics default browser behavior by automatically resetting the scroll position of the document body (as well as any [scroll regions](/guide/scroll-management#scroll-regions) you've defined) back to the top of the page.

You can disable this behavior by setting the `preserveScroll` option to `true`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, { preserveScroll: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, { preserveScroll: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, { preserveScroll: true })
```

:::

If you'd like to only preserve the scroll position if the response includes validation errors, set the `preserveScroll` option to `"errors"`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, { preserveScroll: 'errors' })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, { preserveScroll: 'errors' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, { preserveScroll: 'errors' })
```

:::

You can also lazily evaluate the `preserveScroll` option based on the response by providing a callback.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

:::

For more information regarding this feature, check out the [scroll management](/guide/scroll-management) documentation.

## Partial Reloads

The `only` option allows you to request a subset of the props (data) from the server on subsequent visits to the same page, thus making your application more efficient since it does not need to retrieve data that the page is not interested in refreshing.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.get('/users', { search: 'John' }, { only: ['users'] })
```

\== React

```js
import { router } from '@inertiajs/react'

router.get('/users', { search: 'John' }, { only: ['users'] })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.get('/users', { search: 'John' }, { only: ['users'] })
```

:::

For more information on this feature, check out the [partial reloads](/guide/partial-reloads) documentation.

## View Transitions

You may enable [View transitions](/guide/view-transitions) for a visit by setting the `viewTransition` option to `true`. This will use the browser's View Transitions API to animate the page transition.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit('/another-page', { viewTransition: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit('/another-page', { viewTransition: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit('/another-page', { viewTransition: true })
```

:::

## Visit Cancellation

@available\_since core=3.0.0

You may cancel all in-flight visits using the `router.cancelAll()` method. By default, this cancels all synchronous, asynchronous, and prefetch requests.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

// Cancel all in-flight requests...
router.cancelAll()
```

\== React

```js
import { router } from '@inertiajs/react'

// Cancel all in-flight requests...
router.cancelAll()
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

// Cancel all in-flight requests...
router.cancelAll()
```

:::

You may selectively cancel specific request types by passing an options object.

```js
// Cancel only async requests (leaving sync and prefetch active)...
router.cancelAll({ sync: false, prefetch: false })

// Cancel only sync requests...
router.cancelAll({ async: false, prefetch: false })

// Cancel everything except prefetch requests...
router.cancelAll({ prefetch: false })
```

### Cancel Tokens

@available\_since core=0.3.0

For more granular control, you may cancel individual visits using a cancel token. Inertia automatically generates a cancel token and provides it via the `onCancelToken()` callback prior to making the visit.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  onCancelToken: (cancelToken) => (this.cancelToken = cancelToken),
})

// Cancel the visit...
this.cancelToken.cancel()
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  onCancelToken: (cancelToken) => (this.cancelToken = cancelToken),
})

// Cancel the visit...
this.cancelToken.cancel()
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  onCancelToken: (cancelToken) => (this.cancelToken = cancelToken),
})

// Cancel the visit...
this.cancelToken.cancel()
```

:::

The `onCancel()` and `onFinish()` event callbacks will be executed when a visit is cancelled.

## Event Callbacks

In addition to Inertia's [global events](/guide/events), Inertia also provides a number of per-visit event callbacks.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onCancel: () => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onCancel: () => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onHttpException: (response) => {},
  onNetworkError: (error) => {},
  onCancel: () => {},
  onFinish: (visit) => {},
  onPrefetching: () => {},
  onPrefetched: () => {},
})
```

:::

Returning `false` from the `onBefore()` callback will cause the visit to be canceled. Returning `false` from `onHttpException()` or `onNetworkError()` will prevent the corresponding [global event](/guide/events) from being fired and its default behavior.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.delete(`/users/${user.id}`, {
  onBefore: () => confirm('Are you sure you want to delete this user?'),
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.delete(`/users/${user.id}`, {
  onBefore: () => confirm('Are you sure you want to delete this user?'),
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.delete(`/users/${user.id}`, {
  onBefore: () => confirm('Are you sure you want to delete this user?'),
})
```

:::

It's also possible to return a promise from the `onSuccess()` and `onError()` callbacks. When doing so, the "finish" event will be delayed until the promise has resolved.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post(url, {
  onSuccess: () => {
    return Promise.all([this.firstTask(), this.secondTask()])
  },
  onFinish: (visit) => {
    // Not called until firstTask() and secondTask() have finished
  },
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post(url, {
  onSuccess: () => {
    return Promise.all([this.firstTask(), this.secondTask()])
  },
  onFinish: (visit) => {
    // Not called until firstTask() and secondTask() have finished
  },
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post(url, {
  onSuccess: () => {
    return Promise.all([this.firstTask(), this.secondTask()])
  },
  onFinish: (visit) => {
    // Not called until firstTask() and secondTask() have finished
  },
})
```

:::

---

---
url: /guide/merging-props.md
---
# Merging Props

Inertia overwrites props with the same name when reloading a page. However, you may need to merge new data with existing data instead. For example, when implementing a "load more" button for paginated results. The [Infinite scroll](/guide/infinite-scroll) component uses prop merging under the hood.

Prop merging only works during [partial reloads](/guide/partial-reloads). Full page visits will always replace props entirely, even if you've marked them for merging.

## Merge Methods

@available\_since rails=3.6.0 core=2.0.0

To merge a prop instead of overwriting it, you may use the `InertiaRails.merge` method when returning your response.

```ruby
class UsersController < ApplicationController
  include Pagy::Method

  def index
    _pagy, records = pagy(:offset, User.all)

    render inertia: {
      users: InertiaRails.merge { records.as_json(...) },
    }
  end
end
```

The `InertiaRails.merge` method will append new items to existing arrays at the root level.

```ruby
# Append at root level (default)...
InertiaRails.merge { items }
```

@available\_since rails=3.12.0 core=2.2.0

You may change this behavior to prepend items instead.

```ruby
# Prepend at root level...
InertiaRails.merge(prepend: true) { items }
```

For more precise control, you can target specific nested properties for merging while replacing the rest of the object.

```ruby
# Only append to the 'data' array, replace everything else...
InertiaRails.merge(append: 'data') { {data: data, meta: meta} }

# Prepend to the 'messages' array...
InertiaRails.merge(prepend: 'messages') { chat_data }
```

You can combine multiple operations and target several properties at once.

```ruby
InertiaRails.merge(
  append: 'posts',
  prepend: 'announcements'
) { forum_data }

# Target multiple properties...
InertiaRails.merge(
  append: ['notifications', 'activities']
) { dashboard_data }
```

On the client side, Inertia handles all the merging automatically according to your server-side configuration.

## Matching Items

@available\_since rails=3.10.0 core=2.0.13

When merging arrays, you may use the `match_on` parameter to match existing items by a specific field and update them instead of appending new ones.

```ruby
# Match posts by ID, update existing ones...
InertiaRails.merge(match_on: 'id') { post_data }
```

@available\_since rails=3.12.0 core=2.2.0

You may also use append and prepend with a hash to specify the field to match.

```ruby
# Match posts by ID, update existing ones...
InertiaRails.merge(append: 'data', match_on: 'data.id') { post_data }

# Same as above, but using a hash shortcut...
InertiaRails.merge(append: { data: 'id' }) { post_data }

# Multiple properties with different match fields...
InertiaRails.merge(append: {
  'users.data' => 'id',
  'messages' => 'uuid',
}) { complex_data }
```

In the first two examples, Inertia will iterate over the data array and attempt to match each item by its id field. If a match is found, the existing item will be replaced. If no match is found, the new item will be appended.

## Deep Merge

@available\_since rails=3.8.0 core=2.0.8

Instead of specifying which nested paths should be merged, you may use `InertiaRails.deep_merge` to ensure a deep merge of the entire structure.

```ruby
class ChatController < ApplicationController
  def index
    chat_data = {
      messages: [
        { id: 4, text: 'Hello there!', user: 'Alice' },
        { id: 5, text: 'How are you?', user: 'Bob' },
      ],
      online: 12,
    }

    render inertia: {
      chat: InertiaRails.deep_merge(match_on: 'messages.id') { chat_data },
    }
  end
end
```

> \[!NOTE]
> `InertiaRails.deep_merge` was introduced before `InertiaRails.merge` had support for prepending and targeting nested paths. In most cases, `InertiaRails.merge` with its append and prepend parameters should be sufficient.

## Client Side Visits

You can also merge props directly on the client side without making a server request using [client side visits](/guide/manual-visits#client-side-visits). Inertia provides [prop helper methods](/guide/manual-visits#prop-helpers) that allow you to append, prepend, or replace prop values.

## Combining with Deferred Props

You may combine [deferred props](/guide/deferred-props) with mergeable props to defer the loading of the prop and ultimately mark it as mergeable once it's loaded.

```ruby
class UsersController < ApplicationController
  include Pagy::Method

  def index
    pagy, records = pagy(:offset, User.all)

    render inertia: {
      results: InertiaRails.defer(deep_merge: true) { records.as_json(...) },
    }
  end
end
```

## Combining with Once Props

@available\_since rails=3.15.0 core=2.2.20

You may pass the `once: true` argument to a merge prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      activity: InertiaRails.merge(once: true) { @user.recent_activity },
    }
  end
end
```

For more information on once props, see the [once props](/guide/once-props) documentation.

## Resetting Props

On the client side, you can indicate to the server that you would like to reset the prop. This is useful when you want to clear the prop value before merging new data, such as when the user enters a new search query on a paginated list.

The `reset` request option accepts an array of the props keys you would like to reset.

```js
router.reload({
  reset: ['results'],
  // ...
})
```

---

---
url: /guide/once-props.md
---
# Once Props

@available\_since rails=3.15.0 core=2.2.20

Some data rarely changes, is expensive to compute, or is simply large. Rather than including this data in every response, you may use *once props*. These props are remembered by the client and reused on subsequent pages that include the same prop. This makes them ideal for [shared data](/guide/shared-data).

> \[!NOTE]
> To understand when to use once props vs cached props vs HTTP caching, see the [Caching](/guide/caching) guide.

## Creating Once Props

To create a once prop, use the `InertiaRails.once` method when returning your response. This method receives a block that returns the prop data.

```ruby
class BillingController < ApplicationController
  def index
    render inertia: {
      plans: InertiaRails.once { Plan.all },
    }
  end
end
```

After the client has received this prop, subsequent requests will skip resolving the block and exclude the prop from the response. The client only remembers once props while navigating between pages that include them.

Navigating to a page without the once prop will forget the remembered value, and it will be resolved again on the next page that has it. In practice, this is rarely an issue since once props are typically used as shared data or within a specific section of your application.

## Forcing a Refresh

You may force a once prop to be refreshed using the `fresh` parameter. This is useful when you need to invalidate cached data based on particular pages, user actions or external changes:

```ruby
class BillingController < ApplicationController
  def index
    render inertia: {
      plans: InertiaRails.once(fresh: params[:refresh_plans].present?) { Plan.all },
    }
  end
end
```

## Refreshing from the Client

You may refresh a once prop from the client-side using a [partial reload](/guide/partial-reloads). The server will always resolve a once prop when explicitly requested.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.reload({ only: ['plans'] })
```

\== React

```js
import { router } from '@inertiajs/react'

router.reload({ only: ['plans'] })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.reload({ only: ['plans'] })
```

:::

## Expiration

You may set an expiration time using the `expires_in` parameter. This parameter accepts an `ActiveSupport::Duration` or an integer (seconds). The prop will be refreshed on a subsequent visit after the expiration time has passed.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      plans: InertiaRails.once(expires_in: 1.day) { Plan.all },
    }
  end
end
```

## Custom Keys

You may assign a custom key to the prop using the `key` parameter. This is useful when you want to share data across multiple pages while using different prop names.

```ruby
class TeamsController < ApplicationController
  def index
    render inertia: {
      memberRoles: InertiaRails.once(key: 'roles') { Role.all },
    }
  end

  def invite
    render inertia: {
      availableRoles: InertiaRails.once(key: 'roles') { Role.all },
    }
  end
end
```

Both pages share the same underlying data because they use the same custom key, so the prop is only resolved for whichever page you visit first.

## Sharing Once Props

You may share once props globally using the `inertia_share` controller method.

```ruby
class ApplicationController < ActionController::Base
  inertia_share countries: InertiaRails.once { Country.all }
end
```

You can also use `expires_in` and `key` options when sharing once props:

```ruby
class ApplicationController < ActionController::Base
  # Refresh countries list daily
  inertia_share countries: InertiaRails.once(expires_in: 1.day) { Country.all }

  # Share roles under a custom key for cross-page sharing
  inertia_share roles: InertiaRails.once(key: 'user_roles') { Role.all }
end
```

## Conditional Once Props

Some shared data is mostly stable but changes at specific moments, like the authenticated user. You may return a once prop while a user is authenticated, and `nil` otherwise. Sign in and sign out usually end with a redirect to a page that does not explicitly request the `auth` prop, so a remembered once value would go stale.

Returning `nil` on signed-out requests overwrites the remembered user on every response, while returning a once prop when authenticated lets the client remember the user across visits. Use the block form of `inertia_share` so the condition runs on each request.

```ruby
class InertiaController < ApplicationController
  inertia_share do
    {
      auth: Current.user ? InertiaRails.once { Current.user.as_json(only: [:id, :name, :email]) } : nil,
    }
  end
end
```

## Prefetching

Once props are compatible with [prefetching](/guide/prefetching). The client automatically includes any remembered once props in prefetched responses, so navigating to a prefetched page will already have the once props available.

Prefetched pages containing an expired once prop will be invalidated from the cache.

## Combining with Other Prop Types

The `once` option can be passed to [deferred](/guide/deferred-props), [merge](/guide/merging-props), and [optional](/guide/partial-reloads#lazy-data-evaluation) props.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      memberRoles: InertiaRails.once(key: 'roles') { Role.all },
      permissions: InertiaRails.defer(once: true) { Permission.all },
      activity: InertiaRails.merge(once: true) { @user.recent_activity },
      categories: InertiaRails.optional(once: true) { Category.all },
    }
  end
end
```

---

---
url: /guide/optimistic-updates.md
---
# Optimistic Updates

Inertia allows you to update the UI immediately without waiting for the server to respond, such as incrementing a like counter, toggling a bookmark, or adding an item to a list. Optimistic updates apply changes instantly while the request is in flight, automatically rolling back if the request fails.

## Router Visits

You may chain the `optimistic()` method before any router visit. The callback receives the current page props and should return a partial update to apply immediately.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router
  .optimistic((props) => ({
    post: {
      ...props.post,
      likes: props.post.likes + 1,
    },
  }))
  .post(`/posts/${post.id}/like`)
```

\== React

```js
import { router } from '@inertiajs/react'

router
  .optimistic((props) => ({
    post: {
      ...props.post,
      likes: props.post.likes + 1,
    },
  }))
  .post(`/posts/${post.id}/like`)
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router
  .optimistic((props) => ({
    post: {
      ...props.post,
      likes: props.post.likes + 1,
    },
  }))
  .post(`/posts/${post.id}/like`)
```

:::

The optimistic update is applied immediately to the current page's props, so your component re-renders with the new values before the request is sent. When the server responds, Inertia replaces the optimistic data with the server's response. If the request fails, the props are automatically reverted to their original values.

## Form Component

The `<Form>` component supports optimistic updates via the `optimistic` prop. Since the component manages input data internally, the form data is provided as a second callback argument.

:::tabs key:frameworks

\== Vue

```vue
<template>
  <Form
    action="/todos"
    method="post"
    :optimistic="
      (props, data) => ({
        todos: [
          ...props.todos,
          { id: Date.now(), name: data.name, done: false },
        ],
      })
    "
  >
    <input type="text" name="name" />
    <button type="submit">Add Todo</button>
  </Form>
</template>
```

\== React

```jsx
<Form
  action="/todos"
  method="post"
  optimistic={(props, data) => ({
    todos: [...props.todos, { id: Date.now(), name: data.name, done: false }],
  })}
>
  <input type="text" name="name" />
  <button type="submit">Add Todo</button>
</Form>
```

\== Svelte

```svelte
<Form
  action="/todos"
  method="post"
  optimistic={(props, data) => ({
    todos: [...props.todos, { id: Date.now(), name: data.name, done: false }],
  })}
>
  <input type="text" name="name" />
  <button type="submit">Add Todo</button>
</Form>
```

:::

## Form Helper

The `useForm` helper also supports optimistic updates via the same `optimistic()` method.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { useForm } from '@inertiajs/vue3'

const props = defineProps({ posts: Array })

const form = useForm({
  title: '',
})

function save() {
  form
    .optimistic((props) => ({
      posts: [...props.posts, { title: form.title }],
    }))
    .post('/posts')
}
</script>

<template>
  <input v-model="form.title" />
  <button @click="save" :disabled="form.processing">Save</button>
</template>
```

\== React

```jsx
import { useForm } from '@inertiajs/react'

export default function Posts({ posts }) {
  const { data, setData, optimistic, post, processing } = useForm({
    title: '',
  })

  function save(e) {
    e.preventDefault()
    optimistic((props) => ({
      posts: [...props.posts, { title: data.title }],
    }))
    post('/posts')
  }

  return (
    <form onSubmit={save}>
      <input
        value={data.title}
        onChange={(e) => setData('title', e.target.value)}
      />
      <button type="submit" disabled={processing}>
        Save
      </button>
    </form>
  )
}
```

\== Svelte

```svelte
<script>
  import { useForm } from '@inertiajs/svelte'

  let { posts } = $props()

  const form = useForm({
    title: '',
  })

  function save() {
    form
      .optimistic((props) => ({
        posts: [...props.posts, { title: form.title }],
      }))
      .post('/posts')
  }
</script>

<input bind:value={form.title} />
<button onclick={save} disabled={form.processing}>Save</button>
```

:::

## HTTP Requests

The [`useHttp`](/guide/http-requests) hook supports optimistic updates as well. Since HTTP requests don't interact with Inertia's page props, the optimistic callback receives and updates the form's own data. On failure, the form data is reverted to its pre-request state.

:::tabs key:frameworks

\== Vue

```js
import { useHttp } from '@inertiajs/vue3'

const form = useHttp({
  likes: 0,
})

form
  .optimistic((data) => ({
    likes: data.likes + 1,
  }))
  .post('/api/likes')
```

\== React

```js
import { useHttp } from '@inertiajs/react'

const { optimistic, post } = useHttp({
  likes: 0,
})

optimistic((data) => ({
  likes: data.likes + 1,
}))
post('/api/likes')
```

\== Svelte

```js
import { useHttp } from '@inertiajs/svelte'

const form = useHttp({
  likes: 0,
})

form
  .optimistic((data) => ({
    likes: data.likes + 1,
  }))
  .post('/api/likes')
```

:::

## How It Works

When an optimistic update is applied:

1. The returned props are compared against the current page props, and only the keys that actually changed are snapshotted
2. The callback's return value is merged into the current data
3. The request is sent to the server
4. On success, the server's response replaces the optimistic data
5. On failure, only the snapshotted keys are reverted, rolling back the optimistic changes

The callback should return a **partial** object containing only the keys you wish to update. The returned values are shallow-merged with the current data.

### Automatic Rollback

Optimistic state is automatically reverted in several scenarios:

* **Validation errors (422)**: The optimistic state is reverted and the validation errors are preserved
* **Server errors**: When the request fails for any other reason, the original state is restored
* **Interrupted visits**: When a new visit interrupts an in-flight request, the previous optimistic state is restored before the new optimistic update is applied

### Concurrent Updates

Multiple optimistic requests may be in flight at the same time. Inertia tracks which props each optimistic update touched, and server responses will not overwrite a prop until the last optimistic request that modified it has resolved.

## Inline Option

You may also pass the optimistic callback directly in the visit options instead of chaining.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post(
  `/posts/${post.id}/like`,
  {},
  {
    optimistic: (props) => ({
      post: { ...props.post, likes: props.post.likes + 1 },
    }),
  },
)
```

\== React

```js
import { router } from '@inertiajs/react'

router.post(
  `/posts/${post.id}/like`,
  {},
  {
    optimistic: (props) => ({
      post: { ...props.post, likes: props.post.likes + 1 },
    }),
  },
)
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post(
  `/posts/${post.id}/like`,
  {},
  {
    optimistic: (props) => ({
      post: { ...props.post, likes: props.post.likes + 1 },
    }),
  },
)
```

:::

The inline option works with `useHttp` submit methods as well.

```js
form.post('/api/likes', {
  optimistic: (data) => ({
    likes: data.likes + 1,
  }),
})
```

---

---
url: /guide/pages.md
---
# Pages

When building applications using Inertia, each page in your application typically has its own controller / route and a corresponding JavaScript component. This allows you to retrieve just the data necessary for that page - no API required.

In addition, all of the data needed for the page can be retrieved before the page is ever rendered by the browser, eliminating the need for displaying "loading" states when users visit your application.

## Creating Pages

Inertia pages are simply JavaScript components. If you have ever written a Vue, React, or Svelte component, you will feel right at home. As you can see in the example below, pages receive data from your application's controllers as props.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import Layout from '../Layout'
import { Head } from '@inertiajs/vue3'

defineProps({ user: Object })
</script>

<template>
  <Layout>
    <Head title="Welcome" />
    <h1>Welcome</h1>
    <p>Hello {{ user.name }}, welcome to your first Inertia app!</p>
  </Layout>
</template>
```

\== React

```jsx
import Layout from '../Layout'
import { Head } from '@inertiajs/react'

export default function Welcome({ user }) {
  return (
    <Layout>
      <Head title="Welcome" />
      <h1>Welcome</h1>
      <p>Hello {user.name}, welcome to your first Inertia app!</p>
    </Layout>
  )
}
```

\== Svelte

```svelte
<script>
  import Layout from '../Layout.svelte'

  let { user } = $props()
</script>

<svelte:head>
  <title>Welcome</title>
</svelte:head>

<Layout>
  <h1>Welcome</h1>
  <p>Hello {user.name}, welcome to your first Inertia app!</p>
</Layout>
```

:::

Given the page above, you can render the page by returning an [Inertia
response](/guide/responses) from a controller or route. In this
example, let's assume this page is stored at
`app/frontend/pages/users/show.vue`
`app/frontend/pages/users/show.jsx`
`app/frontend/pages/users/show.svelte` within a Rails application.

```ruby
class UsersController < ApplicationController
  def show
    user = User.find(params[:id])

    render inertia: { user: }
  end
end
```

If you attempt to render a page that does not exist, the response will typically be a blank screen.

## Transforming Component Names

Sometimes you may wish to transform component names. This may be done on the client side using the [`pages.transform`](/guide/client-side-setup#pages-shorthand) option, or on the server using the [`component_path_resolver`](/guide/responses#custom-path-resolver) config option. The transformed name is sent to the browser.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.component_path_resolver = ->(path:, action:) { "#{path}/#{action}/page" }
end
```

The server-side resolver only runs when Inertia Rails infers the component name, as in `render inertia: { event: }`. Explicit names, like `render inertia: 'events/show'`, are sent as-is.

## Layouts

Most applications share common UI elements across pages. Inertia provides persistent layouts that survive page navigations, along with layout props for passing dynamic data between pages and their layouts. Visit the [layouts documentation](/guide/layouts) to learn more.

---

---
url: /guide/partial-reloads.md
---
# Partial Reloads

When making visits to the same page you are already on, it's not always necessary to re-fetch all of the page's data from the server. In fact, selecting only a subset of the data can be a helpful performance optimization if it's acceptable that some page data becomes stale. Inertia makes this possible via its "partial reload" feature.

As an example, consider a "user index" page that includes a list of users, as well as an option to filter the users by their company. On the first request to the page, both the `users` and `companies` props are passed to the page component. However, on subsequent visits to the same page (maybe to filter the users), you can request only the `users` data from the server without requesting the `companies` data. Inertia will then automatically merge the partial data returned from the server with the data it already has in memory client-side.

> \[!NOTE]
> Partial reloads only work for visits made to the same page component.

## Only Certain Props

To perform a partial reload, use the `only` visit option to specify which data the server should return. This option should be an array of keys which correspond to the keys of the props.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, {
  only: ['users'],
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, {
  only: ['users'],
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, {
  only: ['users'],
})
```

:::

## Except Certain Props

In addition to the `only` visit option you can also use the `except` option to specify which data the server should exclude. This option should also be an array of keys which correspond to the keys of the props.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, {
  except: ['users'],
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, {
  except: ['users'],
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, {
  except: ['users'],
})
```

:::

### Filtering Inside Arrays

@available\_since rails=3.23.0

Dot-notation keys address array elements by index: `rows.0.name` selects one key of one element. The response still replaces the whole array on the client, so this saves server work, not client state. Elements you did not ask for are never evaluated and arrive as placeholders: `{}` for an element written as a Hash, `null` for anything else — including a lambda or serializer that would have produced a Hash, since it never runs.

```ruby
render inertia: 'reports/index', props: {
  rows: [{ name: 'First', total: 10 }, { name: 'Second', total: 20 }],
}
```

```js
router.reload({ only: ['rows.0.name'] })
// rows: [{ name: 'First' }, {}]
```

After this reload the page holds exactly `[{ name: 'First' }, {}]` — the second row's data is gone. Ask for every path the page still needs, or reload the whole prop. The placeholders exist to keep each element at its index, so the paths announced for deferred and merged props still match.

Objects work the other way round: a nested object whose every key the reload filtered out is dropped along with its key, rather than arriving as `{}`.

## Router Shorthand

Since partial reloads can only be made to the same page component the user is already on, it almost always makes sense to just use the `router.reload()` method, which automatically uses the current URL.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.reload({ only: ['users'] })
```

\== React

```js
import { router } from '@inertiajs/react'

router.reload({ only: ['users'] })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.reload({ only: ['users'] })
```

:::

## Using Links

It's also possible to perform partial reloads with Inertia links using the `only` property.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users?active=true" :only="['users']">Show active</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users?active=true" only={['users']}>
    Show active
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/users?active=true" use:inertia={{ only: ['users'] }}>Show active</a>

<Link href="/users?active=true" only={['users']}>Show active</Link>
```

:::

## Lazy Data Evaluation

For partial reloads to be most effective, be sure to also use lazy data evaluation when returning props from your server-side routes or controllers. This can be accomplished by wrapping page data in a lambda.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: -> { User.all.as_json },
      companies: -> { Company.all.as_json },
    }
  end
end
```

When Inertia performs a request, it will determine which data is required and only then will it evaluate the lambda. This can significantly increase the performance of pages that contain a lot of expensive data.

Additionally, Inertia provides an `InertiaRails.optional` method to specify that a prop should never be included unless explicitly requested using the `only` option:

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: InertiaRails.optional { User.all },
    }
  end
end
```

> \[!NOTE]
> Prior to Inertia.js v2, the method `InertiaRails.lazy` was used. It is now deprecated and has been replaced by `InertiaRails.optional`. Please update your code accordingly to ensure compatibility with the latest version.

On the inverse, you can use the `InertiaRails.always` method to specify that a prop should always be included, even if it has not been explicitly required in a partial reload.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: InertiaRails.always { User.all },
    }
  end
end
```

Here's a summary of each approach:

| Approach                                                                              | Standard Visits | Partial Reloads | Evaluated        |
| :------------------------------------------------------------------------------------ | :-------------- | :-------------- | :--------------- |
| `User.all.as_json`                           | Always          | Optionally      | Always           |
| `-> { User.all.as_json }`                    | Always          | Optionally      | Only when needed |
| `InertiaRails.optional { User.all.as_json }` | Never           | Optionally      | Only when needed |
| `InertiaRails.always { User.all.as_json }`   | Always          | Always          | Always           |

> \[!NOTE]
> A lambda only helps when the block does real work. `User.all` on its own is lazy: the query doesn't run until the prop is serialized, so a skipped prop never hits the database. Wrap calls that execute immediately, like `.as_json`, `.count`, or `.pluck`.

## Preserving Errors

@available\_since core=3.0.0

The Rails adapter shares errors using `InertiaRails.always`. With [`always_include_errors_hash`](/guide/configuration#always-include-errors-hash) enabled, as the Rails generator does, every response includes an errors hash, even partial reloads where no validation runs. This means an empty errors hash from the server will overwrite any existing client-side validation errors. You may use the `preserveErrors` option to keep existing errors when the server doesn't return new ones.

:::tabs key:frameworks

\== Vue

```js
router.reload({
  only: ['posts'],
  preserveErrors: true,
})
```

\== React

```js
router.reload({
  only: ['posts'],
  preserveErrors: true,
})
```

\== Svelte

```js
router.reload({
  only: ['posts'],
  preserveErrors: true,
})
```

:::

## Combining with Once Props

@available\_since rails=3.15.0 core=2.2.20

You may pass the `once: true` argument to an optional prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: InertiaRails.optional(once: true) { User.all },
    }
  end
end
```

For more information on once props, see the [once props](/guide/once-props) documentation.

## Combining with Caching

@available\_since rails=3.21.0

You may pass the `cache` option to an optional prop to cache the resolved value on the server side. On cache hits, the block is not evaluated.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: InertiaRails.optional(cache: 'all_users') { User.all },
    }
  end
end
```

For more information on cache keys and options, see the [cached props](/guide/cached-props) documentation.

---

---
url: /guide/polling.md
---
# Polling

## Poll Helper

Polling your server for new information on the current page is common, so Inertia provides a poll helper designed to help reduce the amount of boilerplate code. In addition, the poll helper will automatically stop polling when the page is unmounted.

The only required argument is the polling interval in milliseconds.

:::tabs key:frameworks

\== Vue

```js
import { usePoll } from '@inertiajs/vue3'

usePoll(2000)
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

usePoll(2000)
```

\== Svelte

```js
import { usePoll } from '@inertiajs/svelte'

usePoll(2000)
```

:::

If you need to pass additional request options to the poll helper, you can pass any of the `router.reload` options as the second parameter.

:::tabs key:frameworks

\== Vue

```js
import { usePoll } from '@inertiajs/vue3'

usePoll(2000, {
  onStart() {
    console.log('Polling request started')
  },
  onFinish() {
    console.log('Polling request finished')
  },
})
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

usePoll(2000, {
  onStart() {
    console.log('Polling request started')
  },
  onFinish() {
    console.log('Polling request finished')
  },
})
```

\== Svelte

```js
import { usePoll } from '@inertiajs/svelte'

usePoll(2000, {
  onStart() {
    console.log('Polling request started')
  },
  onFinish() {
    console.log('Polling request finished')
  },
})
```

:::

You may also pass a function that returns the request options. The function is evaluated on every tick, allowing the poll to reflect the latest component state.

@available\_since core=3.2.0

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { usePoll } from '@inertiajs/vue3'
const props = defineProps({ counter: Number })
usePoll(2000, () => ({
  data: { counter_seen: props.counter },
  only: ['last_received'],
}))
</script>
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

export default ({ counter }) => {
  usePoll(2000, () => ({
    data: { counter_seen: counter },
    only: ['last_received'],
  }))
}
```

\== Svelte

```js
import { usePoll } from '@inertiajs/svelte'

let { counter } = $props()

usePoll(2000, () => ({
  data: { counter_seen: counter },
  only: ['last_received'],
}))
```

:::

If you'd like more control over the polling behavior, the poll helper provides `stop` and `start` methods that allow you to manually start and stop polling. You can pass the `autoStart: false` option to the poll helper to prevent it from automatically starting polling when the component is mounted.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { usePoll } from '@inertiajs/vue3'

const { start, stop } = usePoll(
  2000,
  {},
  {
    autoStart: false,
  },
)
</script>

<template>
  <button @click="start">Start polling</button>
  <button @click="stop">Stop polling</button>
</template>
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

export default () => {
  const { start, stop } = usePoll(
    2000,
    {},
    {
      autoStart: false,
    },
  )

  return (
    <div>
      <button onClick={start}>Start polling</button>
      <button onClick={stop}>Stop polling</button>
    </div>
  )
}
```

\== Svelte

```svelte
<script>
  import { usePoll } from '@inertiajs/svelte'

  const { start, stop } = usePoll(
    2000,
    {},
    {
      autoStart: false,
    },
  )
</script>

<button onclick={start}>Start polling</button>
<button onclick={stop}>Stop polling</button>
```

:::

@available\_since core=3.7.0

The poll helper also returns a reactive `polling` value that reflects whether the poll is running, making it ideal for rendering a pause or resume button. The value doesn't indicate whether a request is in flight.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { usePoll } from '@inertiajs/vue3'

const { start, stop, polling } = usePoll(2000)
</script>

<template>
  <button v-if="polling" @click="stop">Pause updates</button>
  <button v-else @click="start">Resume updates</button>
</template>
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

export default () => {
  const { start, stop, polling } = usePoll(2000)

  return polling ? (
    <button onClick={stop}>Pause updates</button>
  ) : (
    <button onClick={start}>Resume updates</button>
  )
}
```

\== Svelte

```svelte
<script>
  import { usePoll } from '@inertiajs/svelte'

  const poll = usePoll(2000)
</script>

{#if poll.polling}
  <button onclick={poll.stop}>Pause updates</button>
{:else}
  <button onclick={poll.start}>Resume updates</button>
{/if}
```

:::

## Concurrency Mode

@available\_since core=3.2.0

By default, the poll helper fires a new request on every tick, even when the previous request is still in flight. You may control this behavior with the `mode` option, which accepts one of three values: `overlap`, `cancel`, or `rest`.

The default `overlap` mode allows requests to run in parallel. The `cancel` mode aborts any in-flight request when the next tick fires. The `rest` mode treats the interval as the time between the end of the previous request and the start of the next one, so requests never overlap.

:::tabs key:frameworks

\== Vue

```js
import { usePoll } from '@inertiajs/vue3'

usePoll(
  2000,
  {},
  {
    mode: 'rest',
  },
)
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

usePoll(
  2000,
  {},
  {
    mode: 'rest',
  },
)
```

\== Svelte

```js
import { usePoll } from '@inertiajs/svelte'

usePoll(
  2000,
  {},
  {
    mode: 'rest',
  },
)
```

:::

## Background Tabs

@available\_since core=3.9.0

By default, the poll helper throttles requests by 90% when the browser tab is in the background. You may control this behavior with the `background` option, which accepts one of three values: `throttle`, `pause`, or `continue`.

The `pause` mode stops polling entirely while the tab is hidden. Once the tab becomes visible again, polling resumes, firing a request immediately if the interval has already elapsed since the last one. The `continue` mode keeps polling at the regular interval, even while the tab is hidden.

:::tabs key:frameworks

\== Vue

```js
import { usePoll } from '@inertiajs/vue3'

usePoll(
  2000,
  {},
  {
    background: 'pause',
  },
)
```

\== React

```jsx
import { usePoll } from '@inertiajs/react'

usePoll(
  2000,
  {},
  {
    background: 'pause',
  },
)
```

\== Svelte

```js
import { usePoll } from '@inertiajs/svelte'

usePoll(
  2000,
  {},
  {
    background: 'pause',
  },
)
```

:::

> \[!NOTE]
> The `keepAlive` option is deprecated in favor of `background: 'continue'`.

---

---
url: /guide/precognition.md
---
# Precognition

@available\_since rails=3.18.0 core=2.3.0

Precognition enables real-time validation of form data without executing the full controller action. When your client-side form sends a validation request with special headers, the server runs your validations and responds with the results immediately — without saving records or triggering other side effects.

> \[!NOTE]
> This page covers the **server-side** (Rails) setup. For client-side usage with the `<Form>` component and `useForm` helper, see the [forms documentation](/guide/forms#precognition). For the `useHttp` hook, see [HTTP requests](/guide/http-requests#precognition).

Unlike Laravel, Rails doesn't have a standard params validation layer, so Inertia Rails provides a small DIY kit for those who want to use Precognition.

## Basic usage

Use `precognition!` or `precognition` in your controller to handle precognition requests:

```ruby
class UsersController < ApplicationController
  def create
    @user = User.new(user_params)
    precognition!(@user)

    if @user.save
      redirect_to @user
    else
      redirect_back_or_to new_user_path, inertia: { errors: @user.errors }
    end
  end
end
```

Two controller methods are available:

* **`precognition!(model_or_errors)`** — raises an exception to halt the action on precognition requests. No `return if` needed — the action simply stops. For non-precognition requests, returns `false` and continues normally.
* **`precognition(model_or_errors)`** — returns `true` if a precognition response was rendered, `false` otherwise. Use with `return if precognition(@user)` if you prefer the explicit return pattern.

Both methods accept an ActiveModel-like object (calls `valid?` automatically) or an errors hash:

* For valid data, responds with `204 No Content` with `Precognition: true` and `Precognition-Success: true` headers
* For invalid data, responds with `422 Unprocessable Entity` with errors as JSON and a `Precognition: true` header

> \[!NOTE]
> `precognition!` raises `InertiaRails::PrecognitionResponse`, which inherits from `Exception`, so `rescue_from StandardError` handlers and bare `rescue` clauses don't catch it. A `rescue_from Exception` handler still does, so don't use one for error pages.

## One call per action

You can only call `precognition!` or `precognition` once per controller action. Calling it a second time raises `InertiaRails::DoublePrecognitionError`. This is intentional — precognition validates a single form submission, so there should be exactly one validation point per action.

If you need to validate multiple models, use a [form object](#form-objects) that combines all validations into a single `valid?` call:

```ruby
# Bad — raises DoublePrecognitionError
def create
  precognition!(@user)
  precognition!(@profile) # Error!
end

# Good — validate everything in one call
def create
  form = RegistrationForm.new(params)
  precognition!(form) # Validates user + profile together
end
```

## Module-level API

`InertiaRails.precognition!` works the same way as the controller method but can be called from anywhere in the request cycle — form objects, service objects, or any Ruby code:

```ruby
InertiaRails.precognition!(@user)
```

This is useful when you want to handle precognition outside the controller.

## Form objects

When your form doesn't map directly to a single model, you can create a plain Ruby class with validations using `ActiveModel::API` and `ActiveModel::Attributes`. This gives you the same validation interface as a model:

```ruby
class RegistrationForm
  include ActiveModel::API
  include ActiveModel::Attributes

  attribute :name, :string
  attribute :email, :string
  attribute :company_name, :string

  validates :name, :email, presence: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
  validates :company_name, presence: true

  def save
    InertiaRails.precognition!(self)

    return false unless valid?

    # Create user, company, etc.
  end
end
```

Since `InertiaRails.precognition!` works from anywhere, form objects handle precognition themselves — no controller changes needed:

```ruby
class RegistrationsController < ApplicationController
  def create
    form = RegistrationForm.new(params)

    if form.save
      redirect_to form.user
    else
      redirect_back_or_to new_registration_path, inertia: { errors: form.errors }
    end
  end
end
```

## Other validation libraries

For libraries like dry-validation, pass the errors hash:

```ruby
class UsersController < ApplicationController
  def create
    result = UserContract.new.call(user_params.to_h)
    precognition!(result.errors.to_h)

    if result.success?
      @user = User.create!(result.to_h)
      redirect_to @user
    else
      redirect_back_or_to new_user_path, inertia: { errors: result.errors.to_h }
    end
  end
end
```

## Preventing side effects

Since precognition requests reuse your existing controller actions, it's important to place the `precognition!` call **before** any side-effect-producing code (saving records, sending emails, calling external APIs, enqueuing jobs). The `precognition!` method halts the action on precognition requests, so any code after it only runs during real form submissions.

You can also enable [`precognition_prevent_writes`](/guide/configuration#precognition-prevent-writes) to automatically block database writes during precognition requests as an extra safety net.

## Field-specific validation

Inertia's client-side form helper can request validation of specific fields using the `Precognition-Validate-Only` header. The server automatically filters the errors to only include the requested fields.

## Using `transform` with precognition

When using the `<Form>` component with a `transform` prop that wraps data under a key (e.g., `transform={(data) => ({ user: data })}`), the field names passed to `validate()` must match the keys in the **transformed** data structure, not the input `name` attributes.

This is because `validate('name')` looks up the value using the field name in the transformed data. If the transform wraps inputs under `user`, the transformed data is `{ user: { name: '...' } }`, and `validate('name')` won't find a value at the top level.

To work around this, you have two options:

**Option 1: Use dotted input names instead of a transform**

Use `name="user.name"` (or `name="user[name]"`) input attributes. The `<Form>` component automatically converts these into a nested `{ user: { name: '...' } }` structure without needing a transform, so `validate('user.name')` will correctly find the value. Note that server error keys must match (e.g., `user.name`), so you may need to prefix errors in your precognition response.

**Option 2: Use `useForm` with `withPrecognition` instead**

The `useForm` helper tracks data internally, so `validate('name')` always works regardless of transforms:

:::tabs key:frameworks

\== Vue

```js
const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')

// The transform only applies to the submitted data, not the validate() lookup
form.transform((data) => ({ user: data }))
```

\== React

```jsx
const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')

form.transform((data) => ({ user: data }))
```

\== Svelte

```js
const form = useForm({
  name: '',
  email: '',
}).withPrecognition('post', '/users')

form.transform((data) => ({ user: data }))
```

:::

---

---
url: /guide/prefetching.md
---
# Prefetching

Inertia supports prefetching data for pages that are likely to be visited next. This can be useful for improving the perceived performance of your app by allowing the data to be fetched in the background while the user is still interacting with the current page.

## Link Prefetching

To prefetch data for a page, you can add the `prefetch` prop to the Inertia link component. By default, Inertia will prefetch the data for the page when the user hovers over the link for more than 75ms. You may customize this hover delay by setting the `prefetch.hoverDelay` option in your [application defaults](/guide/client-side-setup#configuring-defaults).

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch>Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users" prefetch>
    Users
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: true }}>Users</a>
```

:::

By default, data is cached for 30 seconds before being evicted. You may customize this default value by setting the `prefetch.cacheFor` option in your [application defaults](/guide/client-side-setup#configuring-defaults). You may also customize the cache duration on a per-link basis by passing a `cacheFor` prop to the `Link` component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch cache-for="1m">Users</Link>
  <Link href="/users" prefetch cache-for="10s">Users</Link>
  <Link href="/users" prefetch :cache-for="5000">Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <>
    <Link href="/users" prefetch cacheFor="1m">
      Users
    </Link>
    <Link href="/users" prefetch cacheFor="10s">
      Users
    </Link>
    <Link href="/users" prefetch cacheFor={5000}>
      Users
    </Link>
  </>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: true, cacheFor: '1m' }}>Users</a>
<a href="/users" use:inertia={{ prefetch: true, cacheFor: '10s' }}>Users</a>
<a href="/users" use:inertia={{ prefetch: true, cacheFor: 5000 }}>Users</a>
```

:::

Instead of prefetching on hover, you can also start prefetching on `mousedown` by passing the `click` value to the `prefetch` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch="click">Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users" prefetch="click">
    Users
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: 'click' }}>Users</a>
```

:::

If you're confident that the user will visit a page next, you can prefetch the data on mount as well.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch="mount">Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users" prefetch="mount">
    Users
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: 'mount' }}>Users</a>
```

:::

You can also combine prefetch strategies by passing an array of values to the `prefetch` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" :prefetch="['mount', 'hover']">Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users" prefetch={['mount', 'hover']}>
    Users
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: ['mount', 'hover'] }}>Users</a>
```

:::

## Programmatic Prefetching

You can prefetch data programmatically using `router.prefetch`. This method's signature is identical to `router.visit` with the exception of a third argument that allows you to specify prefetch options.

When the `cacheFor` option is not specified, it defaults to 30 seconds.

```js
router.prefetch('/users', { method: 'get', data: { page: 2 } })

router.prefetch(
  '/users',
  { method: 'get', data: { page: 2 } },
  { cacheFor: '1m' },
)
```

Inertia also provides a `usePrefetch` hook that allows you to track the prefetch state for the current page. It returns information about whether the page is currently prefetching, has been prefetched, when it was last updated, and a `flush` method that flushes the cache for the current page only.

:::tabs key:frameworks

\== Vue

```js
import { usePrefetch } from '@inertiajs/vue3'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch()
```

\== React

```js
import { usePrefetch } from '@inertiajs/react'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch()
```

\== Svelte

```js
import { usePrefetch } from '@inertiajs/svelte'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch()
```

:::

You can also pass visit options when you need to differentiate between different request configurations for the same URL.

:::tabs key:frameworks

\== Vue

```js
import { usePrefetch } from '@inertiajs/vue3'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch({
  headers: { 'X-Custom-Header': 'value' },
})
```

\== React

```js
import { usePrefetch } from '@inertiajs/react'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch({
  headers: { 'X-Custom-Header': 'value' },
})
```

\== Svelte

```js
import { usePrefetch } from '@inertiajs/svelte'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch({
  headers: { 'X-Custom-Header': 'value' },
})
```

:::

## Cache Tags

@available\_since core=2.1.2

Cache tags allow you to group related prefetched data and invalidate all cached data with that tag when specific events occur.

To tag cached data, pass a `cacheTags` prop to your `Link` component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch cache-tags="users">Users</Link>
  <Link href="/dashboard" prefetch :cache-tags="['dashboard', 'stats']">
    Dashboard
  </Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <>
    <Link href="/users" prefetch cacheTags="users">
      Users
    </Link>
    <Link href="/dashboard" prefetch cacheTags={['dashboard', 'stats']}>
      Dashboard
    </Link>
  </>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: true, cacheTags: 'users' }}>Users</a>
<a
  href="/dashboard"
  use:inertia={{ prefetch: true, cacheTags: ['dashboard', 'stats'] }}
>
  Dashboard
</a>
```

:::

When prefetching programmatically, pass `cacheTags` in the third argument to `router.prefetch`.

```js
router.prefetch('/users', {}, { cacheTags: 'users' })
router.prefetch('/dashboard', {}, { cacheTags: ['dashboard', 'stats'] })
```

## Cache Invalidation

You can manually flush the prefetch cache by calling `router.flushAll` to remove all cached data, or `router.flush` to remove cache for a specific page.

```js
// Flush all prefetch cache
router.flushAll()

// Flush cache for a specific page
router.flush('/users', { method: 'get', data: { page: 2 } })

// Using the usePrefetch hook
const { flush } = usePrefetch()

// Flush cache for the current page
flush()
```

For more granular control, you can flush cached data by their tags using `router.flushByCacheTags`. This removes any cached response that contains *any* of the specified tags.

```js
// Flush all responses tagged with 'users'
router.flushByCacheTags('users')

// Flush all responses tagged with 'dashboard' OR 'stats'
router.flushByCacheTags(['dashboard', 'stats'])
```

### Automatic Cache Flushing

By default, Inertia does not automatically flush the prefetch cache when you navigate to new pages. Cached data is only evicted when it expires based on the cache duration. If you want to flush all cached data on every navigation, you can set up an event listener.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.on('navigate', () => router.flushAll())
```

\== React

```js
import { router } from '@inertiajs/react'

router.on('navigate', () => router.flushAll())
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.on('navigate', () => router.flushAll())
```

:::

### Invalidate on Requests

@available\_since core=2.1.2

To automatically invalidate caches when making requests, pass an `invalidateCacheTags` prop to the `Form` component. The specified tags will be flushed when the form submission succeeds.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Form } from '@inertiajs/vue3'
</script>

<template>
  <Form
    action="/users"
    method="post"
    :invalidate-cache-tags="['users', 'dashboard']"
  >
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
  </Form>
</template>
```

\== React

```jsx
import { Form } from '@inertiajs/react'

export default () => (
  <Form
    action="/users"
    method="post"
    invalidateCacheTags={['users', 'dashboard']}
  >
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
  </Form>
)
```

\== Svelte

```svelte
<script>
  import { Form } from '@inertiajs/svelte'
</script>

<Form
  action="/users"
  method="post"
  invalidateCacheTags={['users', 'dashboard']}
>
  <input type="text" name="name" />
  <input type="email" name="email" />
  <button type="submit">Create User</button>
</Form>
```

:::

When using the `useForm` helper, you can include `invalidateCacheTags` in the visit options.

:::tabs key:frameworks

\== Vue

```js
import { useForm } from '@inertiajs/vue3'

const form = useForm({
  name: '',
  email: '',
})

const submit = () => {
  form.post('/users', {
    invalidateCacheTags: ['users', 'dashboard'],
  })
}
```

\== React

```js
import { useForm } from '@inertiajs/react'

const { data, setData, post } = useForm({
  name: '',
  email: '',
})

function submit(e) {
  e.preventDefault()
  post('/users', {
    invalidateCacheTags: ['users', 'dashboard'],
  })
}
```

\== Svelte

```js
import { useForm } from '@inertiajs/svelte'

const form = useForm({
  name: '',
  email: '',
})

function submit() {
  form.post('/users', {
    invalidateCacheTags: ['users', 'dashboard'],
  })
}
```

:::

You can also invalidate cache tags with programmatic visits by including `invalidateCacheTags` in the options.

```js
router.delete(`/users/${userId}`, {
  invalidateCacheTags: ['users', 'dashboard'],
})

router.post('/posts', postData, {
  invalidateCacheTags: ['posts', 'recent-posts'],
})
```

## Stale While Revalidate

By default, Inertia will fetch a fresh copy of the data when the user visits the page if the cached data is older than the cache duration. You can customize this behavior by passing a tuple to the `cacheFor` prop.

The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before fetching data from the server is necessary.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch :cacheFor="['30s', '1m']">Users</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/users" prefetch cacheFor={['30s', '1m']}>
    Users
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia } from '@inertiajs/svelte'
</script>

<a href="/users" use:inertia={{ prefetch: true, cacheFor: ['30s', '1m'] }}>
  Users
</a>
```

:::

If a request is made within the fresh period (before the first value), the cache is returned immediately without making a request to the server.

If a request is made during the stale period (between the two values), the stale value is served to the user, and a request is made in the background to refresh the cached data. Once the fresh data is returned, it is merged into the page so the user has the most recent data.

If a request is made after the second value, the cache is considered expired, and the page and data is fetched from the server as a regular request.

---

---
url: /guide/progress-indicators.md
---
# Progress Indicators

Since Inertia requests are made via XHR, there would typically not be a browser loading indicator when navigating from one page to another. To solve this, Inertia displays a progress indicator at the top of the page whenever you make an Inertia visit. However, [asynchronous requests](#visit-options) do not show the progress indicator unless explicitly configured.

Of course, if you prefer, you can disable Inertia's default loading indicator and provide your own custom implementation. We'll discuss both approaches below.

## Default

Inertia's default progress indicator is a light-weight wrapper around the [NProgress](https://ricostacruz.com/nprogress/) library. You can customize it via the `progress` property of the `createInertiaApp()` function.

```js
createInertiaApp({
  progress: {
    // The delay after which the progress bar will appear, in milliseconds...
    delay: 250,
    // The color of the progress bar...
    color: '#29d',
    // Whether to include the default NProgress styles...
    includeCSS: true,
    // Whether the NProgress spinner will be shown...
    showSpinner: false,
  },
  // ...
})
```

For applications using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) that restricts inline styles, you may pass a `nonce` to `createInertiaApp()` to permit the styles Inertia injects for the progress bar. See [Content Security Policy](/guide/client-side-setup#content-security-policy) for details.

You may disable Inertia's default loading indicator by setting the `progress` property to `false`.

```js
createInertiaApp({
  progress: false,
  // ...
})
```

## Programmatic Access

@available\_since core=2.1.11

When you need to control the progress indicator outside of Inertia requests, for example, when making requests with Axios or other libraries, you can use Inertia's progress methods directly.

:::tabs key:frameworks

\== Vue

```js
import { progress } from '@inertiajs/vue3'

progress.start() // Begin progress animation
progress.set(0.25) // Set to 25% complete
progress.finish() // Complete and fade out
progress.reset() // Reset to start
progress.remove() // Complete and remove from DOM
progress.hide() // Hide progress bar
progress.reveal() // Show progress bar

progress.isStarted() // Returns boolean
progress.getStatus() // Returns current percentage or null
```

\== React

```js
import { progress } from '@inertiajs/react'

progress.start() // Begin progress animation
progress.set(0.25) // Set to 25% complete
progress.finish() // Complete and fade out
progress.reset() // Reset to start
progress.remove() // Complete and remove from DOM
progress.hide() // Hide progress bar
progress.reveal() // Show progress bar

progress.isStarted() // Returns boolean
progress.getStatus() // Returns current percentage or null
```

\== Svelte

```js
import { progress } from '@inertiajs/svelte'

progress.start() // Begin progress animation
progress.set(0.25) // Set to 25% complete
progress.finish() // Complete and fade out
progress.reset() // Reset to start
progress.remove() // Complete and remove from DOM
progress.hide() // Hide progress bar
progress.reveal() // Show progress bar

progress.isStarted() // Returns boolean
progress.getStatus() // Returns current percentage or null
```

:::

The `hide()` and `reveal()` methods work together to prevent conflicts when separate parts of your code need to control progress visibility. Each `hide()` call increments an internal counter, while `reveal()` decrements it. The progress bar only appears when this counter reaches zero.

However, `reveal()` accepts an optional `force` parameter that bypasses this counter. Inertia uses this pattern internally to hide progress during prefetching while ensuring it appears for actual navigation.

```js
progress.hide() // Counter = 1, bar hidden
progress.hide() // Counter = 2, bar still hidden
progress.reveal() // Counter = 1, bar still hidden
progress.reveal() // Counter = 0, bar now visible

// Force reveal bypasses the counter
progress.reveal(true)
```

> \[!NOTE]
> If you've disabled the progress indicator with `progress: false` in `createInertiaApp()`, these programmatic methods will not work.

## Custom

It's also possible to setup your own custom page loading indicators using Inertia [events](/guide/events). Let's explore how to do this using the [NProgress](https://ricostacruz.com/nprogress/) library as an example.

First, disable Inertia's default loading indicator.

```js
createInertiaApp({
  progress: false,
  // ...
})
```

Next, install the NProgress library.

```bash
npm install nprogress
```

After installation, you'll need to add the NProgress [styles](https://github.com/rstacruz/nprogress/blob/master/nprogress.css) to your project. You can do this using a CDN hosted copy of the styles.

```html
<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/nprogress/0.2.0/nprogress.min.css"
/>
```

Then, import both `NProgress` and the Inertia `router` into your application.

:::tabs key:frameworks

\== Vue

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/vue3'
```

\== React

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/react'
```

\== Svelte

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/svelte'
```

:::

Next, add a `start` event listener. We'll use this listener to show the progress bar when a new Inertia visit begins.

```js
router.on('start', () => NProgress.start())
```

Finally, add a `finish` event listener to hide the progress bar when the page visit finishes.

```js
router.on('finish', () => NProgress.done())
```

That's it! Now, as you navigate from one page to another, the progress bar will be added and removed from the page.

### Handling Cancelled Visits

While this custom progress implementation works great for page visits that finish properly, it would be nice to handle cancelled visits as well. First, for interrupted visits (those that get cancelled as a result of a new visit), the progress bar should simply be reset back to the start position. Second, for manually cancelled visits, the progress bar should be immediately removed from the page.

We can accomplish this by inspecting the `event.detail.visit` object that's provided to the finish event.

```js
router.on('finish', (event) => {
  if (event.detail.visit.completed) {
    NProgress.done()
  } else if (event.detail.visit.interrupted) {
    NProgress.set(0)
  } else if (event.detail.visit.cancelled) {
    NProgress.done()
    NProgress.remove()
  }
})
```

### File Upload Progress

Let's take this a step further. When files are being uploaded, it would be great to update the loading indicator to reflect the upload progress. This can be done using the `progress` event.

```js
router.on('progress', (event) => {
  if (event.detail.progress.percentage) {
    NProgress.set((event.detail.progress.percentage / 100) * 0.9)
  }
})
```

Now, instead of the progress bar "trickling" while the files are being uploaded, it will actually update it's position based on the progress of the request. We limit the progress here to 90%, since we still need to wait for a response from the server.

### Loading Indicator Delay

The last thing we're going to implement is a loading indicator delay. It's often preferable to delay showing the loading indicator until a request has taken longer than 250-500 milliseconds. This prevents the loading indicator from appearing constantly on quick page visits, which can be visually distracting.

To implement the delay behavior, we'll use the `setTimeout` and `clearTimeout` functions. Let's start by defining a variable to keep track of the timeout.

```js
let timeout = null
```

Next, let's update the `start` event listener to start a new timeout that will show the progress bar after 250 milliseconds.

```js
router.on('start', () => {
  timeout = setTimeout(() => NProgress.start(), 250)
})
```

Next, we'll update the `finish` event listener to clear any existing timeouts in the event that the page visit finishes before the timeout does.

```js
router.on('finish', (event) => {
  clearTimeout(timeout)
  // ...
})
```

In the `finish` event listener, we need to determine if the progress bar has actually started displaying progress, otherwise we'll inadvertently cause it to show before the timeout has finished.

```js
router.on('finish', (event) => {
  clearTimeout(timeout)

  if (!NProgress.isStarted()) {
    return
  }
  // ...
})
```

And, finally, we need to do the same check in the `progress` event listener.

```js
router.on('progress', (event) => {
  if (!NProgress.isStarted()) {
    return
  }
  // ...
})
```

That's it, you now have a beautiful custom page loading indicator!

### Complete Example

For convenience, here is the full source code of the final version of our custom loading indicator.

:::tabs key:frameworks

\== Vue

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/vue3'

let timeout = null

router.on('start', () => {
  timeout = setTimeout(() => NProgress.start(), 250)
})

router.on('progress', (event) => {
  if (NProgress.isStarted() && event.detail.progress.percentage) {
    NProgress.set((event.detail.progress.percentage / 100) * 0.9)
  }
})

router.on('finish', (event) => {
  clearTimeout(timeout)

  if (!NProgress.isStarted()) {
    return
  }

  if (event.detail.visit.completed) {
    NProgress.done()
  } else if (event.detail.visit.interrupted) {
    NProgress.set(0)
  } else if (event.detail.visit.cancelled) {
    NProgress.done()
    NProgress.remove()
  }
})
```

\== React

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/react'

let timeout = null

router.on('start', () => {
  timeout = setTimeout(() => NProgress.start(), 250)
})

router.on('progress', (event) => {
  if (NProgress.isStarted() && event.detail.progress.percentage) {
    NProgress.set((event.detail.progress.percentage / 100) * 0.9)
  }
})

router.on('finish', (event) => {
  clearTimeout(timeout)

  if (!NProgress.isStarted()) {
    return
  }

  if (event.detail.visit.completed) {
    NProgress.done()
  } else if (event.detail.visit.interrupted) {
    NProgress.set(0)
  } else if (event.detail.visit.cancelled) {
    NProgress.done()
    NProgress.remove()
  }
})
```

\== Svelte

```js
import NProgress from 'nprogress'
import { router } from '@inertiajs/svelte'

let timeout = null

router.on('start', () => {
  timeout = setTimeout(() => NProgress.start(), 250)
})

router.on('progress', (event) => {
  if (NProgress.isStarted() && event.detail.progress.percentage) {
    NProgress.set((event.detail.progress.percentage / 100) * 0.9)
  }
})

router.on('finish', (event) => {
  clearTimeout(timeout)

  if (!NProgress.isStarted()) {
    return
  }

  if (event.detail.visit.completed) {
    NProgress.done()
  } else if (event.detail.visit.interrupted) {
    NProgress.set(0)
  } else if (event.detail.visit.cancelled) {
    NProgress.done()
    NProgress.remove()
  }
})
```

:::

## Visit Options

In addition to these configurations, Inertia.js provides two visit options to control the loading indicator on a per-request basis: `showProgress` and `async`. These options offer greater control over how Inertia.js handles asynchronous requests and manages progress indicators.

### Show Progress

The `showProgress` option provides fine-grained control over the visibility of the loading indicator during requests.

```js
router.get('/settings', {}, { showProgress: false })
```

### Async

The `async` option allows you to perform asynchronous requests without displaying the default progress indicator. It can be used in combination with the `showProgress` option.

```js
// Disable the progress indicator
router.get('/settings', {}, { async: true })
// Enable the progress indicator with async requests
router.get('/settings', {}, { async: true, showProgress: true })
```

---

---
url: /guide/redirects.md
---
# Redirects

When making a non-GET Inertia request manually or via a `<Link>` element, you should ensure that you always respond with a proper Inertia redirect response.

For example, if your controller is creating a new user, your "create" endpoint should return a redirect back to a standard `GET` endpoint, such as your user "index" page. Inertia will automatically follow this redirect and update the page accordingly.

```ruby
class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      redirect_to users_url
    else
      redirect_to new_user_url, inertia: { errors: user.errors }
    end
  end

  private

  def user_params
    params.expect(user: [:name, :email])
  end
end
```

## 303 Response Code

When redirecting after a `PUT`, `PATCH`, or `DELETE` request, you must use a `303` response code, otherwise the subsequent request will not be treated as a `GET` request. A `303` redirect is very similar to a `302` redirect; however, the follow-up request is explicitly changed to a `GET` request.

The Rails adapter does this for you: it converts `301` and `302` redirects to `303` when they respond to an Inertia `PUT`, `PATCH`, or `DELETE` request.

## Preserving Fragments

@available\_since rails=3.19.0 core=3.0.0

Sometimes a user may visit a URL with a fragment, such as `/article/old-slug#section`, and the server needs to redirect to a different URL. The fragment from the original request is normally lost during the redirect.

:::tabs key:frameworks

\== Vue

```vue
<Link href="/article/old-slug#section">View section</Link>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => <Link href="/article/old-slug#section">View section</Link>
```

\== Svelte

```svelte
<Link href="/article/old-slug#section">View section</Link>
```

:::

You may preserve the fragment by passing `preserve_fragment` on the redirect response. The client will carry over the `#section` fragment to the redirect target, resulting in `/article/new-slug#section`.

```ruby
redirect_to article_path(article), inertia: { preserve_fragment: true }
```

## Redirecting to Fragments

@available\_since rails=3.23.0 core=3.0.0

A redirect target may contain its own fragment, such as `/articles/1#comments`. By default, the fragment is lost when Inertia follows the redirect. Enable `convert_fragment_redirects` to keep it. Apps set up with the installer have it enabled.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.convert_fragment_redirects = true
end
```

```ruby
redirect_to article_path(article, anchor: 'comments')
```

Inertia Rails then returns a `409 Conflict` response with the URL in the `X-Inertia-Redirect` header, and the client visits `/articles/1#comments`.

## External Redirects

Sometimes it's necessary to redirect outside of your Inertia app: to another website, or to a non-Inertia endpoint in your own app. These destinations can't be visited as Inertia pages — the client has to leave the SPA with a full `window.location` visit. The server triggers that visit by responding with an Inertia location response: `409 Conflict` with the destination URL in the `X-Inertia-Location` header.

Inertia Rails generates these responses in two ways: automatically for cross-origin redirects, and explicitly for same-origin redirects marked with `inertia: { full_page: true }`.

### Cross-Origin Redirects

@available\_since rails=3.23.0

A regular redirect to another origin works out of the box — Inertia Rails automatically converts it into an Inertia location response for Inertia requests:

```ruby
redirect_to 'https://checkout.stripe.com/session_123', allow_other_host: true
```

Without the conversion, such a redirect can never succeed: the browser follows XHR redirects transparently, and the follow-up request to the external origin fails CORS checks.

The conversion applies to `301`, `302`, and `303` responses. Method-preserving `307` and `308` redirects are left untouched, since a `window.location` visit cannot preserve the HTTP method. It applies to all Inertia requests, including background ones such as polling and prefetching.

You can disable this behavior with the [`convert_external_redirects`](/guide/configuration#convert-external-redirects) configuration option.

### Same-Origin Redirects

@available\_since rails=3.23.0

Redirects to a non-Inertia endpoint on the same origin can't be converted automatically: a `Location` header doesn't reveal whether its target renders an Inertia page, and converting every same-origin redirect would turn regular Inertia navigation into full page loads. A plain `redirect_to` fails differently here — the browser follows the redirect transparently, the non-Inertia endpoint responds without the `X-Inertia` header, and the client rejects it as an invalid Inertia response.

Mark such redirects explicitly with `inertia: { full_page: true }`:

```ruby
redirect_to admin_path, inertia: { full_page: true }
```

For Inertia requests, the redirect is converted into an Inertia location response, even when `convert_external_redirects` is disabled. For non-Inertia requests, it stays a regular redirect. Think of it as [`inertia_location`](#inertia-location) with `redirect_to` ergonomics: URL helpers, records, flash options, and status codes all work as usual.

> \[!NOTE]
> Don't combine the mark with `inertia: { errors: ... }` — a location response triggers a full page visit to a non-Inertia endpoint, so the errors would never reach an Inertia page and are discarded, like with `inertia_location`.

The mark requires a `301`, `302`, or `303` redirect. Combining it with a method-preserving `307` or `308` status raises an `ArgumentError`, since a `window.location` visit cannot preserve the HTTP method.

> \[!TIP]
> If a whole section of your app is non-Inertia, you can guard it on the target side instead, so that any Inertia request that reaches it — through a followed redirect or a stale link — is bounced into a full page visit:
>
> ```ruby
> class NonInertiaBaseController < ApplicationController
>   before_action -> { inertia_location(request.original_url) if request.inertia? }
> end
> ```

### `inertia_location`

On older versions of Inertia Rails, where the automatic conversion above is not available, use the `inertia_location` method, which generates the Inertia location response directly:

```ruby
inertia_location 'https://checkout.stripe.com/session_123'
```

For Inertia requests, it generates a `409 Conflict` response with the destination URL in the `X-Inertia-Location` header. For non-Inertia requests (for example, a direct browser visit to the same endpoint), it performs a regular redirect — on older versions of Inertia Rails, it responds with `409 Conflict` regardless of the request type.

> \[!WARNING]
> `inertia_location` bypasses Rails' open redirect protection. Only pass trusted URLs to it, and don't redirect to user-provided URLs.

---

---
url: /guide/remembering-state.md
---
# Remembering State

When navigating browser history, Inertia restores pages using prop data cached in history state. However, Inertia does not restore local page component state since this is beyond its reach. This can lead to outdated pages in your browser history.

For example, if a user partially completes a form, then navigates away, and then returns back, the form will be reset and their work will be lost.

To mitigate this issue, you can tell Inertia which local component state to save in the browser history.

## Saving Local State

To save local component state to the history state, use the `useRemember` feature to tell Inertia which data it should remember.

:::tabs key:frameworks

\== Vue

```js
import { useRemember } from '@inertiajs/vue3'

const form = useRemember({
  first_name: null,
  last_name: null,
})
```

\== React

```jsx
import { useRemember } from '@inertiajs/react'

export default function Profile() {
  const [formState, setFormState] = useRemember({
    first_name: null,
    last_name: null,
    // ...
  })

  // ...
}
```

\== Svelte

```js
import { useRemember } from '@inertiajs/svelte'

const form = useRemember({
  first_name: null,
  last_name: null,
})

// ...
```

:::

Now, whenever your local `form` state changes, Inertia will automatically save this data to the history state and will also restore it on history navigation.

## Multiple Components

If your page contains multiple components that use the remember functionality provided by Inertia, you need to provide a unique key for each component so that Inertia knows which data to restore to each component.

:::tabs key:frameworks

\== Vue

```js
import { useRemember } from '@inertiajs/vue3'

const form = useRemember(
  {
    first_name: null,
    last_name: null,
  },
  'users/new',
)
```

\== React

```jsx
import { useRemember } from '@inertiajs/react'

export default function Profile() {
  const [formState, setFormState] = useRemember(
    {
      first_name: null,
      last_name: null,
    },
    'users/new',
  )
}
```

\== Svelte

```js
import { useRemember } from '@inertiajs/svelte'

const form = useRemember(
  {
    first_name: null,
    last_name: null,
  },
  'users/new',
)
```

:::

If you have multiple instances of the same component on the page using the remember functionality, be sure to also include a unique key for each component instance, such as a model identifier.

:::tabs key:frameworks

\== Vue

```js
import { useRemember } from '@inertiajs/vue3'

const props = defineProps({ user: Object })

const form = useRemember(
  {
    first_name: null,
    last_name: null,
  },
  `users/edit:${props.user.id}`,
)
```

\== React

```jsx
import { useRemember } from '@inertiajs/react'

export default function Profile({ user }) {
  const [formState, setFormState] = useRemember(
    {
      first_name: user.first_name,
      last_name: user.last_name,
    },
    `users/edit:${user.id}`,
  )
}
```

\== Svelte

```js
import { page, useRemember } from '@inertiajs/svelte'

const form = useRemember(
  {
    first_name: page.props.user.first_name,
    last_name: page.props.user.last_name,
  },
  `users/edit:${page.props.user.id}`,
)
```

:::

## Form Helper

If you're using the [Inertia form helper](/guide/forms#form-helper), you can pass a unique form key as the first argument when instantiating your form. This will cause the form data and errors to automatically be remembered.

:::tabs key:frameworks

\== Vue

```js
import { useForm } from '@inertiajs/vue3'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${props.user.id}`, data)
```

\== React

```js
import { useForm } from '@inertiajs/react'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)
```

\== Svelte

```js
import { useForm } from '@inertiajs/svelte'

const form = useForm('CreateUser', data)
const form = useForm(`EditUser:${user.id}`, data)
```

:::

You may [exclude specific fields](/guide/forms#excluding-fields) from being remembered using the `dontRemember()` method. This is useful for sensitive fields like passwords that should not be stored in history state.

## Manually Saving State

The `useRemember` hook watches for data changes and automatically saves those changes to the history state. Then, Inertia will restore the data on page load.

However, it's also possible to manage this manually using the underlying `remember()` and `restore()` methods exposed by Inertia.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

// Save local component state to history state
router.remember(data, 'my-key')

// Restore local component state from history state
let data = router.restore('my-key')
```

\== React

```js
import { router } from '@inertiajs/react'

// Save local component state to history state
router.remember(data, 'my-key')

// Restore local component state from history state
let data = router.restore('my-key')
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

// Save local component state to history state
router.remember(data, 'my-key')

// Restore local component state from history state
let data = router.restore('my-key')
```

:::

> \[!WARNING]
> Some browsers limit the number of `history.replaceState()` calls allowed
> within a short time period. Inertia catches this error and logs it to the
> console, but the state update will be lost. Avoid calling `router.remember()`
> too frequently, and consider debouncing or batching state updates in
> high-frequency scenarios.

---

---
url: /guide/responses.md
---
# Responses

## Creating Responses

Creating an Inertia response is simple. By default, Inertia Rails follows convention over configuration: you pass the props (data) you wish to send to the page, and the component name is automatically inferred from the controller and action.

In the example below, we will pass a single prop (`user`) to the `users/show` page component.

```ruby
class UsersController < ApplicationController
  def show
    user = User.find(params[:id])
    render inertia: { user: } # Renders '../users/show.jsx|vue|svelte'
  end
end
```

Within Rails applications, the `UsersController#show` action would typically correspond to the file located at `app/frontend/pages/users/show.(jsx|vue|svelte)`.

> \[!WARNING]
> To ensure that pages load quickly, only return the minimum data required for the page. Also, be aware that **all data returned from the controllers will be visible client-side**, so be sure to omit sensitive information.

### Customizing the Component Path

While the default convention works for most cases, you may need to render a specific component or change how component paths are resolved globally.

#### Explicit Component Names

If you wish to render a component that does not match the current controller action, you can explicitly provide the name of the [JavaScript page component](/guide/pages) followed by the props hash.

```ruby
class EventsController < ApplicationController
  def my_event
    event = Event.find(params[:id])

    render inertia: 'events/show', props: {
      event: event.as_json(
        only: [:id, :title, :start_date, :description]
      )
    }
  end
end
```

#### Custom Path Resolver

If the default automatic path resolution does not match your project's conventions, you can define a custom resolution method via the `component_path_resolver` config value.

The value should be callable and will receive the `path` and `action` parameters, returning a string component path.

```ruby
inertia_config(
  component_path_resolver: ->(path:, action:) do
    "storefront/#{path.camelize}/#{action.camelize}"
  end
)
```

### Using Instance Variables as Props

For convenience, Inertia can automatically pass your controller's instance variables to the page component as props. To enable this behavior, invoke the `use_inertia_instance_props` method within your controller or a base controller.

```ruby
class EventsController < ApplicationController
  use_inertia_instance_props

  def index
    @events = Event.all

    render inertia: 'events/index'
  end
end
```

In this example, the `@events` instance variable is automatically included in the response as the `events` prop.

Please note that if you manually provide a props hash in your render call, the instance variables feature is disabled for that specific response.

> \[!WARNING]
> Security and Performance Risk
>
> When enabled, this feature serializes all instance variables present in the controller at the time of rendering. This includes:
>
> * Variables set by `before_action` filters (e.g., `@current_user`, `@breadcrumbs`) called **after** `use_inertia_instance_props`.
> * Memoized variables (often used for caching internal state, e.g., `@_cached_result`).
> * Variables intended only for server-side logic.
>
> This creates a high risk of accidentally leaking sensitive data or internal implementation details to the client. It can also negatively impact performance by serializing unnecessary heavy objects. We recommend being explicit with your props whenever possible.

## Properties

To pass data from the server to your page components, you can use props. You can pass various types of values as props, including primitive types, hashes, arrays, Active Record objects, lambdas, and custom objects:

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      # Primitive values
      title: 'Dashboard',
      count: 42,
      active: true,

      # Hashes and arrays
      settings: { theme: 'dark', notifications: true },

      # Active Record models and relations
      event: Event.first,
      events: Event.all,

      # Objects that respond to `to_inertia`
      avatar: UserAvatar.new(current_user, size: 128),

      # Lambdas
      timestamp: -> { Time.current.to_i },
    }
  end
end
```

Active Record models, relations, and other Ruby objects are converted with `as_json` when Inertia serializes the response. Objects that respond to `to_inertia` are converted with that method instead, as described in [the next section](#the-to-inertia-method). Lambdas run only when the response includes the prop, which makes them useful for [partial reloads](/guide/partial-reloads#lazy-data-evaluation).

Integers outside JavaScript's safe range lose precision in the browser. You may preserve them as native `BigInt` values using [big integer support](/guide/big-integers).

## The `to_inertia` Method

@available\_since rails=3.19.0

When passing props to your components, you may want to create custom classes that can transform themselves into the appropriate data format. Any object that responds to `to_inertia` can be a prop value. Inertia calls the method and sends its return value in place of the object.

```ruby
class UserAvatar
  def initialize(user, size: 64)
    @user = user
    @size = size
  end

  def to_inertia
    @user.avatar_url.presence ||
      "https://ui-avatars.com/api/?name=#{ERB::Util.url_encode(@user.name)}&size=#{@size}"
  end
end
```

Once defined, you can use this class directly as a prop value.

```ruby
class ProfilesController < ApplicationController
  def show
    user = User.find(params[:id])

    render inertia: {
      user: user.as_json(only: [:id, :name]),
      avatar: UserAvatar.new(user, size: 128),
    }
  end
end
```

Inertia also finds these objects inside nested hashes and arrays, and when a lambda or a prop type returns one. The `to_inertia` method may return a hash that contains lambdas and prop types. Inertia resolves them like any other props, including on partial reloads.

```ruby
class CourseProps
  def initialize(course)
    @course = course
  end

  def to_inertia
    course = @course

    {
      title: course.title,
      students: InertiaRails.optional { course.students.as_json(only: [:id, :name]) },
    }
  end
end
```

> \[!WARNING]
> Inertia runs lambdas and prop type blocks in the controller's context, so an instance variable like `@course` inside the block reads the controller's variable. Copy the value to a local variable first, as in the example above.

Like a lambda, `to_inertia` runs only when the response includes the prop, so a partial reload that skips the prop doesn't call it.

The `to_inertia` method receives no arguments. It can't see the prop's key, the other props, or the request, so pass anything it needs to the constructor.

### Passing an Object as Props

@available\_since rails=3.23.0

In some situations you may want to group related props together for reusability across different pages. You can pass an object that responds to `to_inertia` as the `props:` option. Its `to_inertia` method must return a hash, and each key becomes a prop.

```ruby
class UserPermissions
  def initialize(user)
    @user = user
  end

  def to_inertia
    {
      can_edit: @user.editor?,
      can_publish: @user.publisher?,
      is_admin: @user.admin?,
    }
  end
end
```

```ruby
class ProfilesController < ApplicationController
  def show
    render inertia: 'profiles/show', props: UserPermissions.new(current_user)
  end
end
```

Inertia merges [shared data](/guide/shared-data) with these props as usual. To combine the object with other props, merge its hash into a props hash:

```ruby
render inertia: {
  user: current_user.as_json(only: [:id, :name]),
  **UserPermissions.new(current_user).to_inertia,
}
```

## Root Template Data

There are situations where you may want to access your prop data in your ERB template. For example, you may want to add a meta description tag, Twitter card meta tags, or Facebook Open Graph meta tags.

Inertia Rails provides several view helpers for working with Inertia data in your templates:

### `inertia_page`

Returns the [page object](/guide/the-protocol#the-page-object) hash containing `component`, `props`, `url`, and other Inertia data. Use this to access page data in your root template.

```erb
# app/views/inertia.html.erb

<% content_for(:head) do %>
<meta name="twitter:title" content="<%= inertia_page[:props][:event][:title] %>">
<% end %>

<%= inertia_root %>
```

### `inertia_rendering?`

Returns `true` when the current request is rendering an Inertia response. This is useful for conditionally rendering content in shared layouts.

```erb
# app/views/layouts/application.html.erb

<% if inertia_rendering? %>
  <%= yield %>
<% else %>
  <div class="traditional-layout">
    <%= yield %>
  </div>
<% end %>
```

### `inertia_root`

Renders the root element for the Inertia app. This helper automatically respects the [`root_dom_id`](/guide/configuration#root-dom-id) and [`use_script_element_for_initial_page`](/guide/configuration#use-script-element-for-initial-page) configuration options.

```erb
<%= inertia_root %>
```

You can also pass a custom `id` or `page` object if needed:

```erb
<%= inertia_root(id: 'my-app', page: custom_page_object) %>
```

### `inertia_ssr_head`

Returns the SSR head content when [server-side rendering](/guide/server-side-rendering) is enabled. This should be included in your layout's `<head>` section to inject SSR-generated meta tags and other head elements.

```erb
# app/views/layouts/inertia.html.erb

<!DOCTYPE html>
<html>
  <head>
    <%= inertia_ssr_head %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>
```

@available\_since rails=3.23.0

Pass a block to render fallback head elements when the response isn't server-side rendered. When SSR is active, the `<Head>` component already provides these elements, so the block is skipped. Give fallback `<meta>` tags a `data-inertia` key, so the `<Head>` component replaces them instead of adding a duplicate.

```erb
<head>
  <%= inertia_ssr_head do %>
    <title>My App</title>
    <meta data-inertia="description" name="description" content="My application description">
  <% end %>
</head>
```

### `inertia_meta_tags`

Renders meta tags that were defined server-side using the `inertia_meta` configuration. This is useful for SEO when you want to manage meta tags from your Rails controllers. See the [Server-managed meta tags cookbook](/cookbook/server-managed-meta-tags) for a complete guide.

```erb
<head>
  <%= inertia_meta_tags %>
</head>
```

#### Default Title

@available\_since rails=3.23.0 core=3.0.1

Pass `default_title:` to render a plain `<title>` when the page has no title of its own, for example on non-Inertia pages:

```erb
<head>
  <%= inertia_meta_tags(default_title: content_for(:title) || "My App") %>
</head>
```

### Passing Additional Data to the View

Sometimes you may want to provide data to the root template that will not be sent to your JavaScript page / component. This can be accomplished by passing the `view_data` option.

```ruby
def show
  event = Event.find(params[:id])

  render inertia: { event: }, view_data: { meta: event.meta }
end
```

You can then access this variable like a regular local variable.

```erb
# app/views/inertia.html.erb

<% content_for(:head) do %>
<meta
  name="description"
  content="<%= local_assigns.fetch(:meta, "Default description") %>">
<% end %>

<%= inertia_root %>
```

## Rails Generators

Inertia Rails provides a number of generators to help you get started with Inertia in your Rails application. You can generate controllers or use scaffolds to create a new resource with Inertia responses.

### Scaffold Generator

Use the `inertia:scaffold` generator to create a resource with Inertia responses. Execute the following command in the terminal:

```bash
bin/rails generate inertia:scaffold ModelName field1:type field2:type
```

Example output:

```bash
$ bin/rails generate inertia:scaffold Post title:string body:text
      invoke  active_record
      create    db/migrate/20240611123952_create_posts.rb
      create    app/models/post.rb
      invoke    test_unit
      create      test/models/post_test.rb
      create      test/fixtures/posts.yml
      invoke  resource_route
       route    resources :posts
      invoke  scaffold_controller
      create    app/controllers/posts_controller.rb
      invoke    inertia_templates
      create      app/frontend/pages/posts
      create      app/frontend/pages/posts/index.svelte
      create      app/frontend/pages/posts/edit.svelte
      create      app/frontend/pages/posts/show.svelte
      create      app/frontend/pages/posts/new.svelte
      create      app/frontend/pages/posts/form.svelte
      create      app/frontend/pages/posts/post.svelte
      invoke    resource_route
      invoke    test_unit
      create      test/controllers/posts_controller_test.rb
      create      test/system/posts_test.rb
      invoke    helper
      create      app/helpers/posts_helper.rb
      invoke      test_unit
```

#### Tailwind CSS Integration

Inertia Rails tries to detect the presence of Tailwind CSS in the application and generate the templates accordingly. If you want to specify templates type, use the `--inertia-templates` option:

* `inertia_templates` - default
* `inertia_tw_templates` - Tailwind CSS

### Controller Generator

Use the `inertia:controller` generator to create a controller with an Inertia response. Execute the following command in the terminal:

```bash
bin/rails generate inertia:controller ControllerName action1 action2
```

Example output:

```bash
$ bin/rails generate inertia:controller pages welcome next_steps
      create  app/controllers/pages_controller.rb
       route  get 'pages/welcome'
              get 'pages/next_steps'
      invoke  test_unit
      create    test/controllers/pages_controller_test.rb
      invoke  helper
      create    app/helpers/pages_helper.rb
      invoke    test_unit
      invoke  inertia_templates
      create    app/frontend/pages/pages
      create    app/frontend/pages/pages/welcome.jsx
      create    app/frontend/pages/pages/next_steps.jsx
```

### Customizing the Generator Templates

Rails generators allow templates customization. You can create custom template files in your application to override the default templates used by the generators. For example, to customize the controller generator view template for React, create a file at the path `lib/templates/inertia_templates/controller/react/view.jsx.tt`:

```jsx
export default function <%= @action.camelize %>() {
  return (
    <h1>Hello from my new default template</h1>
  );
}
```

You can find the default templates in the gem's source code:

* [Default controller generator templates](https://github.com/inertiajs/inertia-rails/tree/master/lib/generators/inertia_templates/controller/templates)
* [Default scaffold generator templates](https://github.com/inertiajs/inertia-rails/tree/master/lib/generators/inertia_templates/scaffold/templates)
* [Tailwind controller generator templates](https://github.com/inertiajs/inertia-rails/tree/master/lib/generators/inertia_tw_templates/controller/templates)
* [Tailwind scaffold generator templates](https://github.com/inertiajs/inertia-rails/tree/master/lib/generators/inertia_tw_templates/scaffold/templates)

> \[!TIP]
> You can also replace the whole generator with your own implementation. See the [Rails documentation](https://guides.rubyonrails.org/generators.html#overriding-rails-generators) for more information.

## Maximum Response Size

To enable client-side history navigation, all Inertia server responses are stored in the browser's history state. However, keep in mind that some browsers impose a size limit on how much data can be saved within the history state.

For example, [Firefox](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) has a size limit of 16 MiB and throws a `NS_ERROR_ILLEGAL_VALUE` error if you exceed this limit. Typically, this is much more data than you'll ever practically need when building applications.

## Detecting Inertia Requests

Controllers can determine if a request was made via Inertia:

```ruby
def some_action
  if request.inertia?
  # This is an Inertia request
  end

  if request.inertia_partial?
  # This is a partial Inertia request
  end
end
```

## Inertia Responses and `respond_to`

Inertia responses always operate as a `:html` response type. This means that you can use the `respond_to` method to handle JSON requests differently, while still returning Inertia responses:

```ruby
def some_action
  respond_to do |format|
    format.html do
      render inertia: { data: 'value' }
    end

    format.json do
      render json: { message: 'This is a JSON response' }
    end
  end
end
```

---

---
url: /guide/routing.md
---
# Routing

## Defining routes

When using Inertia, all of your application's routes are defined server-side. This means that you don't need Vue Router or React Router. Instead, you can simply define Rails routes and return Inertia responses from those routes.

## Shorthand routes

If you have a page that doesn't need a corresponding controller method, like an "FAQ" or "about" page, you can route directly to a component via the `inertia` method.

```ruby
# In config/routes.rb
Rails.application.routes.draw do
  # Basic usage - maps 'dashboard' URL to 'Dashboard' component
  inertia 'dashboard' => 'Dashboard'

  # Multiple pages at once
  inertia 'about' => 'About', 'contact' => 'Contact'

  # Using a symbol - infers component name from route
  inertia :settings

  # Within namespaces and scopes
  namespace :admin do
    inertia 'dashboard' => 'Admin/Dashboard'
  end

  # Within resource definitions
  resources :users do
    inertia :activity, on: :member
    inertia :statistics, on: :collection
  end
end
```

You can also pass static props to the component:

@available\_since rails=3.22.0

```ruby
inertia 'about' => 'About', props: { title: 'About us' }
```

## Generating URLs

Some server-side frameworks allow you to generate URLs from named routes. However, you will not have access to those helpers client-side. Here are a couple ways to still use named routes with Inertia.

The first option is to generate URLs server-side and include them as props. Notice in this example how we're passing the `edit_url` and `create_url` to the `users/index` component.

```ruby
class UsersController < ApplicationController
  def index
    render inertia: {
      users: User.all.map do |user|
        user.as_json(
          only: [ :id, :name, :email ]
        ).merge(
          edit_url: edit_user_path(user)
        )
      end,
      create_url: new_user_path
    }
  end
end
```

Another option is to use [JsRoutes](https://github.com/railsware/js-routes) or [JS From Routes](https://js-from-routes.netlify.app) gems that make named server-side routes available on the client via autogenerated helpers.

### Typelizer

[Typelizer](https://github.com/skryukov/typelizer) generates typed route helpers from your Rails routes. Each helper returns an object with `url` and `method` keys. You can pass this object directly to the [Link component](/guide/links#typelizer) or [router methods](/guide/manual-visits#typelizer), and Inertia understands how to handle it.

To generate the helpers, enable route generation in your Typelizer initializer and run `bin/rails typelizer:routes`.

```ruby
# config/initializers/typelizer.rb
Typelizer.configure do |config|
  config.routes.enabled = true
end
```

Typelizer generates one module per controller, with a helper for each action.

```js
import { users } from '@/routes'

users.index() // => { url: '/users', method: 'get' }
users.show(1) // => { url: '/users/1', method: 'get' }
users.update(1) // => { url: '/users/1', method: 'patch' }
```

See the [Typelizer route helpers guide](https://typelizer.dev/guides/routes) for named route shortcuts, query strings, and other options.

---

---
url: /guide/scroll-management.md
---
# Scroll Management

## Scroll Resetting

When navigating between pages, Inertia mimics default browser behavior by automatically resetting the scroll position of the document body (as well as any [scroll regions](#scroll-regions) you've defined) back to the top.

In addition, Inertia keeps track of the scroll position of each page and automatically restores that scroll position as you navigate forward and back in history.

## Scroll Preservation

Sometimes it's desirable to prevent the default scroll resetting when making visits. You can disable this behavior by setting the `preserveScroll` option to `true`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, { preserveScroll: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, { preserveScroll: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, { preserveScroll: true })
```

:::

If you'd like to only preserve the scroll position if the response includes validation errors, set the `preserveScroll` option to `"errors"`.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit(url, { preserveScroll: 'errors' })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit(url, { preserveScroll: 'errors' })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit(url, { preserveScroll: 'errors' })
```

:::

You can also lazily evaluate the `preserveScroll` option based on the response by providing a callback.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.post('/users', data, {
  preserveScroll: (page) => page.props.someProp === 'value',
})
```

:::

When using an [Inertia link](/guide/links), you can preserve the scroll position using the `preserveScroll` prop.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/" preserve-scroll>Home</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/" preserveScroll>
    Home
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { inertia, Link } from '@inertiajs/svelte'
</script>

<a href="/" use:inertia={{ preserveScroll: true }}>Home</a>

<Link href="/" preserveScroll>Home</Link>
```

:::

## Scroll Regions

If your app doesn't use document body scrolling, but instead has scrollable elements (using the `overflow` CSS property), scroll resetting will not work.

In these situations, you must tell Inertia which scrollable elements to manage by adding the `scroll-region` attribute to the element.

```html
<div class="overflow-y-auto" scroll-region="">
  <!-- Your page content -->
</div>
```

## Text Fragments

[Text fragments](https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) allow you to link directly to specific text on a page using a special URL syntax like `#:~:text=term`. However, the browser removes the fragment directive before any JavaScript runs, so text fragments only work if the targeted text is present in the initial HTML response.

To use text fragments with your Inertia pages, enable [server-side rendering](/guide/server-side-rendering).

---

---
url: /cookbook/server-managed-meta-tags.md
---
# Server Managed Meta Tags

Inertia Rails can manage a page's meta tags on the server instead of on the frontend. This means that link previews (such as on Facebook, LinkedIn, etc.) will include correct meta *without server-side rendering*.

Inertia Rails renders server defined meta tags into both the server rendered HTML and the client-side Inertia page props. Because the tags share unique `head-key` attributes, the client will "take over" the meta tags after the initial page load.

@available\_since rails=3.10.0

## Setup

### Server Side

Simply add the `inertia_meta_tags` helper to your layout. This will render the meta tags in the `<head>` section of your HTML.

Apps generated with the `inertia:install` generator have this preconfigured: the layout's `<title>` tag is replaced with `inertia_meta_tags(default_title: content_for(:title) || "My App")`, which renders `default_title` when the page has no title of its own, including on non-Inertia pages. For client-side visits, the generated React and Vue entrypoints fall back to the same name with `title: (title) => title || "My App"`. The Svelte adapter has no title callback.

```erb
<!-- app/views/layouts/application.html.erb (or your custom layout) -->

<!DOCTYPE html>
<html>
  <head>
    ...
    <%= inertia_meta_tags %> <!-- Add this inside your <head> tag --> // [!code ++]
    <title inertia>My Inertia App</title> <!-- Remove existing title --> // [!code --]
  </head>
</html>
```

> \[!NOTE]
> Make sure to remove the `<title>` tag in your Rails layout if you plan to manage it with Inertia Rails. Otherwise you will end up with duplicate `<title>` tags. To keep a fallback for pages without a title, pass [`default_title:`](/guide/responses#default-title) to `inertia_meta_tags` or configure a callable [title template](#title-template).

### Client Side

#### Inertia.js v3.5+

@available\_since rails=3.23.0 core=3.5.0

Since v3.5.0, Inertia.js natively supports [server-provided head elements](https://github.com/inertiajs/inertia/pull/3161) via the `serverHead` option of `createInertiaApp`. Apps generated with the `inertia:install` generator have this preconfigured; in existing apps, enable HTML string serialization on the server:

```ruby
InertiaRails.configure do |config|
  config.server_head = true
end
```

Then enable the matching option on the client:

```js
createInertiaApp({
  serverHead: true,
  // ...
})
```

That's it, no custom component is needed. This works in React, Vue, and Svelte (even though Svelte has no `<Head>` component), meta tags re-sync on every navigation including partial reloads, and page-level `<Head>` elements override server tags with a matching `head-key`.

The meta tags travel in the `head` prop. If your app already uses a prop with that name, Inertia Rails raises an error on the conflict. Pick a custom name and pass it on both sides: `config.server_head = 'server_meta'` and `serverHead: 'server_meta'`. In tests, note that the prop contains rendered HTML strings rather than structured hashes.

> \[!WARNING]
> Enable both sides together. With `serverHead` set on the client but `config.server_head` disabled (or vice versa), meta tags silently disappear: the client reads a prop the server doesn't send, and the cookbook component below cannot render HTML strings.

> \[!NOTE]
> When using [SSR](/guide/server-side-rendering), pass the same `serverHead` option to `createInertiaApp` in your SSR entrypoint. The tags are then delivered through `inertia_ssr_head` instead. Keep both helpers in your layout. Exactly one of them renders per response, so the tags never duplicate: `inertia_meta_tags` is empty on SSR-rendered responses (except for its `default_title` when the SSR head has no `<title>`), and `inertia_ssr_head` is empty when SSR is disabled or falls back.

#### Older clients (cookbook component)

For Inertia.js clients older than v3.5, copy the following code into your application instead. It should be rendered **once** in your application, such as in a [layout component](/guide/layouts#creating-layouts).

> \[!NOTE]
> These components are written for Inertia.js v2. On v3.0 to v3.4, upgrade to v3.5 or newer and use the [`serverHead` option](#inertia-js-v3-5) instead.

:::tabs key:frameworks
\== Vue

```vue
<script>
import { Head } from '@inertiajs/vue3'
import { usePage } from '@inertiajs/vue3'
import { h } from 'vue'

export default {
  name: 'MetaTags',
  setup() {
    const page = usePage()

    return () => {
      const metaTags = page.props._inertia_meta || []

      return h(Head, {}, () =>
        metaTags.map((meta) => {
          const { tagName, innerContent, headKey, httpEquiv, ...attrs } = meta

          const attributes = {
            key: headKey,
            'head-key': headKey,
            ...attrs,
          }

          if (httpEquiv) {
            attributes['http-equiv'] = httpEquiv
          }

          let content = null
          if (innerContent != null) {
            content =
              typeof innerContent === 'string'
                ? innerContent
                : JSON.stringify(innerContent)
          }

          return h(tagName, attributes, content)
        }),
      )
    }
  },
}
</script>
```

\== React

```jsx
import React from 'react'
import { Head, usePage } from '@inertiajs/react'

const MetaTags = () => {
  const { _inertia_meta: meta } = usePage().props
  return (
    <Head>
      {meta.map((meta) => {
        const { tagName, innerContent, headKey, httpEquiv, ...attrs } = meta

        let stringifiedInnerContent
        if (innerContent != null) {
          stringifiedInnerContent =
            typeof innerContent === 'string'
              ? innerContent
              : JSON.stringify(innerContent)
        }

        return React.createElement(tagName, {
          key: headKey,
          'head-key': headKey,
          ...(httpEquiv ? { 'http-equiv': httpEquiv } : {}),
          ...attrs,
          ...(stringifiedInnerContent
            ? { dangerouslySetInnerHTML: { __html: stringifiedInnerContent } }
            : {}),
        })
      })}
    </Head>
  )
}

export default MetaTags
```

\== Svelte

```svelte
<!-- MetaTags.svelte -->
<script>
  import { onMount } from 'svelte'
  import { page } from '@inertiajs/svelte'

  $: metaTags = ($page.props._inertia_meta ?? []).map(
    ({ tagName, headKey, innerContent, httpEquiv, ...attrs }) => ({
      tagName,
      headKey,
      innerContent,
      attrs: httpEquiv ? { ...attrs, 'http-equiv': httpEquiv } : attrs,
    }),
  )

  // Svelte throws warnings if we render void elements like meta with content
  $: voidTags = metaTags.filter((tag) => tag.innerContent == null)
  $: contentTags = metaTags.filter((tag) => tag.innerContent != null)

  let ready = false

  onMount(() => {
    // Clean up server-rendered tags
    document.head.querySelectorAll('[inertia]').forEach((el) => el.remove())

    ready = true
  })
</script>

<svelte:head>
  {#if ready}
    <!-- Void elements (no content) -->
    {#each voidTags as tag (tag.headKey)}
      <svelte:element this={tag.tagName} inertia={tag.headKey} {...tag.attrs} />
    {/each}

    <!-- Elements with content -->
    {#each contentTags as tag (tag.headKey)}
      <svelte:element this={tag.tagName} inertia={tag.headKey} {...tag.attrs}>
        {@html typeof tag.innerContent === 'string'
          ? tag.innerContent
          : JSON.stringify(tag.innerContent)}
      </svelte:element>
    {/each}
  {/if}
</svelte:head>
```

:::

## Rendering Meta Tags

Tags are defined as plain hashes and conform to the following structure:

```ruby
# All fields are optional.
{
  # Defaults to "meta" if not provided
  tag_name: "meta",

  # Used for <meta http-equiv="...">
  http_equiv: "Content-Security-Policy",

  # Used to deduplicate tags. InertiaRails will auto-generate one if not provided
  head_key: "csp-header",

  # Used with <script>, <title>, etc.
  inner_content: "Some content",

  # Any additional attributes will be passed directly to the tag.
  # For example: name: "description", content: "Page description"
  name: "description",
  content: "A description of the page"
}
```

The `<title>` tag has shortcut syntax:

```ruby
{ title: "The page title" }
```

### In the renderer

Add meta tags to an action by passing an array of hashes to the `meta:` option in the `render` method:

```ruby
class EventsController < ApplicationController
  def show
    event = Event.find(params[:id])

    render inertia: { event: event.as_json }, meta: [
      { title: "Check out the #{event.name} event!" },
      { name: 'description', content: event.description },
      { tag_name: 'script', type: 'application/ld+json', inner_content: { '@context': 'https://schema.org', '@type': 'Event', name: 'My Event' } }
    ]
  end
end
```

### Shared Meta Tags

Often, you will want to define default meta tags that are shared across certain pages and which you can override within a specific controller or action. Inertia Rails has an `inertia_meta` controller instance method which references a store of meta tag data.

You can call it anywhere in a controller to manage common meta tags, such as in `before_action` callbacks or directly in an action.

```ruby
class EventsController < ApplicationController
  before_action :set_meta_tags

  def show
    render inertia: { event: Event.find(params[:id]) }
  end

  private

  def set_meta_tags
    inertia_meta.add([
      { title: 'Look at this event!' }
    ])
  end
end
```

#### The `inertia_meta` API

The `inertia_meta` method provides a simple API to manage your meta tags. You can add, remove, or clear tags as needed. The `inertia_meta.remove` method accepts either a `head_key` string or a block to filter tags.

```ruby
# Add a single tag
inertia_meta.add({ title: 'Some Page title' })

# Add multiple tags at once
inertia_meta.add([
  { tag_name: 'meta', name: 'og:description', content: 'A description of the page' },
  { tag_name: 'meta', name: 'twitter:title', content: 'A title for Twitter' },
  { tag_name: 'title', inner_content: 'A title for the page', head_key: 'my_custom_head_key' },
  { tag_name: 'script', type: 'application/ld+json', inner_content: { '@context': 'https://schema.org', '@type': 'Event', name: 'My Event' } }
])

# Read the current page title
inertia_meta.title # => "A title for the page"

# Remove a specific tag by head_key
inertia_meta.remove("my_custom_head_key")

# Remove tags by a condition
inertia_meta.remove do |tag|
  tag[:tag_name] == 'script' && tag[:type] == 'application/ld+json'
end

# Remove all tags
inertia_meta.clear
```

#### JSON-LD and Script Tags

Inertia Rails supports defining `<script>` tags with `type="application/ld+json"` for structured data. All other script tags will be marked as `type="text/plain"` to prevent them from executing on the client side. Executable scripts should be added either in the Rails layout or using standard techniques in your frontend framework.

```ruby
inertia_meta.add({
  tag_name: "script",
  type: "application/ld+json",
  inner_content: {
    "@context": "https://schema.org",
    "@type": "Event",
    name: "My Event",
    startDate: "2023-10-01T10:00:00Z",
    location: {
      "@type": "Place",
      name: "Event Venue",
      address: "123 Main St, City, Country"
    }
  }
})
```

## Title Template

@available\_since rails=3.23.0

Instead of repeating an app-wide suffix in every action, configure a title template — the server-side counterpart of the [title callback](/guide/title-and-meta#title-callback). It receives the current title (or `nil` when the page sets none), runs in the controller context, and its result becomes the title:

```ruby
InertiaRails.configure do |config|
  config.meta_title_template = ->(title) { title ? "#{title} - My App" : 'My App' }
end
```

With this template, `inertia_meta.add({ title: 'Events' })` renders `<title>Events - My App</title>` — in the server-rendered HTML too, so crawlers and link previews see the full title without running JavaScript. Because the template runs even when no title is set, it doubles as a default title for pages that define no meta tags at all.

The template only sees titles set on the server: titles set with `<Head>` in components skip it. The template also only applies to Inertia responses, so `default_title` on the `inertia_meta_tags` helper still covers non-Inertia pages.

> \[!WARNING]
> Don't combine a server-side title template with the client-side [title callback](/guide/title-and-meta#title-callback) — the client applies its callback on top of the server-provided title, so the suffix would appear twice. Use one or the other. A callback that only fills in a missing title, such as `(title) => title || "My App"`, is safe to keep.

## Deduplication

> \[!NOTE]
> The Svelte adapter does not have a `<Head />` component. Inertia Rails will deduplicate meta tags *on the server*, and the Svelte component above will render them deduplicated accordingly.

### Automatic Head Keys

Inertia Rails relies on the `head-key` attribute and the `<Head />` components that the Inertia.js core uses to [manage meta tags](/guide/title-and-meta) and deduplicate them. Inertia.js core expects us to manage `head-key` attributes and deduplication manually, but Inertia Rails will generate them automatically for you.

* `<meta>` tags will use the `name`,`property`, or `http_equiv` attributes to generate a head key. This enables automatic deduplication of common meta tags like `description`, `og:title`, and `twitter:card`.
* All other tags will deterministically generate a `head-key` based on the tag's attributes.

#### Allowing Duplicates

Sometimes, it is valid HTML to have multiple meta tags with the same name or property. If you want to allow duplicates, you can set the `allow_duplicates` option to `true` when defining the tag.

```ruby
class StoriesController < ApplicationController
  before_action do
    inertia_meta.add({ name: 'article:author', content: 'Tony Gilroy' })
  end

  # Renders a single article:author meta tag
  def single_author
    render inertia: 'stories/show'
  end

  # Renders multiple article:author meta tags
  def multiple_authors
    render inertia: 'stories/show', meta: [
      { name: 'article:author', content: 'Dan Gilroy', allow_duplicates: true },
    ]
  end
end
```

### Manual Head Keys

Automatic head keys should cover the majority of use cases, but you can set `head_key` manually if you need to control the deduplication behavior more precisely. For example, you may want to do this if you know you will remove a shared meta tag in a specific action.

```ruby
# In a concern or `before_action` callback
inertia_meta.add([
  {
    tag_name: 'meta',
    name: 'description',
    content: 'A description of the page',
    head_key: 'my_custom_head_key'
  },
])

# Later in a specific action
inertia_meta.remove('my_custom_head_key')
```

## Combining Meta Tag Methods

There are multiple ways to manage meta tags in Inertia Rails:

* Adding tags to a Rails layout such as `application.html.erb`.
* Using the `<Head />` component from Inertia.js (or the Svelte head element) in the frontend.
* Using the server driven meta tags feature described here.

Nothing prevents you from using these together, but for organizational purposes, we recommended using only one of the last two techniques.

---

---
url: /guide/server-side-rendering.md
---
# Server-Side Rendering (SSR)

Server-side rendering pre-renders your JavaScript pages on the server, allowing your visitors to receive fully rendered HTML when they visit your application. Since fully rendered HTML is served by your application, it's also easier for search engines to index your site.

Server-side rendering uses Node.js to render your pages in a background process; therefore, Node must be available on your server for server-side rendering to function properly. Inertia's SSR server requires Node.js 22 or higher.

## Starter Kits

The [Inertia Rails starter kits](/guide/starter-kits) ship with optional SSR support. Each kit's README explains how to turn it on.

## Vite Plugin Setup

@available\_since rails=3.19.0 core=3.0.0

The recommended way to configure SSR is with the `@inertiajs/vite` plugin. This approach handles SSR configuration automatically, including development mode SSR without a separate Node.js server.

### 1. Install the Vite plugin

```bash
npm install @inertiajs/vite
```

### 2. Configure Vite

Add the Inertia plugin to your `vite.config.js` file. And configure entry point.

```js
// vite.config.js
import inertia from '@inertiajs/vite'

export default defineConfig({
  plugins: [
    // ...
    inertia({
      ssr: {
        entry: 'entrypoints/inertia.js',
      },
    }),
  ],
})
```

You may also configure SSR options explicitly.

```js
// vite.config.js
inertia({
  ssr: {
    entry: 'ssr/ssr.js',
    port: 13714,
    cluster: true,
  },
})
```

You may pass `false` to opt out of the plugin's automatic SSR handling, for example if you prefer to [configure SSR manually](#manual-setup) or [disable SSR entirely](#disabling-ssr).

```js
// vite.config.js
inertia({
  ssr: false,
})
```

### 3. Update your build script

Update the `build` script in your `package.json` to build both bundles.

```json
{
  "scripts": {
      "dev": "vite",
     "build": "vite build" // [!code --]
     "build": "vite build && vite build --ssr" // [!code ++]
  }
}
```

### Development Mode

The Vite plugin handles SSR automatically during development. There is no need to build your SSR bundle or start a separate Node.js server. Simply run your dev servers as usual:

```bash
bin/dev
```

The Vite plugin exposes a server endpoint that Rails uses for rendering, complete with HMR support.

> \[!NOTE]
> The `vite build --ssr`, `bin/vite ssr`, etc. commands are for [production](#production) only. You should not run them during development.

### Production

For production, build both bundles and start the SSR server.

```bash
npm run build
node public/vite-ssr/inertia.js
```

### Custom SSR Entry Point

The Vite plugin reuses your `inertia.js` entry point for both browser and SSR rendering by default, so no separate file is needed. The plugin detects the `data-server-rendered` attribute to decide whether to hydrate or mount, and the `setup` and `resolve` callbacks are optional.

Most app customizations, such as registering plugins or wrapping with providers, may be handled using the [`withApp` callback](/guide/client-side-setup#customizing-the-app) in your main entry point. A separate SSR entry point is only needed when you require completely different setup logic for the server.

You may create a separate `app/frontend/ssr/ssr.js` file for this purpose.

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'

createServer((page) =>
  createInertiaApp({
    page,
    render: renderToString,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.vue')
      return pages[`../pages/${name}.vue`]()
    },
    setup({ App, props, plugin }) {
      return createSSRApp({
        render: () => h(App, props),
      }).use(plugin)
    },
  }),
)
```

\== React

```jsx
import { createInertiaApp } from '@inertiajs/react'
import createServer from '@inertiajs/react/server'
import ReactDOMServer from 'react-dom/server'

createServer((page) =>
  createInertiaApp({
    page,
    render: ReactDOMServer.renderToString,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.jsx')
      return pages[`../pages/${name}.jsx`]()
    },
    setup: ({ App, props }) => <App {...props} />,
  }),
)
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'
import createServer from '@inertiajs/svelte/server'
import { render } from 'svelte/server'

createServer((page) =>
  createInertiaApp({
    page,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.svelte')
      return pages[`../pages/${name}.svelte`]()
    },
    setup({ App, props }) {
      return render(App, { props })
    },
  }),
)
```

:::

Be sure to add anything that's missing from your `inertia.js` file that makes sense to run in SSR mode, such as plugins or custom mixins.

### Host

@available\_since core=3.1.0

By default, the SSR server binds to `0.0.0.0`, making it accessible on all network interfaces. You may restrict it to a specific interface using the `host` option.

```js
// vite.config.js
inertia({
  ssr: {
    host: '127.0.0.1',
  },
})
```

## Manual Setup

If you prefer not to use the Vite plugin, you may configure SSR manually.

### 1. Create an SSR entry point

Create an SSR entry point file in your Rails app.

:::tabs key:frameworks
\== Vue

```bash
touch app/frontend/ssr/ssr.js
```

\== React

```bash
touch app/frontend/ssr/ssr.jsx
```

\== Svelte

```bash
touch app/frontend/ssr/ssr.js
```

:::

This file will look similar to your app entry point, but it runs in Node.js instead of the browser. Here's a complete example.

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'

createServer((page) =>
  createInertiaApp({
    page,
    render: renderToString,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.vue')
      return pages[`../pages/${name}.vue`]()
    },
    setup({ App, props, plugin }) {
      return createSSRApp({
        render: () => h(App, props),
      }).use(plugin)
    },
  }),
)
```

\== React

```jsx
import { createInertiaApp } from '@inertiajs/react'
import createServer from '@inertiajs/react/server'
import ReactDOMServer from 'react-dom/server'

createServer((page) =>
  createInertiaApp({
    page,
    render: ReactDOMServer.renderToString,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.jsx')
      return pages[`../pages/${name}.jsx`]()
    },
    setup: ({ App, props }) => <App {...props} />,
  }),
)
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'
import createServer from '@inertiajs/svelte/server'
import { render } from 'svelte/server'

createServer((page) =>
  createInertiaApp({
    page,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.svelte')
      return pages[`../pages/${name}.svelte`]()
    },
    setup({ App, props }) {
      return render(App, { props })
    },
  }),
)
```

:::

### 2. Configure Vite

Next, we need to update our Vite configuration to build our new `ssr.js` file. We can do this by adding a `ssrBuildEnabled` property to Ruby Vite plugin configuration in the `config/vite.json` file.

```json
"production": {
  "ssrBuildEnabled": true
}
```

### 3. Enable SSR in the Inertia's Rails adapter

Update Inertia Rails adapter config to turn SSR on.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_enabled = ViteRuby.config.ssr_build_enabled
end
```

### Client-Side Hydration

You should also update your `inertia.js` file to use hydration instead of normal rendering. This allows VueReactSvelte to pick up the server-rendered HTML and make it interactive without re-rendering it.

:::tabs key:frameworks

\== Vue

```js
import { createApp, h } from 'vue' // [!code --]
import { createSSRApp, h } from 'vue' // [!code ++]
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.vue')
    return pages[`../pages/${name}.vue`]()
  },
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) }) // [!code --]
    createSSRApp({ render: () => h(App, props) }) // [!code ++]
      .use(plugin)
      .mount(el)
  },
})
```

\== React

```js
import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client' // [!code --]
import { hydrateRoot } from 'react-dom/client' // [!code ++]

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.jsx')
    return pages[`../pages/${name}.jsx`]()
  },
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />) // [!code --]
    hydrateRoot(el, <App {...props} />) // [!code ++]
  },
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'
import { mount } from 'svelte' // [!code --]
import { hydrate, mount } from 'svelte' // [!code ++]

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob('../pages/**/*.svelte')
    return pages[`../pages/${name}.svelte`]()
  },
  setup({ el, App, props }) {
    mount(App, { target: el, props }) // [!code --]
    if (el.dataset.serverRendered === 'true') {
      // [!code ++:5]
      hydrate(App, { target: el, props })
    } else {
      mount(App, { target: el, props })
    }
  },
})
```

:::

### Opting Out of the Vite Plugin

You may pass `ssr: false` to the Inertia plugin to disable its automatic SSR handling and manage the SSR build yourself.

```js
// vite.config.js
export default defineConfig({
  plugins: [
    RubyPlugin(),
    inertia({
      ssr: false, // [!code ++]
    }),
  ],
})
```

Vite Ruby then builds your SSR entry point on its own. Its default `ssrEntrypoint` setting (`~/ssr/ssr.{js,ts,jsx,tsx}`) already matches `app/frontend/ssr/ssr.js`, so `bin/vite build --ssr` builds it to `public/vite-ssr`. The `ssrBuildEnabled` option from step 2 adds this build to `assets:precompile`.

### Clustering

By default, the SSR server runs on a single thread. You may enable clustering to start multiple Node servers on the same port, with requests handled by each thread in a round-robin fashion.

```js
// vite.config.js
inertia({
  ssr: {
    cluster: true,
  },
})
```

When using a [custom SSR entry point](#custom-ssr-entry-point) or [manual setup](#manual-setup), you may pass the `cluster` option to `createServer` instead.

@available\_since core=2.0.7

:::tabs key:frameworks

\== Vue

```js
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { cluster: true },
)
```

\== React

```jsx
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { cluster: true },
)
```

\== Svelte

```js
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { cluster: true },
)
```

:::

### Host

@available\_since core=3.1.0

By default, the SSR server binds to `0.0.0.0`, making it accessible on all network interfaces. You may pass the `host` option to `createServer` to restrict it to a specific interface.

:::tabs key:frameworks

\== Vue

```js
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { host: '127.0.0.1' },
)
```

\== React

```jsx
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { host: '127.0.0.1' },
)
```

\== Svelte

```js
createServer(
  (page) =>
    createInertiaApp({
      // ...
    }),
  { host: '127.0.0.1' },
)
```

:::

## Running the SSR Server

> \[!NOTE]
> The SSR server is only required in production. During development, the [Vite plugin](#development-mode) handles SSR automatically.

### Puma Plugin

@available\_since rails=3.20.0

The recommended way to run the SSR server in production is with the built-in Puma plugin. Add the plugin to your Puma configuration:

```ruby
# config/puma.rb
plugin :inertia_ssr
```

The plugin automatically starts and stops the SSR Node.js process alongside Puma. It handles health checks, automatic restarts on crashes, and graceful shutdown. No separate process management (systemd, Procfile, etc.) is needed.

The plugin starts the SSR server whenever the SSR bundle is found, even if `ssr_enabled` is `false` globally, so SSR enabled per controller with `inertia_config` works. It is a no-op when the bundle is not found or the Vite dev server is running, so it is safe to add unconditionally.

#### Bundle Resolution

The plugin locates the SSR bundle using the following rules, in order:

1. **Explicit config** — `config.ssr_bundle` (a path or an array of paths; the first existing file wins).
2. **ViteRuby output** — if ViteRuby is loaded, it globs `<ssr_output_dir>/*.js`.
3. **`ssr/` directory** — globs `ssr/*.js` in the project root (matches the `@inertiajs/vite` plugin's default SSR build output).
4. **Legacy fallback** — checks `public/assets-ssr/*.js`.

If none of the above finds a file, the plugin logs nothing and stays idle.

#### Runtime Detection

The JavaScript runtime is auto-detected from your lockfile (`bun.lock` or `bun.lockb` → Bun, `deno.lock` → Deno, otherwise Node.js). To override:

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_runtime = "bun"
end
```

### Manual

If you are not using Puma, or prefer to manage the SSR process yourself, start the SSR server manually:

```bash
bin/vite ssr
```

With the server running, you should be able to access your app within the browser with server-side rendering enabled. In fact, you should be able to disable JavaScript entirely and still navigate around your application.

## Error Handling

When SSR rendering fails, Inertia gracefully falls back to client-side rendering. The Vite plugin logs detailed error information to the console, including the component name, request URL, source location, and a tailored hint to help you resolve the issue.

Common SSR errors are automatically classified. Browser API errors (such as referencing `window` or `document` in server-rendered code) include guidance on moving the code to a lifecycle hook. Components that depend on browser APIs may also be wrapped in [`WhenMounted`](#client-only-components). Component resolution errors suggest checking file paths and casing.

The Rails adapter always logs SSR failures to `Rails.logger` at the `error` level, so a failure is never silent. Beyond that, exactly one of the following applies:

1. Your `on_ssr_error` callback is called, if you defined one.
2. Otherwise, the error is reported to the Rails error reporter — unless `ssr_raise_on_error` is enabled, in which case the raised error is left to Rails' exception middleware.

### Reporting to the Error Reporter

@available\_since rails=3.23.0

When no `on_ssr_error` callback is configured, SSR failures are reported through `Rails.error`, so error trackers that subscribe to the Rails error reporter pick them up without any extra wiring. (Requires Rails 7.0 or newer; on older versions the log line above is the only output.)

Reports are sent with `handled: true`, which implies a default severity of `:warning` — the request still succeeds by falling back to client-side rendering, so these are not request-level failures. On Rails 7.1 and newer they are also tagged with `source: "inertia_rails"`. Every report carries the following context, with any keys the error does not supply omitted:

| Context key           | Description                                                                        |
| --------------------- | ---------------------------------------------------------------------------------- |
| `component`           | The Inertia component that failed to render                                        |
| `ssr_type`            | Error classification from the SSR server, or `"connection"` for transport failures |
| `ssr_hint`            | Remediation hint from the SSR server, when available                               |
| `ssr_stack`           | The JavaScript stack trace from the SSR server                                     |
| `ssr_source_location` | The originating file and line in your front-end code                               |

Because subscribers receive the source, you can route or ignore these separately from the rest of your application's errors (Rails 7.1+):

```ruby
class MySubscriber
  def report(error, handled:, severity:, context:, source: nil)
    return if source == 'inertia_rails'

    # ...
  end
end
```

For connection failures, the `InertiaRails::SSRError` wraps the underlying exception as its `cause`, so trackers display the full chain — `Errno::ECONNREFUSED` and friends are not hidden behind the wrapper.

### Customizing Error Handling

To handle SSR failures yourself, set the `on_ssr_error` option in your `config/initializers/inertia_rails.rb` file.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.on_ssr_error = ->(error, page) do
    Rails.logger.warn("SSR failed for #{page[:component]}: #{error.message}")
    Sentry.capture_exception(error) # or any error tracker
  end
end
```

The callback receives an `InertiaRails::SSRError` and the page hash, giving you access to the component name, props, and URL that failed.

> \[!NOTE]
> Defining `on_ssr_error` **replaces** the automatic report to `Rails.error` — the callback becomes solely responsible for reporting. This applies even when your callback does something unrelated to reporting, such as incrementing a metric. To keep the automatic report as well, call `Rails.error.report(error, handled: true, source: 'inertia_rails')` from within your callback. Logging to `Rails.logger` is unaffected either way.

### Raising on Error

Since Inertia falls back to client-side rendering, SSR failures may go unnoticed. Your tests pass because the client-side render succeeds, but your users never receive server-rendered HTML. This is especially common in system tests.

You may set the `ssr_raise_on_error` option in your `config/initializers/inertia_rails.rb` file to raise an exception instead of falling back, so you catch SSR issues early.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_raise_on_error = Rails.env.test?
end
```

> \[!WARNING]
> This option is not recommended for production. SSR failures will return an error response instead of falling back to client-side rendering.

You may also set the `INERTIA_SSR_RAISE_ON_ERROR` environment variable to `true`, for example on CI. It only applies when your initializer does not set the option.

## SSR Response Caching

@available\_since rails=3.19.0

SSR rendering sends a request to the Node.js server for every page load. You can cache these responses to avoid redundant renders when the same page data is served repeatedly.

### Enabling SSR Caching

Set `ssr_cache` in your initializer:

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_cache = true
end
```

When enabled, the SSR response is cached using an MD5 digest of the page JSON as the cache key. Identical page data produces the same key, so the Node.js server is only called once per unique page.

### Cache Options

Pass a hash to control cache behavior:

```ruby
InertiaRails.configure do |config|
  config.ssr_cache = { expires_in: 1.hour }
end
```

### Dynamic Configuration

Use a lambda for per-request control. The lambda is evaluated in the controller context:

```ruby
InertiaRails.configure do |config|
  config.ssr_cache = -> { { expires_in: action_name == 'index' ? 1.hour : 5.minutes } }
end
```

### Per-Render Override

Override the global setting on individual render calls:

```ruby
class PostsController < ApplicationController
  def show
    render inertia: 'Posts/Show',
      props: { post: @post.as_json },
      ssr_cache: false  # skip caching for this render
  end
end
```

### Development Mode

SSR caching is automatically disabled when the Vite dev server is running, since dev responses change frequently and should not be cached.

### Cache Store

SSR caching uses the same [`cache_store`](/guide/configuration#cache-store) as [cached props](/guide/cached-props). SSR cache keys are prefixed with `inertia_ssr/`.

## Disabling SSR

SSR has two layers: the **Vite plugin** serves SSR during development and builds the SSR bundle for production, while the **Rails adapter** dispatches rendering requests to the SSR server. To fully disable SSR, you should disable both.

```js
// vite.config.js
inertia({
  ssr: false,
})
```

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_enabled = false
end
```

To keep SSR in your build but skip it in tests, see [Disabling SSR During Tests](/guide/testing#disabling-ssr-during-tests).

## Excluding Controllers from SSR

Sometimes you may wish to skip server-side rendering for certain controllers while keeping SSR enabled for the rest of your application.

```ruby
class AdminController < ApplicationController
  inertia_config(ssr_enabled: false)
end
```

You can also use a lambda for conditional SSR, which is evaluated per-request in the controller context:

```ruby
class DashboardController < ApplicationController
  inertia_config(ssr_enabled: -> { !complex_client_only_page? })
end
```

## Client-Only Components

@available\_since core=3.8.0

Sometimes, a component relies on browser APIs such as `window` or `document` and cannot be rendered on the server. Instead of disabling SSR for the entire page, you may wrap the component in `WhenMounted`, which renders its children only after mounting in the browser. The `fallback` is rendered on the server and during hydration instead.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { WhenMounted } from '@inertiajs/vue3'
import Chart from '@/components/Chart.vue'
</script>

<template>
  <WhenMounted>
    <template #fallback>
      <div>Loading chart...</div>
    </template>

    <Chart />
  </WhenMounted>
</template>
```

\== React

```jsx
import { WhenMounted } from '@inertiajs/react'
import Chart from '@/components/Chart'

export default () => (
  <WhenMounted fallback={<div>Loading chart...</div>}>
    <Chart />
  </WhenMounted>
)
```

\== Svelte

```svelte
<script>
  import { WhenMounted } from '@inertiajs/svelte'
  import Chart from '@/components/Chart.svelte'
</script>

<WhenMounted>
  {#snippet fallback()}
    <div>Loading chart...</div>
  {/snippet}

  <Chart />
</WhenMounted>
```

:::

The fallback only appears on the initial server-rendered page load. Subsequent visits, as well as applications not using SSR, render the children immediately.

JSX children are evaluated before `WhenMounted` renders, so expressions that access `window` directly still run on the server. You may pass a function as the children to defer their evaluation until the component mounts.

```jsx
<WhenMounted fallback={<div>Loading chart...</div>}>
  {() => <Chart width={window.innerWidth} />}
</WhenMounted>
```

Note that `WhenMounted` only skips rendering on the server. The wrapped component is still part of your SSR bundle, so its module must be safe to import on the server.

## Deployment

When deploying your SSR enabled app to production, build both the client-side (`application.js`) and server-side bundles (`ssr.js`), and then run the SSR server as a background process — either via the [Puma plugin](#puma-plugin) or manually.

> \[!NOTE]
> The Puma plugin expects Node.js (or your configured runtime) to be available in the same environment as Puma. For containerized deployments where the SSR server runs in a separate container, skip the plugin and point `ssr_url` to the SSR container instead.

---

---
url: /guide/server-side-setup.md
---
# Server-Side Setup

The first step when installing Inertia is to configure your server-side framework.

> \[!NOTE]
> For the official Laravel adapter instructions, please see the [official documentation](https://inertiajs.com/docs/v3/installation/server-side-setup).

> \[!TIP]
> The [Inertia Rails starter kits](/guide/starter-kits) provide out-of-the-box scaffolding for new Inertia applications. They're the fastest way to start a new project. To install Inertia into an existing application, follow the steps below.

## Install Dependencies

First, install the Inertia server-side adapter gem and add to the application's Gemfile by executing:

```bash
bundle add inertia_rails
```

## Rails Generator

If you plan to use Vite as your frontend build tool, you can use the built-in generator to install and set up Inertia in a Rails application. It automatically detects if the [Vite Rails](https://vite-ruby.netlify.app/guide/rails.html) gem is installed and will attempt to install it if not present.

To install and setup Inertia in a Rails application, execute the following command in the terminal:

```bash
bin/rails generate inertia:install
```

This command will:

* Check for Vite Rails and install it if not present
* Ask if you want to use TypeScript
* Ask you to choose your preferred frontend framework (React, Vue, Svelte)
* Ask if you want to install Tailwind CSS
* Install necessary dependencies
* Set up the application to work with Inertia
* Copy example Inertia controller and views (can be skipped with the `--skip-example-page` option)

With that done, you can now start the Rails server and the Vite development server (we recommend using [Overmind](https://github.com/DarthSim/overmind)):

```bash
bin/dev
```

And navigate to `http://localhost:3000/inertia-example` to see the example Inertia page.

That's it! You're all set up to start using Inertia in your Rails application. Check the guide on [creating pages](/guide/pages) to know more.

## Root Template

If you decide not to use the generator, you can manually set up Inertia in your Rails application.

First, setup the root template that will be loaded on the first page visit. This will be used to load your site assets (CSS and JavaScript), and will also contain a root `<div>` to boot your JavaScript application in.

:::tabs key:builders
\== Vite

```erb
<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csp_meta_tag %>

    <%= inertia_ssr_head %>

    <%# If you want to use React add `vite_react_refresh_tag` %>
    <%= vite_client_tag %>
    <%= vite_javascript_tag 'application' %>
  </head>

  <body>
    <%= yield %>
  </body>
</html>
```

\== Webpacker/Shakapacker

```erb
<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csp_meta_tag %>

    <%= inertia_ssr_head %>

    <%= stylesheet_pack_tag 'application' %>
    <%= javascript_pack_tag 'application', defer: true %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>
```

:::

This template should include your assets, as well as the `yield` method to render the Inertia page. The `inertia_ssr_head` method is used to include the Inertia headers in the response, it's required when [SSR](/guide/server-side-rendering.md) is enabled.

You may also render [fallback head elements](/guide/title-and-meta#ssr-fallback) when SSR is not active.

Inertia's adapter will use standard Rails layout inheritance, with `app/views/layouts/application.html.erb` as a default layout. If you would like to use a different layout, set it with the Rails `layout` method in your controller.

```ruby
class EventsController < ApplicationController
  layout 'my_inertia_layout'
end
```

## Configuration

Next, create an initializer. Inertia.js v3 clients need the `use_script_element_for_initial_page`, `use_data_inertia_head_attribute`, and `always_include_errors_hash` options. The `version` option sets your [asset version](/guide/asset-versioning). The Rails generator sets all of them for you.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.version = ViteRuby.digest # or any other versioning method
  config.use_script_element_for_initial_page = true
  config.use_data_inertia_head_attribute = true
  config.always_include_errors_hash = true
end
```

See the [configuration](/guide/configuration) guide for all available options.

## Base Controller

Inertia Rails adds its middleware and controller methods automatically, so there's nothing to register. To define [shared data](/guide/shared-data) for your Inertia pages, call `inertia_share` in a base controller. The Rails generator creates an `InertiaController` for this:

```ruby
# app/controllers/inertia_controller.rb
class InertiaController < ApplicationController
  inertia_share user: -> { Current.user&.as_json(only: [:id, :name, :email]) }
end
```

Then inherit your Inertia controllers from it:

```ruby
class EventsController < InertiaController
  # ...
end
```

## Creating Responses

That's it, you're all ready to go server-side! Once you setup the [client-side](/guide/client-side-setup.md) framework, you can start creating Inertia [pages](/guide/pages.md) and rendering them via [responses](/guide/responses.md).

```ruby
class EventsController < ApplicationController
  def show
    event = Event.find(params[:id])

    render inertia: {
      event: event.as_json(
        only: [:id, :title, :start_date, :description]
      )
    }
  end
end
```

---

---
url: /guide/shared-data.md
---
# Shared Data

Sometimes you need to access specific pieces of data on numerous pages within your application. For example, you may need to display the current user in the site header. Passing this data manually in each response across your entire application is cumbersome. Thankfully, there is a better option: shared data.

## Sharing Data

The `inertia_share` method allows you to define data that will be available to all controller actions, automatically merging with page-specific props.

### Basic Usage

```ruby
class EventsController < ApplicationController
  # Static sharing: Data is evaluated immediately
  inertia_share app_name: Rails.configuration.app_name

  # Dynamic sharing: Data is evaluated at render time
  inertia_share do
    {
      user: current_user&.as_json(only: [:id, :name, :email]),
      notifications: current_user&.unread_notifications_count
    } if user_signed_in?
  end

  # Alternative syntax for single dynamic values
  inertia_share total_users: -> { User.count }
end
```

### Inheritance and Shared Data

Shared data defined in parent controllers is automatically inherited by child controllers. Child controllers can also override or add to the shared data:

```ruby
# Parent controller
  class ApplicationController < ActionController::Base
  inertia_share app_name: 'My App', version: '1.0'
end

# Child controller
class UsersController < ApplicationController
  # Inherits app_name and version, adds/overrides auth
  inertia_share auth: -> { { user: current_user&.as_json(only: [:id, :name, :email]) } }
end
```

### Conditional Sharing

You can control when data is shared using Rails-style controller filters. The `inertia_share` method supports these filter options:

* `only`: Share data for specific actions
* `except`: Share data for all actions except specified ones
* `if`: Share data when condition is true
* `unless`: Share data when condition is false

```ruby
class EventsController < ApplicationController
  # Share user data only when authenticated
  inertia_share if: :user_signed_in? do
    {
      user: {
        name: current_user.name,
        email: current_user.email,
        role: current_user.role
      }
    }
  end

  # Share data only for specific actions
  inertia_share only: [:index, :show] do
    {
      meta: {
        last_updated: Time.current,
        version: "1.0"
      }
    }
  end
end
```

### Sharing Data From Callbacks

@available\_since rails=3.19.0

Alternatively, you can call `inertia_share` on the controller instance, for example inside a `before_action` callback. This is useful when the shared data depends on work the callback already does, such as loading a record.

```ruby
class ProjectsController < ApplicationController
  before_action :set_team

  private

  def set_team
    @team = current_user.teams.find(params[:team_id])
    inertia_share team: @team.as_json(only: [:id, :name])
  end
end
```

The instance method accepts keyword arguments and a block. Use the `before_action` options, such as `only:` or `if:`, to control when the data is shared.

> \[!NOTE]
> Shared data should be used sparingly as all shared data is included with every response.

> \[!NOTE]
> Page props and shared data are merged together, so be sure to namespace your shared data appropriately to avoid collisions.

## Sharing Once Props

@available\_since rails=3.15.0 core=2.2.20

You may share data that is resolved only once and remembered by the client across subsequent navigations using [once props](/guide/once-props).

```ruby
class ApplicationController < ActionController::Base
  inertia_share countries: InertiaRails.once { Country.all }
end
```

For more information on once props, see the [once props](/guide/once-props) documentation.

## Accessing Shared Data

Once you have shared the data server-side, you will be able to access it within any of your pages or components. Here's an example of how to access shared data in a layout component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { computed } from 'vue'
import { usePage } from '@inertiajs/vue3'

const page = usePage()

const user = computed(() => page.props.auth.user)
</script>

<template>
  <main>
    <header>You are logged in as: {{ user.name }}</header>
    <article>
      <slot />
    </article>
  </main>
</template>
```

\== React

```jsx
import { usePage } from '@inertiajs/react'

export default function Layout({ children }) {
  const { auth } = usePage().props

  return (
    <main>
      <header>You are logged in as: {auth.user.name}</header>
      <article>{children}</article>
    </main>
  )
}
```

\== Svelte

```svelte
<script>
  import { page } from '@inertiajs/svelte'
</script>

<main>
  <header>
    You are logged in as: {page.props.auth.user.name}
  </header>
  <article>
    <slot />
  </article>
</main>
```

:::

## TypeScript

You may configure the shared props type globally using [TypeScript's declaration merging](/guide/typescript#shared-page-props).

## Flash Data

@available\_since rails=3.16.0 core=2.3.3

For one-time notifications like toast messages or success alerts, you may use [flash data](/guide/flash-data). Unlike shared data, flash data is not persisted in the browser's history state, so it won't reappear when navigating through history.

## Deep Merging Shared Data

By default, Inertia will shallow merge data defined in an action with the shared data. You might want a deep merge. Imagine using shared data to represent defaults you'll override sometimes.

```ruby
class ApplicationController
  inertia_share do
    { basketball_data: { points: 50, rebounds: 100 } }
  end
end
```

Let's say we want a particular action to change only part of that data structure. The renderer accepts a `deep_merge` option:

```ruby
class CrazyScorersController < ApplicationController
  def index
    render inertia: {
      basketball_data: { points: 100 }
    }, deep_merge: true
  end
end

# The renderer will send this to the frontend:
{
  basketball_data: {
    points: 100,
    rebounds: 100,
  }
}
```

Deep merging can be set as the project wide default via the `InertiaRails` configuration:

```ruby
# config/initializers/some_initializer.rb
InertiaRails.configure do |config|
  config.deep_merge_shared_data = true
end

```

If deep merging is enabled by default, it's possible to opt out within the action:

```ruby
class CrazyScorersController < ApplicationController
  inertia_share do
    {
      basketball_data: {
        points: 50,
        rebounds: 10,
      }
    }
  end

  def index
    render inertia: {
      basketball_data: { points: 100 }
    }, deep_merge: false
  end
end

# Even if deep merging is set by default, since the renderer has `deep_merge: false`, it will send a shallow merge to the frontend:
{
  basketball_data: {
    points: 100,
  }
}
```

---

---
url: /guide/testing.md
---
# Testing

There are many different ways to test an Inertia application. This page provides a quick overview of the tools available.

## End-to-end Tests

One popular approach to testing your JavaScript page components is to use an end-to-end testing tool like [Cypress](https://www.cypress.io/) or [Capybara](https://teamcapybara.github.io/capybara/). These are browser automation tools that allow you to run real simulations of your app in the browser. These tests are known to be slower; however, since they test your application at the same layer as your end users, they can provide a lot of confidence that your app is working correctly. And, since these tests are run in the browser, your JavaScript code is actually executed and tested as well.

## Client-Side Unit Tests

Another approach to testing your page components is using a client-side unit testing framework, such as [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/), or [Mocha](https://mochajs.org/). This approach allows you to test your JavaScript page components in isolation using Node.js.

## Endpoint Tests

@available\_since rails=3.17.0

Inertia Rails provides test helpers for both RSpec and Minitest.

:::tabs key:tests

\== RSpec

```ruby
# spec/rails_helper.rb
require 'inertia_rails/rspec'
```

\== Minitest

```ruby
# test/test_helper.rb
require 'inertia_rails/minitest'
```

:::

RSpec helpers are automatically available in all request specs. Minitest helpers are automatically included in `ActionDispatch::IntegrationTest`.

## Assertions

Both RSpec and Minitest provide matchers/assertions for testing Inertia responses. In RSpec, negation is done with `not_to`.

The `inertia` helper gives you direct access to `inertia.props`, `inertia.component`, `inertia.view_data`, `inertia.flash`, `inertia.deferred_props`, `inertia.scroll_props`, and `inertia.once_props`.

| Description                  | RSpec                     | Minitest                                                                  |
| ---------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| Inertia response             | `be_inertia_response`     | `assert_inertia_response` / `refute_inertia_response`                     |
| Component name               | `render_component`        | `assert_inertia_component` / `refute_inertia_component`                   |
| Props (partial match)        | `have_props`              | `assert_inertia_props` / `refute_inertia_props`                           |
| Props (exact match)          | `have_exact_props`        | `assert_inertia_props_equal` / `refute_inertia_props_equal`               |
| Prop key absent              | `have_no_prop`            | `assert_no_inertia_prop`                                                  |
| View data (partial match)    | `have_view_data`          | `assert_inertia_view_data` / `refute_inertia_view_data`                   |
| View data (exact match)      | `have_exact_view_data`    | `assert_inertia_view_data_equal` / `refute_inertia_view_data_equal`       |
| View data key absent         | `have_no_view_data`       | `assert_no_inertia_view_data`                                             |
| Flash (partial match)        | `have_flash`              | `assert_inertia_flash` / `refute_inertia_flash`                           |
| Flash (exact match)          | `have_exact_flash`        | `assert_inertia_flash_equal` / `refute_inertia_flash_equal`               |
| Flash key absent             | `have_no_flash`           | `assert_no_inertia_flash`                                                 |
| Deferred props               | `have_deferred_props`     | `assert_inertia_deferred_props` / `refute_inertia_deferred_props`         |
| Scroll props (partial match) | `have_scroll_props`       | `assert_inertia_scroll_props` / `refute_inertia_scroll_props`             |
| Scroll props (exact match)   | `have_exact_scroll_props` | `assert_inertia_scroll_props_equal` / `refute_inertia_scroll_props_equal` |
| Scroll prop key absent       | `have_no_scroll_prop`     | `assert_no_inertia_scroll_prop`                                           |
| Once props (partial match)   | `have_once_props`         | `assert_inertia_once_props` / `refute_inertia_once_props`                 |
| Once props (exact match)     | `have_exact_once_props`   | `assert_inertia_once_props_equal` / `refute_inertia_once_props_equal`     |
| Once prop key absent         | `have_no_once_prop`       | `assert_no_inertia_once_prop`                                             |

:::tabs key:tests

\== RSpec

```ruby
# spec/requests/events_spec.rb
RSpec.describe '/events' do
  describe '#index' do
    let!(:event) { Event.create!(title: 'Rails World', start_date: '2026-09-23', description: 'Annual Ruby on Rails conference') }

    it 'renders inertia component' do
      get events_path

      expect(inertia).to be_inertia_response
      expect(inertia).to render_component 'events/index'
      expect(inertia).to have_props(title: 'Rails World')
      expect(inertia).to have_exact_props(title: 'Rails World', start_date: '2026-09-23', description: 'Annual Ruby on Rails conference')

      # Props support both symbol and string keys
      expect(inertia.props[:title]).to eq 'Rails World'
      expect(inertia.props['title']).to eq 'Rails World'

      expect(inertia).to have_view_data(timezone: 'UTC')
      expect(inertia).to have_exact_view_data(timezone: 'UTC')
      expect(inertia.view_data[:timezone]).to eq 'UTC'

      expect(inertia).to have_no_prop(:secret)
    end
  end
end
```

\== Minitest

```ruby
# test/integration/events_test.rb
class EventsTest < ActionDispatch::IntegrationTest
  test 'renders inertia component' do
    event = Event.create!(title: 'Rails World', start_date: '2026-09-23', description: 'Annual Ruby on Rails conference')

    get events_path

    assert_inertia_response
    assert_inertia_component 'events/index'
    assert_inertia_props title: 'Rails World'
    assert_inertia_props_equal title: 'Rails World', start_date: '2026-09-23', description: 'Annual Ruby on Rails conference'

    # Props support both symbol and string keys
    assert_equal 'Rails World', inertia.props[:title]
    assert_equal 'Rails World', inertia.props['title']

    assert_inertia_view_data timezone: 'UTC'
    assert_inertia_view_data_equal timezone: 'UTC'
    assert_equal 'UTC', inertia.view_data[:timezone]

    assert_no_inertia_view_data :secret
    assert_no_inertia_prop :secret
  end
end
```

:::

## Common Testing Tasks

### Test Flash Messages

Inertia Rails automatically shares [flash data](/guide/flash-data) with your frontend. Flash messages usually come with a redirect, so follow it before asserting.

:::tabs key:tests

\== RSpec

```ruby
RSpec.describe '/events' do
  it 'shows flash message after create' do
    post events_path, params: { event: { title: 'New Event' } }
    follow_redirect!

    expect(inertia).to have_flash(notice: 'Event created!')
    expect(inertia).to have_exact_flash(notice: 'Event created!')
    expect(inertia.flash[:notice]).to eq 'Event created!'
    expect(inertia).to have_no_flash(:alert)
  end
end
```

\== Minitest

```ruby
class EventsTest < ActionDispatch::IntegrationTest
  test 'shows flash message after create' do
    post events_path, params: { event: { title: 'New Event' } }
    follow_redirect!

    assert_inertia_flash notice: 'Event created!'
    assert_inertia_flash_equal notice: 'Event created!'
    assert_equal 'Event created!', inertia.flash[:notice]
    assert_no_inertia_flash :alert
  end
end
```

:::

### Test Validation Errors

[Validation errors](/guide/validation) are shared as props automatically when you redirect with `inertia: { errors: ... }`. Follow the redirect and assert them on the `errors` key.

:::tabs key:tests

\== RSpec

```ruby
RSpec.describe '/events' do
  it 'returns validation errors' do
    post events_path, params: { event: { title: '' } }
    follow_redirect!

    expect(inertia).to render_component 'events/new'
    expect(inertia).to have_props(errors: { title: ["can't be blank"] })
  end
end
```

\== Minitest

```ruby
class EventsTest < ActionDispatch::IntegrationTest
  test 'returns validation errors' do
    post events_path, params: { event: { title: '' } }
    follow_redirect!

    assert_inertia_component 'events/new'
    assert_inertia_props errors: { title: ["can't be blank"] }
  end
end
```

:::

### Test Redirects

After a [redirect](/guide/redirects), use `follow_redirect!` and assert the resulting Inertia response.

:::tabs key:tests

\== RSpec

```ruby
RSpec.describe '/events' do
  it 'redirects after create' do
    post events_path, params: { event: { title: 'Conference' } }
    follow_redirect!

    expect(inertia).to render_component 'events/show'
    expect(inertia).to have_flash(notice: 'Event created!')
  end
end
```

\== Minitest

```ruby
class EventsTest < ActionDispatch::IntegrationTest
  test 'redirects after create' do
    post events_path, params: { event: { title: 'Conference' } }
    follow_redirect!

    assert_inertia_component 'events/show'
    assert_inertia_flash notice: 'Event created!'
  end
end
```

:::

### Test Deferred Props

[Deferred props](/guide/deferred-props) are excluded from the initial page load and fetched in a subsequent request.

:::tabs key:tests

\== RSpec

```ruby
RSpec.describe '/events' do
  it 'defers expensive data' do
    get events_path

    expect(inertia).to have_deferred_props
    expect(inertia).to have_deferred_props(:analytics)
    expect(inertia).to have_deferred_props(:analytics, :statistics)

    # Check a specific group
    expect(inertia).to have_deferred_props(:other_data, group: :slow)

    expect(inertia.deferred_props[:default]).to include('analytics')
    expect(inertia.props[:analytics]).to be_nil
  end
end
```

\== Minitest

```ruby
class EventsTest < ActionDispatch::IntegrationTest
  test 'defers expensive data' do
    get events_path

    assert_inertia_deferred_props
    assert_inertia_deferred_props :analytics
    assert_inertia_deferred_props :analytics, :statistics

    # Check a specific group
    assert_inertia_deferred_props :other_data, group: :slow

    assert_includes inertia.deferred_props[:default], 'analytics'
    assert_nil inertia.props[:analytics]
  end
end
```

:::

### Test Partial Reloads

Use `inertia_reload_only`, `inertia_reload_except`, and `inertia_load_deferred_props` to simulate [partial reloads](/guide/partial-reloads) and deferred prop loading.

:::tabs key:tests

\== RSpec

```ruby
RSpec.describe '/events' do
  it 'supports partial reloads' do
    get events_path

    inertia_reload_only(:analytics, :statistics)
    expect(inertia.props[:analytics]).to be_present

    inertia_reload_except(:expensive_data)

    # Load deferred props by group
    inertia_load_deferred_props(:default)

    # Load all deferred props
    inertia_load_deferred_props
  end
end
```

\== Minitest

```ruby
class EventsTest < ActionDispatch::IntegrationTest
  test 'supports partial reloads' do
    get events_path

    inertia_reload_only(:analytics, :statistics)
    assert_not_nil inertia.props[:analytics]

    inertia_reload_except(:expensive_data)

    # Load deferred props by group
    inertia_load_deferred_props(:default)

    # Load all deferred props
    inertia_load_deferred_props
  end
end
```

:::

## Configuration

### `evaluate_optional_props`

@available\_since rails=3.18.0

By default, [optional](/guide/partial-reloads#lazy-data-evaluation) and [deferred](/guide/deferred-props) props are excluded on first load — just like in production. This means `inertia.props[:my_optional]` returns `nil` unless you simulate a partial reload.

To have these props evaluated on first load in tests, enable `evaluate_optional_props`:

:::tabs key:tests

\== RSpec

```ruby
# spec/rails_helper.rb
require 'inertia_rails/rspec'

InertiaRails::Testing.evaluate_optional_props = true
```

\== Minitest

```ruby
# test/test_helper.rb
require 'inertia_rails/minitest'

InertiaRails::Testing.evaluate_optional_props = true
```

:::

Optional and deferred props are then included in `inertia.props` on first load:

:::tabs key:tests

\== RSpec

```ruby
get events_path

expect(inertia.props[:analytics]).to be_present
expect(inertia.props[:statistics]).to eq({ views: 100 })
```

\== Minitest

```ruby
get events_path

assert_not_nil inertia.props[:analytics]
assert_equal({ views: 100 }, inertia.props[:statistics])
```

:::

You can also toggle this setting per-test:

:::tabs key:tests

\== RSpec

```ruby
around do |example|
  InertiaRails::Testing.evaluate_optional_props = true
  example.run
ensure
  InertiaRails::Testing.evaluate_optional_props = false
end
```

\== Minitest

```ruby
def test_optional_props
  InertiaRails::Testing.evaluate_optional_props = true
  get events_path
  assert_not_nil inertia.props[:analytics]
ensure
  InertiaRails::Testing.evaluate_optional_props = false
end
```

:::

::: warning
When `evaluate_optional_props` is enabled, deferred props will appear in `inertia.props` but will still be listed in `inertia.deferred_props`. Partial reload behaviour is unaffected — this setting only changes first-load behaviour.
:::

## Disabling SSR During Tests

Your application may have [SSR enabled](/guide/server-side-rendering) for development and production, but you might not need it during testing. You may turn off the `ssr_enabled` option in the test environment to prevent the Rails adapter from dispatching SSR requests.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.ssr_enabled = !Rails.env.test?
end
```

Alternatively, you may set the `INERTIA_SSR_ENABLED` environment variable to `false`. It only applies when your initializer does not set `ssr_enabled`.

A controller that sets `ssr_enabled` with [`inertia_config`](/guide/configuration#local-configuration) overrides the global value, so give it the same condition.

```ruby
class DashboardController < ApplicationController
  inertia_config(ssr_enabled: !Rails.env.test?)
end
```

If you keep SSR on in system tests, you may want SSR failures to [raise an error](/guide/server-side-rendering#raising-on-error) instead of falling back to client-side rendering.

---

---
url: /guide/the-protocol.md
---
# The Protocol

This page contains a detailed specification of the Inertia protocol. Be sure to read the [how it works](/guide/how-it-works) page first for a high-level overview.

## HTML Responses

The very first request to an Inertia app is just a regular, full-page browser request, with no special Inertia headers or data. For these requests, the server returns a full HTML document.

This HTML response includes the site assets (CSS, JavaScript) as well as a root `<div>` in the page's body. The root `<div>` serves as a mounting point for the client-side app. A `<script type="application/json">` element contains the JSON encoded [page object](#the-page-object) for the initial page. Inertia uses this information to boot your client-side framework and display the initial page component.

Inertia Rails renders this `<script>` element when [`use_script_element_for_initial_page`](/guide/configuration#use-script-element-for-initial-page) is enabled. The installer enables it, and Inertia.js v3 reads the initial page only from the `<script>` element. With the option disabled, which is the gem default, the page object goes into a `data-page` attribute on the root `<div>` instead.

```http
REQUEST
GET: https://example.com/events/80
Accept: text/html, application/xhtml+xml

RESPONSE
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<html>
    <head>
        <title>My app</title>
        <link href="/css/app.css" rel="stylesheet">
        <script src="/js/app.js" defer></script>
    </head>
    <body>
        <script data-page="app" type="application/json">{"component":"Event","props":{"errors":{},"event":{"id":80,"title":"Birthday party","start_date":"2019-06-02","description":"Come out and celebrate Jonathan's 36th birthday party!"}},"url":"/events/80","version":"c32b8e4965f418ad16eaebba1d4e960f"}</script>
        <div id="app"></div>
    </body>
</html>
```

While the initial response is HTML, Inertia does not server-side render the JavaScript page components. For information on server-side rendering, see the [SSR documentation](/guide/server-side-rendering).

## Inertia Responses

Once the Inertia app has been booted, all subsequent requests to the site are made via XHR with a `X-Inertia` header set to `true`. This header indicates that the request is being made by Inertia and isn't a standard full-page visit.

When the server detects the `X-Inertia` header, instead of responding with a full HTML document, it returns a JSON response with an encoded [page object](#the-page-object).

```http
REQUEST
GET: https://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json
Vary: X-Inertia
X-Inertia: true

{
    "component": "Event",
    "props": {
        "errors": {},
        "event": {
            "id": 80,
            "title": "Birthday party",
            "start_date": "2019-06-02",
            "description": "Come out and celebrate Jonathan's 36th birthday party!"
        }
    },
    "url": "/events/80",
    "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
    "encryptHistory": true
}
```

## Request Lifecycle Diagram

The diagram below illustrates the request lifecycle within an Inertia application. The initial visit generates a standard request to the server, which returns an HTML application skeleton containing a root element with hydrated data. For subsequent user interactions and navigation, Inertia sends XHR requests that return JSON data. Inertia uses this response to dynamically hydrate and swap the page component without a full page reload.

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: First Visit
    Server-->>Client: Returns HTML Skeleton

    Note over Client: Inertia.js is loaded

    Client->>Server: Inertia Request (X-Inertia: true)
    Server-->>Client: Returns JSON Payload (Component Name, Props, etc.)

    Note over Client: Inertia.js swaps components
```

## How the Client Handles Responses

After each request, the client inspects the response before touching the page. Dispatch follows a small set of rules:

* **An Inertia response (`X-Inertia: true`)** is rendered directly: the client applies the page object and swaps the component.
* **A `409 Conflict` carrying `X-Inertia-Location`** triggers a full `window.location` visit to that URL, loading fresh assets. Background requests are exempt when the version changed, since reloading a visit the user never initiated would discard unsaved state.
* **A `409 Conflict` carrying `X-Inertia-Redirect`** triggers a fresh Inertia `GET` visit to that URL.
* **Any other response**, such as an HTML error page or plain JSON, is treated as an exception. The client fires a cancelable [HTTP exception event](/guide/events#http-exception) and, unless you cancel it, shows an error modal rather than silently navigating.

Standard `3xx` redirects never reach these rules. The browser follows them transparently, replaying the request headers against the new location, so `X-Inertia` reaches the redirect target and the client only ever inspects the final response in the chain. See [redirects](#redirects) for the statuses Inertia Rails returns to steer this.

A valid Inertia response with a status of `400` or greater fires that same cancelable HTTP exception event before rendering. Canceling it there suppresses the render, letting you handle the failure yourself.

## Request Headers

The following headers are automatically sent by Inertia when making requests. You don't need to set these manually, they're handled by the Inertia client-side adapter.

* `X-Inertia`: Set to `true` to indicate this is an Inertia request.
* `X-Requested-With`: Set to `XMLHttpRequest` on all Inertia requests.
* `Accept`: Set to `text/html, application/xhtml+xml` to indicate acceptable response types.
* `Content-Type`: Set to `application/json` for requests that do not include file uploads.
* `X-Inertia-Version`: The current asset version to check for asset mismatches.
* `X-XSRF-TOKEN`: The CSRF token read from the `XSRF-TOKEN` cookie, which Inertia Rails sets. See [CSRF protection](/guide/csrf-protection).
* `Purpose`: Set to `prefetch` when making [prefetch](/guide/prefetching) requests.
* `X-Inertia-Partial-Component`: The component name for [partial reloads](/guide/partial-reloads).
* `X-Inertia-Partial-Data`: Comma-separated list of props to include in partial reloads.
* `X-Inertia-Partial-Except`: Comma-separated list of props to exclude from partial reloads.
* `X-Inertia-Reset`: Comma-separated list of props to reset on navigation.
* `Cache-Control`: Set to `no-cache` for reload requests to prevent serving stale content.
* `X-Inertia-Error-Bag`: Specifies which error bag to use for [validation errors](/guide/validation). Note: This header is not used by the Rails adapter as error bags are a Laravel-specific feature.
* `X-Inertia-Infinite-Scroll-Merge-Intent`: Indicates whether the requested data should be appended or prepended when using [Infinite scroll](/guide/infinite-scroll).
* `X-Inertia-Except-Once-Props`: Comma-separated list of non-expired [once prop](/guide/once-props) keys already loaded on the client. The server will skip resolving these props unless explicitly requested via a partial reload or force refreshed server-side.

The following headers are used for [Precognition](/guide/forms#precognition) validation requests.

* `Precognition`: Set to `true` to indicate this is a Precognition validation request.
* `Precognition-Validate-Only`: Comma-separated list of field names to validate.

## Response Headers

Inertia Rails sets the following headers on Inertia page responses.

* `X-Inertia`: Set to `true` to indicate this is an Inertia response.
* `Vary`: Set to `X-Inertia` to help browsers correctly differentiate between HTML and JSON responses.

The following headers appear on `409 Conflict` responses instead. A `409` response carries no `X-Inertia` header, since it tells the client to navigate rather than render a page.

* `X-Inertia-Location`: The destination URL for a full `window.location` visit. Inertia Rails sets it for [external redirects](/guide/redirects#external-redirects): `inertia_location`, redirects marked with `inertia: { full_page: true }`, and cross-origin redirects. It also sets it on an [asset version](#asset-versioning) mismatch, where it holds the requested URL.
* `X-Inertia-Redirect`: The full redirect URL, including its fragment, for a redirect whose target contains a URL fragment. Triggers a fresh Inertia `GET` visit instead of a full page reload. Inertia Rails sends it only when [`convert_fragment_redirects`](/guide/configuration#convert-fragment-redirects) is enabled, as it is in apps set up with the installer.
* `X-Inertia-Version`: The current asset version, sent on an asset version mismatch `409` so the client can see it.

The following headers are used for [Precognition](/guide/forms#precognition) validation responses.

* `Precognition`: Set to `true` to indicate this is a Precognition validation response.
* `Precognition-Success`: Set to `true` when validation passes with no errors, combined with a `204 No Content` status code.
* `Vary`: Includes `Precognition` on responses from actions that call `precognition!` or `precognition`.

## The Page Object

Inertia shares data between the server and client via a page object. This object includes the necessary information required to render the page component, update the browser's history state, and track the site's asset version. The page object can include the following properties:

* `component`: The name of the JavaScript page component.
* `props`: The page props. Contains all of the page data along with an `errors` object. When there are no errors, `errors` is `{}` if [`always_include_errors_hash`](/guide/configuration#always-include-errors-hash) is enabled, as it is in apps set up with the installer. Otherwise, it's absent.
* `url`: The page URL.
* `version`: The current [asset version](/guide/asset-versioning).
* `encryptHistory`: Whether or not to [encrypt the current page's history state](/guide/history-encryption). Only included when `true`.
* `clearHistory`: Whether or not to clear any [encrypted history state](/guide/history-encryption#clearing-history). Only included when `true`.
* `preserveFragment`: Whether to [preserve the URL fragment](/guide/redirects#preserving-fragments) from the original request across a redirect.
* `preserveBigIntegers`: Whether `{"$bigint": "..."}` markers in `props` and `flash` should be turned into [`BigInt` values](/guide/big-integers). Only included when `true`.
* `mergeProps`: Array of prop keys that should be [merged](/guide/merging-props) (appended) during navigation.
* `prependProps`: Array of prop keys that should be [prepended](/guide/merging-props) during navigation.
* `deepMergeProps`: Array of prop keys that should be [deep merged](/guide/merging-props#deep-merge) during navigation.
* `matchPropsOn`: Array of prop keys to use for [matching when merging props](/guide/merging-props#matching-items).
* `scrollProps`: Configuration for [infinite scroll](/guide/infinite-scroll) prop merging behavior.
* `deferredProps`: Configuration for client-side [lazy loading of props](/guide/deferred-props).
* `rescuedProps`: Array of [deferred prop](/guide/deferred-props#error-handling) keys that failed to resolve and were rescued server-side. Used by the client to render the `rescue` slot on the `<Deferred>` component.
* `sharedProps`: Array of top-level prop keys registered via [`inertia_share`](/guide/shared-data). Used by the client to carry shared props over during [instant visits](/guide/instant-visits).
* `onceProps`: Configuration for [once props](/guide/once-props) that should only be resolved once and reused on subsequent pages. Each entry maps a key to an object containing the `prop` name and an `expiresAt` timestamp (in milliseconds), which is only included when the prop sets `expires_in`.
* `flash`: [Flash data](/guide/flash-data) for the current request. Only included when flash data exists. The client exposes it through the [`flash` event](/guide/flash-data#global-flash-event) and strips it from persisted history state.

On standard full page visits, the page object is JSON encoded into the `<script type="application/json">` element, or into the `data-page` attribute when `use_script_element_for_initial_page` is disabled. On Inertia visits (as indicated by the presence of the `X-Inertia` header), the page object is returned as the JSON payload.

Only `component`, `props`, `url`, and `version` are present on every page object, so a minimal one looks like this:

```json
{
  "component": "User/Edit",
  "props": {
    "errors": {},
    "user": {
      "name": "Jonathan"
    }
  },
  "url": "/user/123",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5"
}
```

The remaining fields are conditional, and Inertia Rails includes them only when the corresponding behavior applies. Absent fields default on the client to an empty array, an empty object, or `false`.

## Prop Evaluation Model

Every prop your server returns falls into one or more categories. The category determines whether the prop is resolved for a given request and what metadata, if any, the page object carries to describe it. These rules are purely a server-side resolution concern. The client applies whatever metadata it receives.

Inertia Rails builds these categories with its prop helpers: `InertiaRails.always`, `InertiaRails.optional`, `InertiaRails.defer`, `InertiaRails.merge` and `InertiaRails.deep_merge`, `InertiaRails.once`, and `InertiaRails.scroll`. Any other value, including a lambda, is a regular prop.

Resolution differs between the two request modes. A full visit resolves the complete set of eligible props. A partial reload resolves only the props the client asked for, keyed on the page component.

**Full visit**

| Prop category                | Resolved?                                | Metadata emitted                                               |
| :--------------------------- | :--------------------------------------- | :------------------------------------------------------------- |
| Regular                      | Yes                                      | none                                                           |
| Always                       | Yes (immune to `only`/`except`)          | none                                                           |
| Optional                     | No (not resolved, not announced)         | none                                                           |
| Deferred                     | No (announced only)                      | `deferredProps`                                                |
| Merge / deep merge / prepend | Yes                                      | `mergeProps`, `deepMergeProps`, `prependProps`, `matchPropsOn` |
| Once                         | Yes, unless already remembered by client | `onceProps`                                                    |
| Scroll                       | Yes                                      | `scrollProps`, `mergeProps`                                    |

**Partial reload**

| Prop category                | Resolved?                                                                    | Metadata emitted                                               |
| :--------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------- |
| Regular                      | Only when requested via `only`/`except`                                      | none                                                           |
| Always                       | Yes (immune to `only`/`except`)                                              | none                                                           |
| Optional                     | Only when selected via `only`/`except`                                       | none                                                           |
| Deferred                     | Only when selected via `only`/`except`                                       | `rescuedProps` (on rescue)                                     |
| Merge / deep merge / prepend | When resolved                                                                | `mergeProps`, `deepMergeProps`, `prependProps`, `matchPropsOn` |
| Once                         | When selected via `only`/`except`, unless remembered and not named in `only` | `onceProps`                                                    |
| Scroll                       | When resolved                                                                | `scrollProps`, `mergeProps`                                    |

A few metadata fields are mode-specific:

* `deferredProps` is populated on full visits only. It's absent on partial reloads, since deferred props resolve in the follow-up request.
* `rescuedProps` is populated on partial reloads only, listing deferred props that failed to resolve.
* Merge, scroll, and once metadata is emitted per response, alongside whichever props carry those behaviors.

### Always Props

Always props are resolved on every response in both modes. They ignore the partial reload filters entirely, so an always prop is sent even when a request lists it in `except`. They carry no page object metadata, since they're purely a server-side resolution rule. Inertia Rails treats the `errors` prop as an always prop, so partial reloads include it whenever it's present.

### Composing Categories

A prop may belong to several categories at once, such as `InertiaRails.defer(merge: true)` or `InertiaRails.scroll(defer: true)`. The metadata fields are independent, so the page object carries every label that applies, subject to the mode, the partial reload filters, and the [reset rules](#resetting-props). For example, a deferred merge prop is listed in both `deferredProps` and `mergeProps` on the full visit.

## Partial Reloads

When making Inertia requests, the partial reload option allows you to request a subset of the props (data) from the server on subsequent visits to the *same* page component. This can be a helpful performance optimization if it's acceptable that some page data becomes stale. See the [partial reloads](/guide/partial-reloads) documentation for details.

When a partial reload request is made, Inertia includes the `X-Inertia-Partial-Component` header and may include `X-Inertia-Partial-Data` and/or `X-Inertia-Partial-Except` headers with the request.

The `X-Inertia-Partial-Data` header is a comma separated list of the desired props (data) keys that should be returned.

The `X-Inertia-Partial-Except` header is a comma separated list of the props (data) keys that should not be returned. When only the `X-Inertia-Partial-Except` header is included, all props (data) except those listed will be sent. Both headers may be sent together. In that case, the `X-Inertia-Partial-Data` list narrows the response first and the `X-Inertia-Partial-Except` list is then removed from it, so a prop named in both is excluded.

The `X-Inertia-Partial-Component` header includes the name of the component that is being partially reloaded. This is necessary, since partial reloads only work for requests made to the same page component. If the final destination is different for some reason (eg. the user was logged out and is now on the login page), then no partial reloading will occur.

```http
REQUEST
GET: https://example.com/events
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5
X-Inertia-Partial-Data: events
X-Inertia-Partial-Component: Events

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
    "component": "Events",
    "props": {
        "events": [...], // the requested prop
        "errors": {}     // always included
    },
    "url": "/events/80",
    "version": "6b16b94d7c51cbe5b1fa42aac98241d5"
}
```

### Resetting Props

The `X-Inertia-Reset` header lists prop paths the client wants to reset before new data is applied. A reset prop is re-resolved and returned unlabeled. It's present in `props` but absent from every merge array and from `matchPropsOn`, so the client replaces the value instead of merging into it. The client sends reset paths in both the `X-Inertia-Reset` header and the `only` list. For scroll props, Inertia Rails also sets `scrollProps[path].reset` to `true`, which the [infinite scroll](/guide/infinite-scroll) component uses to re-sync its pagination state to the returned page. See [resetting props](/guide/merging-props#resetting-props) for the client-side API.

## Deferred and Optional Props

Deferred props let the server announce data that will load in a follow-up request. On a full visit, Inertia Rails skips each `InertiaRails.defer` prop and lists its key under `deferredProps`, grouped by the prop's `group` option. Props without a group go to `default`. The client issues one partial reload per group to fetch them, and the group names themselves are arbitrary. See the [deferred props](/guide/deferred-props) documentation.

```json
{
  "component": "Posts/Index",
  "props": {
    "errors": {},
    "user": {
      "name": "Jonathan"
    }
  },
  "url": "/posts",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "deferredProps": {
    "default": ["comments", "analytics"],
    "sidebar": ["relatedPosts"]
  }
}
```

Optional props behave similarly but are never announced. Inertia Rails skips `InertiaRails.optional` props on full visits and resolves them only when a partial reload selects them via `only` or `except`.

### Rescued Deferred Props

A prop defined with `InertiaRails.defer(rescue: true)` that raises doesn't fail the response, which is still a `200` carrying every other prop. Inertia Rails reports the exception to the Rails [error reporter](https://guides.rubyonrails.org/error_reporting.html) as handled, or logs it on Rails 6. It omits the prop from `props` entirely, rather than sending it as `null`, and adds its key to the top-level `rescuedProps` array. The client uses this list to render the `rescue` slot on the `<Deferred>` component. See [error handling](/guide/deferred-props#error-handling).

```json
{
  "component": "Users/Index",
  "props": {
    "errors": {}
  },
  "url": "/users",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "rescuedProps": ["permissions"]
}
```

## Merging Props

Merge props instruct the client to combine incoming prop data with data already on the page instead of replacing it. Arrays are appended or prepended, and objects are shallow or deep merged. The page object labels each merging prop under `mergeProps` (append), `prependProps` (prepend), or `deepMergeProps` (deep merge). In Inertia Rails, `InertiaRails.merge` appends by default, `InertiaRails.merge(prepend: true)` prepends, and `InertiaRails.deep_merge` deep merges. Merging applies on partial reloads only, so a full visit always replaces the prop even when it carries a merge label. See the [merging props](/guide/merging-props) documentation.

```json
{
  "component": "Feed/Index",
  "props": {
    "errors": {},
    "user": {
      "name": "Jonathan"
    },
    "posts": [
      {
        "id": 1,
        "title": "First Post"
      }
    ],
    "notifications": [
      {
        "id": 2,
        "message": "New comment"
      }
    ],
    "conversations": {
      "data": [
        {
          "id": 1,
          "title": "Support Chat",
          "participants": ["John", "Jane"]
        }
      ]
    }
  },
  "url": "/feed",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "mergeProps": ["posts"],
  "prependProps": ["notifications"],
  "deepMergeProps": ["conversations"],
  "matchPropsOn": ["posts.id", "notifications.id", "conversations.data.id"]
}
```

### Matching Items

The `matchPropsOn` array tells the client which field identifies each item, so existing entries can be updated in place rather than duplicated. Each entry has the form `"<propPath>.<keyField>"` and is split on the last dot: everything before the final segment is the prop path, and the final segment is the key field. `conversations.data.id` keys the array at `conversations.data` on its `id` field. Inertia Rails builds each entry by joining the prop path and the `match_on` option, so `InertiaRails.deep_merge(match_on: 'data.id')` on `conversations` emits `conversations.data.id`. See [matching items](/guide/merging-props#matching-items).

## Once Props

Once props are resolved a single time and remembered by the client, then reused on subsequent pages that include the same prop. The page object carries an `onceProps` configuration. Each entry maps a key to the prop name, plus an expiration timestamp in milliseconds when the prop sets `expires_in`. See the [once props](/guide/once-props) documentation.

```json
{
  "component": "Billing/Plans",
  "props": {
    "errors": {},
    "plans": [
      {
        "id": 1,
        "name": "Basic"
      },
      {
        "id": 2,
        "name": "Pro"
      }
    ]
  },
  "url": "/billing/plans",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "onceProps": {
    "plans": {
      "prop": "plans"
    }
  }
}
```

On subsequent Inertia requests, the client sends the loaded, non-expired once keys in the `X-Inertia-Except-Once-Props` header. Inertia Rails skips resolving those props and excludes them from the response, and the client reuses the previously loaded values.

```http
REQUEST
GET: https://example.com/billing/upgrade
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5
X-Inertia-Except-Once-Props: plans

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
    "component": "Billing/Upgrade",
    "props": {
        "errors": {},
        "currentPlan": {
            "id": 1,
            "name": "Basic"
        }
    },
    "url": "/billing/upgrade",
    "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
    "onceProps": {
        "plans": {
            "prop": "plans"
        }
    }
}
```

Note that `plans` is included in `onceProps` but not in `props` since it was already loaded on the client. The `onceProps` key identifies the once prop across pages, while `prop` specifies the actual prop name. These may differ when using [custom keys](/guide/once-props#custom-keys).

### Force-Fresh and Partial Reloads

Pass `fresh: true` to send a fresh value for a once prop even when its key appears in `X-Inertia-Except-Once-Props`, for example when the underlying data has changed. The returned value and its new `expiresAt` replace the client's copy. See [forcing a refresh](/guide/once-props#forcing-a-refresh).

On a partial reload the except-once header is ignored, so a requested once prop is always resolved.

## Infinite Scroll

Infinite scroll builds on merge props. The array inside the prop is labeled for merging (`posts.data` below, set with the `wrapper` option of `InertiaRails.scroll`), and the page object carries a `scrollProps` entry describing the paginator's cursor. See the [infinite scroll](/guide/infinite-scroll) documentation.

```json
{
  "component": "Posts/Index",
  "props": {
    "errors": {},
    "posts": {
      "data": [
        {
          "id": 1,
          "title": "First Post"
        },
        {
          "id": 2,
          "title": "Second Post"
        }
      ]
    }
  },
  "url": "/posts?page=1",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "mergeProps": ["posts.data"],
  "scrollProps": {
    "posts": {
      "pageName": "page",
      "previousPage": null,
      "nextPage": 2,
      "currentPage": 1,
      "reset": false
    }
  }
}
```

Every scroll response emits the merge label and a fresh cursor. A reset request drops the merge label and sets `scrollProps[path].reset` to `true`, which tells the client to re-sync its pagination state to the returned page. A deferred scroll prop emits no `scrollProps` on the full visit, since it resolves in the follow-up request.

## Asset Versioning

One common challenge with single-page apps is refreshing site assets when they've been changed. Inertia makes this easy by optionally tracking the current version of the site's assets. In the event that an asset changes, Inertia will automatically make a full-page visit instead of an XHR visit.

The Inertia [page object](#the-page-object) includes a `version` identifier. This version identifier is set server-side and can be a number, string, file hash, or any other value that represents the current "version" of your site's assets, as long as the value changes when the site's assets have been updated.

Whenever an Inertia request is made, Inertia will include the current asset version in the `X-Inertia-Version` header. When the server receives the request, it compares the asset version provided in the `X-Inertia-Version` header with the current asset version. This is typically handled in the middleware layer of your server-side framework.

If the asset versions are the same, the request simply continues as expected. If they differ, Inertia Rails still runs the controller action, and its middleware then replaces the response with a `409 Conflict`. The `409` includes the URL in an `X-Inertia-Location` header and the current asset version in an `X-Inertia-Version` header. The URL header is necessary, since server-side redirects may have occurred. This tells Inertia what the final intended destination URL is.

> \[!TIP]
> Note, `409 Conflict` responses are only sent for `GET` requests, and not for `POST/PUT/PATCH/DELETE` requests. That said, they will be sent in the event that a `GET` redirect occurs after one of these requests.

When the Inertia client receives a `409 Conflict` response, it checks for the presence of the `X-Inertia-Location` header. If this header exists, Inertia performs a full-page visit to the URL specified in the header. This ensures that the user always has the latest assets loaded.

If flash data exists when a `409 Conflict` response occurs, Inertia Rails keeps it for the next request.

```http
REQUEST
GET: https://example.com/events/80
Accept: text/html, application/xhtml+xml
X-Requested-With: XMLHttpRequest
X-Inertia: true
X-Inertia-Version: 6b16b94d7c51cbe5b1fa42aac98241d5

RESPONSE
409: Conflict
X-Inertia-Location: https://example.com/events/80
X-Inertia-Version: 2f8a1c9e4b7d0a3f6c5e8b1d4a7f0c2e
```

You can read more about this on the [asset versioning](/guide/asset-versioning) page.

## Redirects

Inertia relies on standard HTTP redirects for navigation after a server-side action. Inertia Rails converts a `301` or `302` redirect that responds to an Inertia `PUT`, `PATCH`, or `DELETE` request into a `303 See Other`. The browser then issues a `GET` to the redirect target instead of repeating the original request method.

External redirects point outside your Inertia app, where an Inertia visit can't follow them. Inertia Rails returns a `409 Conflict` with an `X-Inertia-Location` header instead, and the client performs a full `window.location` visit. Cross-origin `301`, `302`, and `303` redirects get this conversion automatically, unless [`convert_external_redirects`](/guide/configuration#convert-external-redirects) is disabled. For non-Inertia endpoints on your own origin, use `inertia_location` or mark the redirect with `inertia: { full_page: true }`.

A redirect whose target contains a URL fragment can be returned as a `409 Conflict` with an `X-Inertia-Redirect` header holding the full URL. The client then makes a fresh Inertia `GET` visit to that URL. Inertia Rails does this only when [`convert_fragment_redirects`](/guide/configuration#convert-fragment-redirects) is enabled, and only for same-origin `301`, `302`, and `303` redirects that don't answer a prefetch request.

This is distinct from the `preserveFragment` page object field, which carries the original request's fragment across an ordinary redirect. Inertia Rails sets that field when you pass `inertia: { preserve_fragment: true }` to `redirect_to`. See the [redirects](/guide/redirects) documentation.

## Validation Errors

Validation errors are shared through the `errors` prop. Inertia Rails treats `errors` as an always prop, so partial reloads never filter it out. When there are no errors, `errors` is `{}` if [`always_include_errors_hash`](/guide/configuration#always-include-errors-hash) is enabled, and absent otherwise.

You share errors by passing them to `redirect_to` with `inertia: { errors: ... }`. Inertia Rails keeps them in the session, much like flash data, and shares them on the next render. They survive redirects and asset version `409` responses, and are cleared after any other response.

Each key may map to either a single message or an array of messages, and the client renders whichever shape it receives. Inertia Rails doesn't reshape the errors you pass. With an `ActiveModel::Errors` object, such as `user.errors`, each field maps to an array of all its messages. To type them as arrays on the client, see [error values](/guide/typescript#error-values).

```json
{
  "errors": {
    "name": ["can't be blank", "is too short (minimum is 3 characters)"]
  }
}
```

Requests may scope errors to a named error bag with the `X-Inertia-Error-Bag` header. Inertia Rails ignores this header. See [error bags](/guide/validation#error-bags).

## HTTP Status Codes

Inertia uses specific HTTP status codes to handle different scenarios.

| Status Code       | Description                                                                                                                                                                |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **200 OK**        | Standard successful response for both HTML and Inertia JSON responses.                                                                                                     |
| **302 Found**     | Standard redirect response.                                                                                                                                                |
| **303 See Other** | The redirect status after an Inertia `PUT`, `PATCH`, or `DELETE` request, which tells the browser to follow it with a `GET`. See [redirects](#redirects).                  |
| **409 Conflict**  | A control response rather than a page, used for an [asset version mismatch](#asset-versioning), an external redirect, or a fragment redirect. See [redirects](#redirects). |

The following status codes are used for [Precognition](/guide/forms#precognition) validation requests.

| Status Code                  | Description                                                                                    |
| :--------------------------- | :--------------------------------------------------------------------------------------------- |
| **204 No Content**           | Successful Precognition validation request with no validation errors.                          |
| **422 Unprocessable Entity** | Precognition validation request with validation errors. The response body contains the errors. |

## Server-Side Rendering

Inertia does not server-side render the page components by default. Enabling [SSR](/guide/server-side-rendering) introduces a second wire contract, this time between Inertia Rails and Inertia's Node SSR server. Inertia Rails POSTs the page object to the SSR server, which returns the pre-rendered markup for the HTML document.

```http
REQUEST
POST: http://localhost:13714/render
Content-Type: application/json

{"component":"Event","props":{"errors":{},"event":{"id":80,"title":"Birthday party"}},"url":"/events/80","version":"c32b8e4965f418ad16eaebba1d4e960f"}

RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json
Server: Inertia.js SSR

{"head":["<title>Birthday party<\/title>"],"body":"<script data-page=\"app\" type=\"application\/json\">{\"component\":\"Event\",...}<\/script><div data-server-rendered=\"true\" id=\"app\"><h1>Birthday party<\/h1><\/div>"}
```

Inertia Rails sends this request to [`ssr_url`](/guide/configuration#ssr-url-experimental), which defaults to `http://localhost:13714`, and appends `/render` unless the URL already ends with `/render` or `/__inertia_ssr`. In development, when the Vite dev server is running and `ssr_url` isn't set, it posts to the dev server's `/__inertia_ssr` endpoint instead. It waits up to [`ssr_timeout`](/guide/configuration#ssr-timeout) seconds for the response.

The response fills the two slots of the root template. The `head` array holds the elements that belong in the document's `<head>`, such as the title and meta tags. Inertia Rails joins them and returns them from the [`inertia_ssr_head`](/guide/responses#inertia-ssr-head) helper in your layout. The `body` string takes the place of the page object script tag and root `<div>` that a non-SSR document would render, since the SSR server already includes both in its markup. Inertia Rails renders it as the view inside your layout. It carries `data-server-rendered="true"` so the client hydrates the existing DOM instead of mounting a fresh app. The SSR server escapes the embedded page object itself, so Inertia Rails prints the `body` markup as is.

The SSR server exposes two additional endpoints. A `GET` request to `/health` returns `{"status":"OK"}`, and a `POST` to `/shutdown` stops the process. The Inertia Rails [Puma plugin](/guide/server-side-rendering#puma-plugin) uses both: it polls `/health` while the SSR server boots and calls `/shutdown` to stop it.

A failed render returns a `500` response whose JSON body classifies the error rather than just reporting it.

```json
{
  "error": "window is not defined",
  "type": "browser-api",
  "component": "events/show",
  "url": "/events/80",
  "browserApi": "The global window object",
  "hint": "The global window object doesn't exist in Node.js. Wrap browser-specific code in a lifecycle hook...",
  "stack": "ReferenceError: window is not defined\n    at ...",
  "sourceLocation": "app/frontend/pages/events/show.vue:14:3",
  "timestamp": "2026-03-14T09:21:44.512Z"
}
```

The `error` message, `hint`, and `timestamp` are always present, while `component`, `url`, `stack`, and `sourceLocation` appear whenever the SSR server can determine them. The `type` narrows the cause to `browser-api` for a browser global touched during render, which also sets `browserApi` to the offending API, `component-resolution` for a page component that could not be resolved, or `render` for anything else thrown by your components.

Inertia Rails treats a failed render as non-fatal. It logs the failure to `Rails.logger` and falls back to the standard client-side rendered document, so a broken SSR build never takes the site down. It wraps the payload in an `InertiaRails::SSRError`, which exposes `type`, `hint`, `browser_api`, `stack`, and `source_location`. When the SSR server can't be reached or doesn't answer in time, the error gets a `connection` type of its own.

If you defined an [`on_ssr_error`](/guide/server-side-rendering#customizing-error-handling) callback, Inertia Rails passes the error to it. Otherwise, it reports the error through `Rails.error`. With [`ssr_raise_on_error`](/guide/server-side-rendering#raising-on-error) enabled, it raises the error instead of falling back, and skips the `Rails.error` report. See [error handling](/guide/server-side-rendering#error-handling).

---

---
url: /guide/title-and-meta.md
---
# Title & Meta

Since Inertia powered JavaScript apps are rendered within the document `<body>`, they are unable to render markup to the document `<head>`, as it's outside of their scope. To help with this, Inertia ships with a `<Head>` component which can be used to set the page `<title>`, `<meta>` tags, and other `<head>` elements.

The `<Head>` component will only replace `<head>` elements that are not in your root layout.

> \[!NOTE]
> Since v3.10.0, Inertia Rails supports managing meta tags via Rails. This allows your meta tags to work with link preview services without setting up server-side rendering. Since this isn't a part of the Inertia.js core, it's documented in the [server driven meta tags cookbook](/cookbook/server-managed-meta-tags).

The `<Head>` component is not available in the Svelte adapter, as Svelte already ships with its own `<svelte:head>` component.

## Head Component

To add `<head>` elements to your page, use the `<Head>` component. Within this component, you can include the elements that you wish to add to the document `<head>`.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head>
    <title>Your page title</title>
    <meta name="description" content="Your page description" />
  </Head>
</template>
```

\== React

```jsx
import { Head } from '@inertiajs/react'

export default () => (
  <Head>
    <title>Your page title</title>
    <meta name="description" content="Your page description" />
  </Head>
)
```

\== Svelte

```svelte
<svelte:head>
  <title>Your page title</title>
  <meta name="description" content="Your page description" />
</svelte:head>
```

:::

## Title Shorthand

If you only need to add a `<title>` to the document `<head>`, you may simply pass the title as a prop to the `<Head>` component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head title="Your page title" />
</template>
```

\== React

```jsx
import { Head } from '@inertiajs/react'

export default () => <Head title="Your page title" />
```

\== Svelte

```js
// Not supported
```

:::

## Title Callback

You can globally modify the page `<title>` using the `title` callback in the `createInertiaApp` setup method. Typically, this method is invoked in your application's main JavaScript file. A common use case for the title callback is automatically adding an app name before or after each page title.

```js
createInertiaApp({
  title: (title) => `${title} - My App`,
  // ...
})
```

@available\_since core=3.5.0

The callback also receives the current [page object](/guide/the-protocol#the-page-object) as its second argument, which you may use to build titles from the page's props.

```js
createInertiaApp({
  title: (title, page) => `${title} - ${page.props.app_name}`,
  // ...
})
```

After defining the `title` callback, the callback will automatically be invoked when you set a title using the `<Head>` component.

> \[!NOTE]
> When using [server driven meta tags](/cookbook/server-managed-meta-tags), configure the [title template](/cookbook/server-managed-meta-tags#title-template) on the server instead — the client applies the `title` callback on top of server-provided titles, so combining the two would apply the suffix twice.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head title="Home" />
</template>
```

\== React

```jsx
import { Head } from '@inertiajs/react'

export default () => <Head title="Home" />
```

\== Svelte

```js
// Not supported
```

:::

Which, in this example, will result in the following `<title>` tag.

```html
<title>Home - My App</title>
```

The `title` callback will also be invoked when you set the title using a `<title>` tag within your `<Head>` component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head>
    <title>Home</title>
  </Head>
</template>
```

\== React

```jsx
import { Head } from '@inertiajs/react'

export default () => (
  <Head>
    <title>Home</title>
  </Head>
)
```

\== Svelte

```js
// Not supported
```

:::

Without [SSR](/guide/server-side-rendering), the callback only runs in the browser. Link previews (like in Slack) don't run JavaScript, so they show the `<title>` from your Rails layout instead. To set that title, see [Default Title](/guide/responses#default-title).

## Multiple Head Instances

It's possible to have multiple instances of the `<Head>` component throughout your application. For example, your layout can set some default `<Head>` elements, and then your individual pages can override those defaults.

:::tabs key:frameworks

\== Vue

```vue
<!-- Layout.vue -->
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head>
    <title>My app</title>
    <meta
      head-key="description"
      name="description"
      content="This is the default description"
    />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </Head>
</template>

<!-- About.vue -->
<script setup>
import { Head } from '@inertiajs/vue3'
</script>

<template>
  <Head>
    <title>About - My app</title>
    <meta
      head-key="description"
      name="description"
      content="This is a page specific description"
    />
  </Head>
</template>
```

\== React

```jsx
// Layout.jsx
import { Head } from '@inertiajs/react'

export default () => (
  <Head>
    <title>My app</title>
    <meta
      head-key="description"
      name="description"
      content="This is the default description"
    />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </Head>
)

// About.jsx
import { Head } from '@inertiajs/react'

export default () => (
  <Head>
    <title>About - My app</title>
    <meta
      head-key="description"
      name="description"
      content="This is a page specific description"
    />
  </Head>
)
```

\== Svelte

```js
// Not supported
```

:::

Inertia will only ever render one `<title>` tag; however, all other tags will be stacked since it's valid to have multiple instances of them. To avoid duplicate tags in your `<head>`, you can use the `head-key` property, which will make sure the tag is only rendered once. This is illustrated in the example above for the `<meta name="description">` tag.

The code example above will render the following HTML.

```html
<head>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  <title>About - My app</title>
  <meta name="description" content="This is a page specific description" />
</head>
```

## Head Extension

When building a real application, it can sometimes be helpful to create a custom head component that extends Inertia's `<Head>` component. This gives you a place to set app-wide defaults, such as appending the app name to the page title.

:::tabs key:frameworks

\== Vue

```vue
<!-- AppHead.vue -->

<script setup>
import { Head } from '@inertiajs/vue3'

defineProps({ title: String })
</script>

<template>
  <Head :title="title ? `${title} - My App` : 'My App'">
    <slot />
  </Head>
</template>
```

\== React

```jsx
// AppHead.js

import { Head } from '@inertiajs/react'

export default ({ title, children }) => {
  return (
    <Head>
      <title>{title ? `${title} - My App` : 'My App'}</title>
      {children}
    </Head>
  )
}
```

\== Svelte

```js
// Not supported
```

:::

Once you have created the custom component, you can just start using it in your pages.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import AppHead from './AppHead'
</script>

<template>
  <AppHead title="About" />
</template>
```

\== React

```jsx
import AppHead from './AppHead'

export default () => <AppHead title="About" />
```

\== Svelte

```js
// Not supported
```

:::

## Server-Side Head Elements

You may wish to include default head elements like `<title>` or `<meta>` tags in your root layout. This creates two challenges: preventing duplicates when [SSR](/guide/server-side-rendering) is active, and ensuring the client-side `<Head>` component may replace them during navigation.

### SSR Fallback

@available\_since rails=3.23.0

`inertia_ssr_head` accepts fallback content in a block. The block renders only when the response isn't server-side rendered. When SSR is active, the `<Head>` component already provides these elements as part of the server-rendered response, so the fallback is skipped.

```erb
<%# app/views/layouts/application.html.erb %>
<head>
  <%= inertia_ssr_head do %>
    <title>My App</title>
    <meta data-inertia="description" name="description" content="My application description">
  <% end %>
  <%= vite_javascript_tag 'application' %>
</head>
```

If you only need a fallback `<title>`, use the [`default_title`](/guide/responses#default-title) option of `inertia_meta_tags` instead.

### The `data-inertia` Attribute

@available\_since core=2.2.13

The client-side `<Head>` component tracks the elements it manages by marking them with a `data-inertia` attribute. By default, it leaves any other tags in your root layout untouched. Since there may only be one `<title>` tag, the `<Head>` component will always replace it. Other elements like `<meta>` and `<link>` may have multiple instances, so the component needs a way to identify which ones it should manage.

You may add the `data-inertia` attribute to elements in your root layout to have the `<Head>` component adopt them. On the first client-side navigation, it will match these elements by key and replace or remove them as needed.

```erb
<%# app/views/layouts/application.html.erb %>
<head>
  <title>My App</title>
  <meta data-inertia="description" name="description" content="My application description">
  <%= vite_javascript_tag 'application' %>
</head>
```

The `data-inertia` value corresponds to the `head-key` property on your client-side `<Head>` elements.

Meta tags rendered by Inertia Rails use the older `inertia` attribute unless you enable the [`use_data_inertia_head_attribute`](/guide/configuration#use-data-inertia-head-attribute) or [`server_head`](/guide/configuration#server-head) option. Inertia.js v3 clients only recognize `data-inertia`, so the Rails generator enables this option.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.use_data_inertia_head_attribute = true
end
```

Inertia.js v2 clients use the `inertia` attribute by default. To switch them to `data-inertia`, enable the `future.useDataInertiaHeadAttribute` option in your [application defaults](/guide/client-side-setup#configuring-defaults):

```js
createInertiaApp({
  // resolve, setup, etc.
  defaults: {
    future: {
      useDataInertiaHeadAttribute: true,
    },
  },
})
```

---

---
url: /guide/typescript.md
---
# TypeScript

Inertia provides first-class TypeScript support. You may configure global types using declaration merging, and pass generics to hooks and router methods for type-safe props, forms, and state management.

## Using pnpm

Due to pnpm's strict dependency isolation, `@inertiajs/core` is not accessible at `node_modules/@inertiajs/core`. Instead, it's nested inside `.pnpm/`, which prevents TypeScript module augmentation from resolving the module.

You may fix this by configuring pnpm to [hoist the package](https://pnpm.io/settings#publichoistpattern). Add the following to your `.npmrc` file and run `pnpm install`.

```ini
public-hoist-pattern[]=@inertiajs/core
```

Alternatively, you may add `@inertiajs/core` as a direct dependency in your project.

```bash
pnpm add @inertiajs/core
```

## Global Configuration

You may configure Inertia's types globally by augmenting the `InertiaConfig` interface in the `@inertiajs/core` module. This is typically done in a `global.d.ts` file in your project's root or `types` directory.

```ts
// global.d.ts
import '@inertiajs/core'

declare module '@inertiajs/core' {
  export interface InertiaConfig {
    sharedPageProps: {
      auth: { user: { id: number; name: string } | null }
      appName: string
    }
    flashDataType: {
      toast?: { type: 'success' | 'error'; message: string }
    }
    errorValueType: string[]
    layoutProps: {
      title: string
      showSidebar: boolean
    }
    namedLayoutProps: {
      app: { title: string; theme: 'light' | 'dark' }
      content: { padding: string; maxWidth: string }
    }
  }
}
```

> \[!NOTE]
> The `import` statement (or `export {}`) is required to make this file a module. Without it, `declare module` replaces the module definition instead of augmenting it. Your `tsconfig.json` also needs to include `.d.ts` files, so make sure a pattern like `"app/frontend/**/*.d.ts"` is present in the `include` array.

### Shared Page Props

The `sharedPageProps` option defines the type of data that is [shared](/guide/shared-data) with every page in your application. With this configuration, `page.props.auth` and `page.props.appName` will be properly typed everywhere.

```ts
sharedPageProps: {
  auth: { user: { id: number; name: string } | null }
  appName: string
}
```

### Flash Data

The `flashDataType` option defines the type of [flash data](/guide/flash-data) in your application.

```ts
flashDataType: {
  toast?: { type: 'success' | 'error'; message: string }
}
```

### Error Values

By default, validation error values are typed as `string`. You may configure TypeScript to expect arrays instead for Rails' default (with `model.errors`) — multiple errors per field.

```ts
errorValueType: string[]
```

### Layout Props

The `layoutProps` option types the data accepted by `setLayoutProps()`. The `namedLayoutProps` option types the data accepted by `setLayoutProps('name', props)`, keyed by layout name.

```ts
layoutProps: {
  title: string
  showSidebar: boolean
}
namedLayoutProps: {
  app: {
    title: string
    theme: 'light' | 'dark'
  }
  content: {
    padding: string
    maxWidth: string
  }
}
```

With this configuration, `setLayoutProps({ title: 'Dashboard' })` is type-checked, and `setLayoutProps('app', { theme: 'dark' })` validates both the layout name and its props.

You may also pass a generic type parameter directly to `setLayoutProps` for ad-hoc typing without configuring the global `InertiaConfig` interface.

```ts
setLayoutProps<{ custom: string }>({ custom: 'value' })
setLayoutProps<{ collapsed: boolean }>('sidebar', { collapsed: true })
```

## Page Components

You may type the `import.meta.glob` result for better type safety when resolving page components.

:::tabs key:frameworks

\== Vue

```ts
import { createInertiaApp } from '@inertiajs/vue3'
import type { DefineComponent } from 'vue'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<DefineComponent>('../pages/**/*.vue')
    return pages[`../pages/${name}.vue`]()
  },
  // ...
})
```

\== React

```tsx
import { createInertiaApp, type ResolvedComponent } from '@inertiajs/react'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<ResolvedComponent>('../pages/**/*.tsx')
    return pages[`../pages/${name}.tsx`]()
  },
  // ...
})
```

\== Svelte

```ts
import { createInertiaApp, type ResolvedComponent } from '@inertiajs/svelte'

createInertiaApp({
  resolve: (name) => {
    const pages = import.meta.glob<ResolvedComponent>('../pages/**/*.svelte')
    return pages[`../pages/${name}.svelte`]()
  },
  // ...
})
```

:::

## Page Props

You may type page-specific props by passing a generic to `usePage()`. These are merged with your global `sharedPageProps`, giving you autocomplete and type checking for both shared and page-specific data.

:::tabs key:frameworks

\== Vue

```vue
<script setup lang="ts">
import { usePage } from '@inertiajs/vue3'

const page = usePage<{
  posts: { id: number; title: string }[]
}>()
</script>
```

\== React

```tsx
import { usePage } from '@inertiajs/react'

export default function Posts() {
  const page = usePage<{
    posts: { id: number; title: string }[]
  }>()

  return (
    <ul>
      {page.props.posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
```

\== Svelte

```svelte
<script lang="ts">
  import { usePage } from '@inertiajs/svelte'

  const page = usePage<{
    posts: { id: number; title: string }[]
  }>()
</script>
```

:::

## Form Helper

The [form helper](/guide/forms#form-helper) accepts a generic type parameter for type-safe form data and error handling. This provides autocomplete for form fields and errors, and prevents typos in field names.

:::tabs key:frameworks

\== Vue

```vue
<script setup lang="ts">
import { useForm } from '@inertiajs/vue3'

const form = useForm<{
  name: string
  email: string
  company: { name: string }
}>({
  name: '',
  email: '',
  company: { name: '' },
})
</script>
```

\== React

```tsx
import { useForm } from '@inertiajs/react'

export default function CreateUser() {
  const form = useForm<{
    name: string
    email: string
    company: { name: string }
  }>({
    name: '',
    email: '',
    company: { name: '' },
  })

  return null
}
```

\== Svelte

```svelte
<script lang="ts">
  import { useForm } from '@inertiajs/svelte'

  const form = useForm<{
    name: string
    email: string
    company: { name: string }
  }>({
    name: '',
    email: '',
    company: { name: '' },
  })
</script>
```

:::

### Nested Data and Arrays

Form types fully support nested objects and arrays. You may access and update nested fields using dot notation, and error keys are automatically typed to match.

```ts
import { useForm } from '@inertiajs/react'

const form = useForm<{
  user: { name: string; email: string }
  tags: { id: number; label: string }[]
}>({
  user: { name: '', email: '' },
  tags: [],
})
```

## Form Component

@available\_since core=3.0.0

The `<Form>` component accepts a generic type parameter for type-safe slot props. In React, you may pass the generic directly. In Vue and Svelte, you may use the `createForm` helper to create a typed form component.

:::tabs key:frameworks

\== Vue

```vue
<script setup lang="ts">
import { createForm } from '@inertiajs/vue3'

interface UserForm {
  name: string
  email: string
}

const TypedForm = createForm<UserForm>()
</script>

<template>
  <TypedForm action="/users" method="post" #default="{ errors }">
    <input type="text" name="name" />
    <div v-if="errors.name">{{ errors.name }}</div>
    <button type="submit">Create User</button>
  </TypedForm>
</template>
```

\== React

```tsx
import { Form } from '@inertiajs/react'

interface UserForm {
  name: string
  email: string
}

export default function CreateUser() {
  return (
    <Form<UserForm> action="/users" method="post">
      {({ errors }) => (
        <>
          <input type="text" name="name" />
          {errors.name && <div>{errors.name}</div>}
          <button type="submit">Create User</button>
        </>
      )}
    </Form>
  )
}
```

\== Svelte

```svelte
<script lang="ts">
  import { createForm } from '@inertiajs/svelte'

  interface UserForm {
    name: string
    email: string
  }

  const TypedForm = createForm<UserForm>()
</script>

<TypedForm action="/users" method="post">
  {#snippet children({ errors })}
    <input type="text" name="name" />
    {#if errors.name}<div>{errors.name}</div>{/if}
    <button type="submit">Create User</button>
  {/snippet}
</TypedForm>
```

:::

The generic provides autocomplete and type checking for the `errors` object, `setError`, `clearErrors`, and other slot props that reference form fields.

### useFormContext

@available\_since core=3.0.0

The `useFormContext()` function also accepts a generic type parameter, providing type-safe access to the form context from child components.

:::tabs key:frameworks

\== React

```tsx
import { useFormContext } from '@inertiajs/react'

const form = useFormContext<UserForm>()
```

\== Vue

```vue
<script setup lang="ts">
import { useFormContext } from '@inertiajs/vue3'

const form = useFormContext<UserForm>()
</script>
```

\== Svelte

```svelte
<script lang="ts">
  import { useFormContext } from '@inertiajs/svelte'

  const form = useFormContext<UserForm>()
</script>
```

:::

## HTTP Helper

The [`useHttp`](/guide/http-requests) hook accepts two generic type parameters: the form data type and an optional default response type.

```ts
import { useHttp } from '@inertiajs/react'

interface UserForm {
  name: string
  email: string
}

interface UserResponse {
  id: number
  name: string
}

const http = useHttp<UserForm, UserResponse>({ name: '', email: '' })
```

## Layout Callbacks

The `LayoutCallback` type provides type safety for [layout callbacks](/guide/layouts#callback-props). The callback receives the page's props (typed via your global `sharedPageProps` configuration) and should return a valid layout definition.

:::tabs key:frameworks

\== Vue

```vue
<script lang="ts">
import Layout from './Layout.vue'
import type { LayoutCallback } from '@inertiajs/vue3'

const callback: LayoutCallback = (props) => {
  return [Layout, { title: props.auth.user?.name }]
}

export default {
  layout: callback,
}
</script>
```

\== React

```tsx
import type { LayoutCallback } from '@inertiajs/react'
import Layout from './Layout'

const Profile = () => <h1>Profile</h1>

const callback: LayoutCallback = (props) => {
  return [Layout, { title: props.auth.user?.name }]
}

Profile.layout = callback

export default Profile
```

\== Svelte

```svelte
<script module lang="ts">
  import Layout from './Layout.svelte'
  import type { LayoutCallback } from '@inertiajs/svelte'

  export const layout: LayoutCallback = (props) => {
    return [Layout, { title: props.auth.user?.name }]
  }
</script>
```

:::

## Remembering State

The `useRemember` hook accepts a generic type parameter for type-safe local state persistence, providing autocomplete and ensuring values match the expected types.

:::tabs key:frameworks

\== Vue

```vue
<script setup lang="ts">
import { useRemember } from '@inertiajs/vue3'

const filters = useRemember<{
  search: string
  status: 'active' | 'inactive' | 'all'
}>({
  search: '',
  status: 'all',
})
</script>
```

\== React

```tsx
import { useRemember } from '@inertiajs/react'

export default function Users() {
  const [filters, setFilters] = useRemember<{
    search: string
    status: 'active' | 'inactive' | 'all'
  }>({
    search: '',
    status: 'all',
  })

  return null
}
```

\== Svelte

```svelte
<script lang="ts">
  import { useRemember } from '@inertiajs/svelte'

  const filters = useRemember<{
    search: string
    status: 'active' | 'inactive' | 'all'
  }>({
    search: '',
    status: 'all',
  })
</script>
```

:::

## Restoring State

The `router.restore()` method accepts a generic for typing state restored from [history](/guide/remembering-state#manually-saving-state).

```ts
import { router } from '@inertiajs/react'

interface TableState {
  sortBy: string
  sortDesc: boolean
  page: number
}

const restored = router.restore<TableState>('table-state')

if (restored) {
  console.log(restored.sortBy)
}
```

## Router Requests

Router methods accept a generic for typing request data, providing type checking for the data being sent.

```ts
import { router } from '@inertiajs/react'

interface CreateUserData {
  name: string
  email: string
}

router.post<CreateUserData>('/users', {
  name: 'John',
  email: 'john@example.com',
})
```

## Scoped Flash Data

The `router.flash()` method accepts a generic for typing page or section-specific flash data, separate from the global `flashDataType` configuration.

```ts
import { router } from '@inertiajs/react'

router.flash<{ paymentError: string }>({ paymentError: 'Card declined' })
```

## Client-Side Visits

The `router.push()` and `router.replace()` methods accept a generic for typing [client-side visit](/guide/manual-visits#client-side-visits) props.

```ts
import { router } from '@inertiajs/react'

interface UserPageProps {
  user: { id: number; name: string }
}

router.push<UserPageProps>({
  component: 'users/show',
  url: '/users/1',
  props: { user: { id: 1, name: 'John' } },
})

router.replace<UserPageProps>({
  props: (current) => ({
    ...current,
    user: { ...current.user, name: 'Updated' },
  }),
})
```

---

---
url: /guide/upgrade-guide.md
---
# Upgrade Guide for v3.0

## What's New

Inertia.js v3.0 is a major release focused on simplicity and developer experience. Axios has been replaced with a
built-in XHR client for a smaller bundle, SSR now works out of the box during development without a separate Node.js
server, and the new `@inertiajs/vite` plugin handles page resolution and SSR configuration automatically. This release
also introduces standalone HTTP requests via the `useHttp` hook, optimistic updates with automatic rollback, layout
props for sharing data between pages and layouts, and improved exception handling.

* [Vite Plugin](/guide/client-side-setup#installation) — Automatic page resolution, SSR setup, and optional
  setup/resolve callbacks.
* [HTTP Requests](/guide/http-requests) — Make standalone HTTP requests with the useHttp hook, without triggering page
  visits.
* [Optimistic Updates](/guide/optimistic-updates) — Apply data changes instantly before the server responds, with
  automatic rollback on failure.
* [Layout Props](/guide/layouts#layout-props) — Share dynamic data between pages and persistent layouts with the
  useLayoutProps hook.
* [Simplified SSR](/guide/server-side-rendering) — SSR works automatically in Vite dev mode. No separate Node.js server
  needed.
* [Exception Handling](/guide/error-handling#production) — Render custom Inertia error pages directly from your
  exception handler, with shared data.

This release also includes several additional improvements:

* [Instant visits](/guide/instant-visits) that swap to the target component before the server responds
* [Form component generics](/guide/typescript#form-component) for type-safe errors and slot props
* [Disable SSR per controller](/guide/server-side-rendering#excluding-controllers-from-ssr) with
  `inertia_config(ssr_enabled: false)`
* [Improved SSR error messages](/guide/server-side-rendering#error-handling) with component names, URLs, and actionable
  hints
* [Page object in resolve callback](/guide/client-side-setup#manual-setup) for context-aware component resolution
* [Built-in HTTP interceptors](/guide/client-side-setup#interceptors) without Axios
* [Default layout](/guide/layouts#default-layouts) option in `createInertiaApp`
* [`preserveErrors`](/guide/partial-reloads#preserving-errors) option to preserve validation errors during partial
  reloads

## Upgrade Dependencies

To upgrade to Inertia.js v3.0, first use npm to install the client-side adapter of your choice:

:::tabs key:frameworks

\== Vue

```bash
npm install @inertiajs/vue3@^3.0
```

\== React

```bash
npm install @inertiajs/react@^3.0
```

\== Svelte

```bash
npm install @inertiajs/svelte@^3.0
```

:::

You may also install the new optional Vite plugin, which provides a simplified SSR setup and a `pages` shorthand for
component resolution:

```bash
npm install @inertiajs/vite@^3.0
```

Next, upgrade the `inertia_rails` gem:

```ruby
gem 'inertia_rails', '~> 3.19'
```

Make sure you are using configuration options that are compatible with Inertia.js v3.0.

```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
  config.use_script_element_for_initial_page = true
  config.use_data_inertia_head_attribute = true
  config.always_include_errors_hash = true
  # ...
end
```

## Breaking Changes

***

### Requirements

#### React 19+

The React adapter now requires React 19. React 18 and below are no longer supported.

#### Svelte 5+

The Svelte adapter now requires Svelte 5. Svelte 4 and below are no longer supported. All Svelte code should be updated
to use the Svelte 5 runes syntax (`$props()`, `$state()`, `$effect()`, etc).

### Axios Removed

Inertia no longer ships with or requires Axios. For most applications, this requires no changes. The built-in XHR client
supports [interceptors](/guide/client-side-setup#interceptors) as well, so Axios interceptors may be migrated directly.
You may also continue using Axios via the [Axios adapter](/guide/client-side-setup#using-axios), or provide a
fully [custom HTTP client](/guide/client-side-setup#custom-http-client).

### `qs` Dependency Removed

The `qs` package has been replaced with a built-in query string implementation and is no longer included as a dependency
of `@inertiajs/core`. Inertia's internal query string handling remains the same, but you should install `qs` directly if
your application imports it.

```bash
npm install qs
```

### `lodash-es` Dependency Removed

The `lodash-es` package has been replaced with `es-toolkit` and is no longer included as a dependency of `@inertiajs/core`. You should install `lodash-es` directly if your application imports it.

```bash
npm install lodash-es
```

### Event Renames

Two global events have been renamed for clarity:

| v2 Name     | v3 Name         | Document Event          |
| ----------- | --------------- | ----------------------- |
| `invalid`   | `httpException` | `inertia:httpException` |
| `exception` | `networkError`  | `inertia:networkError`  |

Global event listeners should be updated accordingly:

```js
// Before (v2)
router.on('invalid', (event) => { ... })
router.on('exception', (event) => { ... })

// After (v3)
router.on('httpException', (event) => { ... })
router.on('networkError', (event) => { ... })
```

You may also handle these events per-visit using the new `onHttpException` and `onNetworkError` callbacks:

```js
router.post('/users', data, {
  onHttpException: (response) => { ... },
  onNetworkError: (error) => { ... },
})
```

Returning `false` from the `onHttpException` callback or calling `event.preventDefault()` on the global `httpException` event will prevent Inertia from navigating to the [error page](/guide/error-handling). This lets you handle HTTP exceptions (4xx and 5xx responses) without leaving the current page.

```js
router.post('/users', data, {
  onHttpException: (response) => {
    // Handle the error without navigating
    return false
  },
})
```

### `router.cancel()` Replaced

The `router.cancel()` method has been replaced by `router.cancelAll()`. In v2, `cancel()` only cancelled synchronous requests. The new `cancelAll()` method cancels all synchronous, asynchronous, and prefetch requests by default. You may pass options to limit which request types are cancelled.

```js
// Before (v2) — only cancelled sync requests
router.cancel()

// After (v3) — cancels all request types
router.cancelAll()

// To match v2 behavior (sync only)...
router.cancelAll({ async: false, prefetch: false })
```

See the [visit cancellation](/guide/manual-visits#visit-cancellation) documentation for more details.

### Future Options Removed

The `future` configuration namespace has been removed. All four future options from v2 are now always enabled and no
longer configurable:

* `future.preserveEqualProps`
* `future.useDataInertiaHeadAttribute`
* `future.useDialogForErrorModal`
* `future.useScriptElementForInitialPage`

```js
// Before (v2)
createInertiaApp({
  defaults: {
    future: {
      preserveEqualProps: true,
      useDataInertiaHeadAttribute: true,
      useDialogForErrorModal: true,
      useScriptElementForInitialPage: true,
    },
  },
})

// After (v3) - just remove the `future` block
createInertiaApp({
  // ...
})
```

Initial page data is now always passed via a `<script type="application/json">` element. The legacy `data-page`
attribute approach is no longer supported.

### Head Element Attributes

The `inertia` attribute used on elements in your root ERB template's `<head>` section has been renamed to `data-inertia`. You should update any head elements that use this attribute:

```html
<!-- Before (v2) -->
<title inertia>My Website</title>

<!-- After (v3) -->
<title data-inertia>My Website</title>
```

### Progress Indicator Exports Removed

The named exports `hideProgress()` and `revealProgress()` have been removed. If needed, use the `progress` object
directly:

```js
import { progress } from '@inertiajs/vue3'

progress.hide()
progress.reveal()
```

### Deferred Component Behavior (React)

The React `<Deferred>` component no longer resets to show the fallback during partial reloads. Previously, the fallback
was shown each time a partial reload was triggered. Now the existing content remains visible while new data loads,
consistent with the Vue and Svelte behavior.

A new `reloading` slot prop is available across all adapters, allowing you to show a loading indicator during partial
reloads while keeping the existing content visible. See the [deferred props](/guide/deferred-props#reloading-indicator)
documentation for details.

### Form Processing Reset Timing

The `useForm` helper now only resets `processing` and `progress` state in the `onFinish` callback, rather than
immediately upon receiving a response. This ensures the processing state remains `true` until the visit is fully
complete.

### Initializer Configuration

Make sure to set `use_script_element_for_initial_page` and `use_data_inertia_head_attribute` to `true` when upgrading frontend dependencies to Inertia 3.x:

```ruby
InertiaRails.configure do |config|
  config.use_data_inertia_head_attribute = true
  config.use_script_element_for_initial_page = true
end
```

### React Arrow Function Layout Components

The new layout implementation in v3 no longer supports arrow function components assigned directly to `.layout`. Inertia cannot reliably distinguish them from render functions at runtime. Wrapping the component in an array resolves this:

```jsx
const Layout = ({ children }) => <main>{children}</main>

// ❌ does not work — arrow function component assigned directly
Dashboard.layout = Layout

// ✅ wrap in an array instead
Dashboard.layout = [Layout]
```

Function declaration components continue to work without any changes.

## Other Changes

***

### SSR in Development

When using the new `@inertiajs/vite` plugin, SSR works automatically during development by simply running `bin/dev`. You
no longer need to build your SSR bundle with `bin/vite build --ssr` or start a separate Node.js server with
`bin/vite ssr` during development. These commands are now only required
for [production deployments](/guide/server-side-rendering#running-the-ssr-server).

### Nested Prop Types

Prop types like `InertiaRails.optional`, `InertiaRails.defer()`, and `InertiaRails.merge()` now work inside closures and
nested arrays. Inertia resolves them at any depth and uses dot-notation paths in partial reload metadata.

```ruby
class DashboardController < ApplicationController
  def index
    render inertia: {
      auth: -> {
        {
          user: Current.user,
          notifications: InertiaRails.defer { Current.user.unread_notifications },
          invoices: InertiaRails.optional { Current.user.invoices }
        }
      }
    }
  end
end
```

On the client side, the `only` and `except` options, as well as the `Deferred` and `WhenVisible` components, all support
dot-notation for targeting nested props.

```js
router.reload({ only: ['auth.notifications'] })
```

Objects that respond to `to_inertia` also work at any nesting level. Inertia Rails renders the hash they return and resolves the prop types inside it.

```ruby
class AuthProps
  def to_inertia
    {
      user: Current.user,
      permissions: InertiaRails.optional { Current.user.permissions }
    }
  end
end

class DashboardController < ApplicationController
  def index
    render inertia: { auth: AuthProps.new }
  end
end
```

### `InertiaRails.lazy` Deprecated

`InertiaRails.lazy` has been deprecated since Inertia Rails 3.6 and logs a deprecation warning. It will be removed in Inertia Rails 4.0. Use `InertiaRails.optional` instead, which provides the same functionality:

```ruby
# Before
render inertia: {
  users: InertiaRails.lazy { User.all }
}

# After
render inertia: {
  users: InertiaRails.optional { User.all }
}
```

`InertiaRails.optional` only takes a block, so pass the value as one: `InertiaRails.lazy(-> { User.all })` becomes `InertiaRails.optional { User.all }`.

### ES2022 Build Target

Inertia packages now target ES2022, up from ES2020 in v2. You may use the [`@vitejs/plugin-legacy`](https://www.npmjs.com/package/@vitejs/plugin-legacy) Vite plugin if your application needs to support older browsers.

### ESM-Only Packages

All Inertia packages now ship as ES Modules only. CommonJS `require()` imports are no longer supported. You should
update any `require()` calls to use `import` statements instead.

### Page Object Changes

The `clearHistory` and `encryptHistory` properties in the [page object](/guide/the-protocol#the-page-object) are now
optional and only included in the response when `true`. Previously, every response included `"clearHistory": false` and
`"encryptHistory": false` even when history wasn't being cleared or encrypted.

## Upgrade guide for v2.0

### What's new

Inertia.js v2.0 is a huge step forward for Inertia! The core library has been completely rewritten to architecturally
support asynchronous requests, enabling a whole set of new features, including:

* [Polling](/guide/polling)
* [Prefetching](/guide/prefetching)
* [Deferred props](/guide/deferred-props)
* [Infinite scrolling](/guide/infinite-scroll)
* [Lazy loading data on scroll](/guide/load-when-visible)

Additionally, for security sensitive projects, Inertia now offers a [history encryption API](/guide/history-encryption),
allowing you to clear page data from history state when logging out of an application.

### Upgrade dependencies

To upgrade to Inertia.js v2.0, first use npm to install the client-side adapter of your choice:

:::tabs key:frameworks
\== Vue

```bash
npm install @inertiajs/vue3@^2.0
```

\== React

```bash
npm install @inertiajs/react@^2.0
```

\== Svelte

```bash
npm install @inertiajs/svelte@^2.0
```

:::

Next, use at least the 3.6 version of `inertia-rails`.

```ruby
gem 'inertia_rails', '~> 3.6'
```

### Breaking changes

While a significant release, Inertia.js v2.0 doesn't introduce many breaking changes. Here's a list of all the breaking
changes:

#### Dropped Vue 2 support

The Vue 2 adapter has been removed. Vue 2 reached End of Life on December 3, 2023, so this felt like it was time.

#### Svelte adapter

* Dropped support for Svelte 3 as it reached End of Life on June 20, 2023.
* The `remember` helper has been renamed to `useRemember` to be consistent with other helpers.
* Updated `setup` callback in `inertia.js`. You need to pass `props` when initializing the `App`
  component. [See the updated guide](/guide/client-side-setup#initialize-the-inertia-app)
* The `setup` callback is now required in
  `ssr.js`. [See the updated guide](/guide/server-side-rendering#manual-setup)

#### Partial reloads are now async

Previously partial reloads in Inertia were synchronous, just like all Inertia requests. In v2.0, partial reloads are now
asynchronous. Generally this is desirable, but if you were relying on these requests being synchronous, you may need to
adjust your code.

---

---
url: /guide/validation.md
---
# Validation

## How It Works

Handling server-side validation errors in Inertia works differently than a classic XHR-driven form that requires you to catch the validation errors from `422` responses and manually update the form's error state - because Inertia never receives `422` responses. Instead, Inertia operates much more like a standard full page form submission. Here's how:

First, you [submit your form using Inertia](/guide/forms). If there are server-side validation errors, you don't return those errors as a `422` JSON response. Instead, you redirect (server-side) the user back to the form page they were previously on, flashing the validation errors in the session.

```ruby
class UsersController < ApplicationController
  def create
    user = User.new(user_params)

    if user.save
      redirect_to users_url
    else
      redirect_to new_user_url, inertia: { errors: user.errors }
    end
  end

  private

  def user_params
    params.expect(user: [:name, :email])
  end
end
```

Next, any time these validation errors are present in the session, they automatically get shared with Inertia, making them available client-side as page props which you can display in your form. Since props are reactive, they are automatically shown when the form submission completes.

Finally, since Inertia apps never generate `422` responses, Inertia needs another way to determine if a response includes validation errors. To do this, Inertia checks the `page.props.errors` object for the existence of any errors. In the event that errors are present, the request's `onError()` callback will be called instead of the `onSuccess()` callback.

## Sharing Errors

In order for your server-side validation errors to be available client-side, your server-side framework must share them via the `errors` prop. Inertia's Rails adapter does this automatically.

## Displaying Errors

Since validation errors are made available client-side as page component props, you can conditionally display them based on their existence. Remember, when using Rails server adapter, the `errors` prop will automatically be available to your page.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { reactive } from 'vue'
import { router } from '@inertiajs/vue3'

defineProps({ errors: Object })

const form = reactive({
  first_name: null,
  last_name: null,
  email: null,
})

function submit() {
  router.post('/users', form)
}
</script>

<template>
  <form @submit.prevent="submit">
    <label for="first_name">First name:</label>
    <input id="first_name" v-model="form.first_name" />
    <div v-if="errors.first_name">{{ errors.first_name }}</div>
    <label for="last_name">Last name:</label>
    <input id="last_name" v-model="form.last_name" />
    <div v-if="errors.last_name">{{ errors.last_name }}</div>
    <label for="email">Email:</label>
    <input id="email" v-model="form.email" />
    <div v-if="errors.email">{{ errors.email }}</div>
    <button type="submit">Submit</button>
  </form>
</template>
```

\== React

```jsx
import { useState } from 'react'
import { router, usePage } from '@inertiajs/react'

export default function Edit() {
  const { errors } = usePage().props

  const [values, setValues] = useState({
    first_name: null,
    last_name: null,
    email: null,
  })

  function handleChange(e) {
    setValues((values) => ({
      ...values,
      [e.target.id]: e.target.value,
    }))
  }

  function handleSubmit(e) {
    e.preventDefault()
    router.post('/users', values)
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="first_name">First name:</label>
      <input
        id="first_name"
        value={values.first_name}
        onChange={handleChange}
      />
      {errors.first_name && <div>{errors.first_name}</div>}
      <label htmlFor="last_name">Last name:</label>
      <input id="last_name" value={values.last_name} onChange={handleChange} />
      {errors.last_name && <div>{errors.last_name}</div>}
      <label htmlFor="email">Email:</label>
      <input id="email" value={values.email} onChange={handleChange} />
      {errors.email && <div>{errors.email}</div>}
      <button type="submit">Submit</button>
    </form>
  )
}
```

\== Svelte

```svelte
<script>
  let { errors = {} } = $props()

  let values = {
    first_name: null,
    last_name: null,
    email: null,
  }

  function handleSubmit() {
    router.post('/users', values)
  }
</script>

<form
  onsubmit={(e) => {
    e.preventDefault()
    handleSubmit()
  }}
>
  <label for="first_name">First name:</label>
  <input id="first_name" bind:value={values.first_name} />
  {#if errors.first_name}<div>{errors.first_name}</div>{/if}

  <label for="last_name">Last name:</label>
  <input id="last_name" bind:value={values.last_name} />
  {#if errors.last_name}<div>{errors.last_name}</div>{/if}

  <label for="email">Email:</label>
  <input id="email" bind:value={values.email} />
  {#if errors.email}<div>{errors.email}</div>{/if}

  <button type="submit">Submit</button>
</form>
```

:::

When using the Vue adapters, you may also access the errors via the `page.props.errors` object.

## Repopulating Input

While handling errors in Inertia is similar to full page form submissions, Inertia offers even more benefits. In fact, you don't even need to manually repopulate old form input data.

When validation errors occur, the user is typically redirected back to the form page they were previously on. And, by default, Inertia automatically preserves the [component state](/guide/manual-visits#state-preservation) for `post`, `put`, `patch`, and `delete` requests. Therefore, all the old form input data remains exactly as it was when the user submitted the form.

So, the only work remaining is to display any validation errors using the `errors` prop.

## Error Bags

> \[!NOTE]
> Error bags are a Laravel-specific feature that relies on Laravel's `ViewErrorBag` system. In Rails, this feature is typically unnecessary because:
>
> * Forms submit to separate controller actions, so only one set of errors is returned per request
> * The [form helper](/guide/forms.md) automatically scopes validation errors to each form instance
>
> If you have multiple forms on a page, use the `useForm()` helper and each form will maintain its own isolated error state.

## Precognition

Inertia Rails supports [Precognition](/guide/precognition) for real-time, server-driven validation without executing the full controller action. See the [Precognition guide](/guide/precognition) for setup instructions.

---

---
url: /guide/view-transitions.md
---
# View Transitions

@available\_since core=2.2.13

Inertia supports the [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions), allowing you to animate page transitions.

> \[!NOTE]
> The View Transitions API is a [relatively new browser feature](https://caniuse.com/view-transitions). Inertia gracefully falls back to standard page transitions in browsers that don't support the API.

## Enabling Transitions

You may enable view transitions for a visit by setting the `viewTransition` option to `true`. By default, this will apply a cross-fade transition between pages.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit('/another-page', { viewTransition: true })
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit('/another-page', { viewTransition: true })
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit('/another-page', { viewTransition: true })
```

:::

## Transition Callbacks

You may also pass a callback to the `viewTransition` option, which will receive the standard [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) instance provided by the browser. This allows you to hook into the various promises provided by the API.

:::tabs key:frameworks

\== Vue

```js
import { router } from '@inertiajs/vue3'

router.visit('/another-page', {
  viewTransition: (transition) => {
    transition.ready.then(() => console.log('Transition ready'))
    transition.updateCallbackDone.then(() => console.log('DOM updated'))
    transition.finished.then(() => console.log('Transition finished'))
  },
})
```

\== React

```js
import { router } from '@inertiajs/react'

router.visit('/another-page', {
  viewTransition: (transition) => {
    transition.ready.then(() => console.log('Transition ready'))
    transition.updateCallbackDone.then(() => console.log('DOM updated'))
    transition.finished.then(() => console.log('Transition finished'))
  },
})
```

\== Svelte

```js
import { router } from '@inertiajs/svelte'

router.visit('/another-page', {
  viewTransition: (transition) => {
    transition.ready.then(() => console.log('Transition ready'))
    transition.updateCallbackDone.then(() => console.log('DOM updated'))
    transition.finished.then(() => console.log('Transition finished'))
  },
})
```

:::

## Links

The `viewTransition` option is also available on the `Link` component.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/another-page" view-transition>Navigate</Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link href="/another-page" viewTransition>
    Navigate
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { Link } from '@inertiajs/svelte'
</script>

<Link href="/another-page" viewTransition>Navigate</Link>
```

:::

You may also pass a callback to access the `ViewTransition` instance.

:::tabs key:frameworks

\== Vue

```vue
<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link
    href="/another-page"
    :view-transition="
      (transition) => transition.finished.then(() => console.log('Done'))
    "
  >
    Navigate
  </Link>
</template>
```

\== React

```jsx
import { Link } from '@inertiajs/react'

export default () => (
  <Link
    href="/another-page"
    viewTransition={(transition) =>
      transition.finished.then(() => console.log('Done'))
    }
  >
    Navigate
  </Link>
)
```

\== Svelte

```svelte
<script>
  import { Link } from '@inertiajs/svelte'
</script>

<Link
  href="/another-page"
  viewTransition={(transition) =>
    transition.finished.then(() => console.log('Done'))}
>
  Navigate
</Link>
```

:::

## Global Configuration

You may enable view transitions globally for all visits by configuring the `visitOptions` callback when [initializing your Inertia app](/guide/client-side-setup#configuring-defaults).

:::tabs key:frameworks

\== Vue

```js
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return { viewTransition: true }
    },
  },
})
```

\== React

```js
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return { viewTransition: true }
    },
  },
})
```

\== Svelte

```js
import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
  // ...
  defaults: {
    visitOptions: (href, options) => {
      return { viewTransition: true }
    },
  },
})
```

:::

## Customizing Transitions

You may customize the transition animations using CSS. The View Transitions API uses several pseudo-elements that you can target with CSS to create custom animations. The following examples are taken from the [Chrome documentation](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#customize_the_transition).

```css
@keyframes fade-in {
  from {
    opacity: 0;
  }
}

@keyframes fade-out {
  to {
    opacity: 0;
  }
}

@keyframes slide-from-right {
  from {
    transform: translateX(30px);
  }
}

@keyframes slide-to-left {
  to {
    transform: translateX(-30px);
  }
}

::view-transition-old(root) {
  animation:
    90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}

::view-transition-new(root) {
  animation:
    210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}
```

You may also animate individual elements between pages by assigning them a unique `view-transition-name`. For example, you may animate an avatar from a large size on a profile page to a small size on a dashboard.

:::tabs key:frameworks

\== Vue

```vue
<!-- Profile.vue -->
<template>
  <img src="/avatar.jpg" alt="User" class="avatar-large" />
</template>

<style>
.avatar-large {
  view-transition-name: user-avatar;
  width: auto;
  height: 200px;
}
</style>
```

```vue
<!-- Dashboard.vue -->
<template>
  <img src="/avatar.jpg" alt="User" class="avatar-small" />
</template>

<style>
.avatar-small {
  view-transition-name: user-avatar;
  width: auto;
  height: 40px;
}
</style>
```

\== React

```jsx
// Profile.jsx
export default function Profile() {
  return <img src="/avatar.jpg" alt="User" className="avatar-large" />
}
```

```jsx
// Dashboard.jsx
export default function Dashboard() {
  return <img src="/avatar.jpg" alt="User" className="avatar-small" />
}
```

```css
.avatar-large {
  view-transition-name: user-avatar;
  width: auto;
  height: 200px;
}

.avatar-small {
  view-transition-name: user-avatar;
  width: auto;
  height: 40px;
}
```

\== Svelte

```svelte
<!-- Profile.svelte -->
<img src="/avatar.jpg" alt="User" class="avatar-large" />

<style>
  .avatar-large {
    view-transition-name: user-avatar;
    width: auto;
    height: 200px;
  }
</style>
```

```svelte
<!-- Dashboard.svelte -->
<img src="/avatar.jpg" alt="User" class="avatar-small" />

<style>
  .avatar-small {
    view-transition-name: user-avatar;
    width: auto;
    height: 40px;
  }
</style>
```

:::

You may customize view transitions to your liking using any CSS animations you wish. For more information, please consult the [View Transitions API documentation](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#customize_the_transition).

---

---
url: /guide/who-is-it-for.md
---
# Who Is Inertia.js For?

Inertia was crafted for development teams and solo hackers who typically build server-side rendered applications using frameworks like Laravel, Ruby on Rails, Django, or Phoenix. You're used to creating controllers, retrieving data from the database (via an ORM), and rendering views.

But what happens when you want to replace your server-side rendered views with a modern, JavaScript-based single-page application frontend? The answer is always "you need to build an API". Because that's how modern SPAs are built.

This means building a REST or GraphQL API. It means figuring out authentication and authorization for that API. It means client-side state management. It means setting up a new Git repository. It means a more complicated deployment strategy. And this list goes on. It's a complete paradigm shift, and often a complete mess. We think there is a better way.

> **Inertia empowers you to build a modern, JavaScript-based single-page application without the tiresome complexity.**

Inertia works just like a classic server-side rendered application. You create controllers, you get data from the database (via your ORM), and you render views. But, Inertia views are JavaScript page components written in React, Vue, or Svelte.

This means you get all the power of a client-side application and modern SPA experience, but you don't need to build an API. We think it's a breath of fresh air that will supercharge your productivity.