` element. You may customize this to use any HTML element using the `as` prop.
:::tabs key:frameworks
\== Vue
```vue
```
:::
## 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
```
:::
In this example, the component monitors the `#table-body` element and automatically tags each `
` 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
```
\== React
```jsx
{users.map((user) => (
{user.name}
))}
```
\== Svelte
```svelte
{#each users as user (user.id)}
{user.name}
{/each}
```
:::
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
Name
{{ user.name }}
Footer
```
\== React
```jsx
import { useRef } from 'react'
export default ({ users }) => {
const tableHeader = useRef()
const tableFooter = useRef()
const tableBody = useRef()
return (
tableBody.current}
startElement={() => tableHeader.current}
endElement={() => tableFooter.current}
>
Name
{users.map((user) => (
{user.name}
))}
Footer
)
}
```
\== Svelte
```svelte
tableBody}
start-element={() => tableHeader}
end-element={() => tableFooter}
>
Name
{#each users as user (user.id)}
{user.name}
{/each}
Footer
```
:::
## 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
```
\== React
```jsx
{users.map((user) => (
{user.name}
))}
```
\== Svelte
```svelte
{#each users as user (user.id)}
{user.name}
{/each}
```
:::
### 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_param: :users)
pagy_orders, orders = pagy(:countless, Order.all, page_param: :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_name: 'users')
orders_meta, orders = paginate(Order.order(:created_at), page_name: '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
Load More
```
\== React
```jsx
import { InfiniteScroll } from '@inertiajs/react'
import { useRef } from 'react'
export default ({ users }) => {
const infiniteScrollRef = useRef(null)
const fetchNext = () => {
infiniteScrollRef.current?.fetchNext()
}
return (
<>
Load More
{users.data.map((user) => (
{user.name}
))}
)
}
```
\== Svelte
```svelte
Load More
{#each users as user (user.id)}
{user.name}
{/each}
```
:::
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: 'data') 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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Dashboard
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default function Layout({ children }) {
return (
{children}
)
}
```
\== Svelte
```svelte
{@render children()}
```
:::
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
Welcome
Hello {{ user.name }}, welcome to your first Inertia app!
```
\== React
```jsx
import Layout from './Layout'
export default function Welcome({ user }) {
return (
Welcome
Hello {user.name}, welcome to your first Inertia app!
)
}
```
\== Svelte
```svelte
Welcome
Hello {user.name}, welcome to your first Inertia app!
```
:::
## 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
Welcome
Hello {{ user.name }}, welcome to your first Inertia app!
```
\== React
```jsx
import Layout from './Layout'
const Welcome = ({ user }) => {
return (
<>
Welcome
Hello {user.name}, welcome to your first Inertia app!
)
}
Welcome.layout = Layout
export default Welcome
```
\== Svelte
```svelte
Welcome Hello {user.name}, welcome to your first Inertia app!
```
:::
Vue 3.3+ users may alternatively use [defineOptions](https://vuejs.org/api/sfc-script-setup.html#defineoptions) to define a layout within `
```
### 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
Welcome
Hello {{ user.name }}, welcome to your first Inertia app!
```
\== React
```jsx
import SiteLayout from './SiteLayout'
import NestedLayout from './NestedLayout'
const Welcome = ({ user }) => {
return (
<>
Welcome
Hello {user.name}, welcome to your first Inertia app!
)
}
Welcome.layout = [SiteLayout, NestedLayout]
export default Welcome
```
\== Svelte
```svelte
Welcome Hello {user.name}, welcome to your first Inertia app!
```
:::
## 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
```js
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 || 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
```
\== React
```jsx
export default function Layout({
title = 'My App',
showSidebar = true,
children,
}) {
return (
<>
{showSidebar && }
{children}
)
}
```
\== Svelte
```svelte
{#if showSidebar}
{/if}
{@render children()}
```
:::
### 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
Dashboard
```
\== React
```jsx
import Layout from './Layout'
const Dashboard = ({ user }) => {
return Dashboard
}
Dashboard.layout = [Layout, { title: 'Dashboard' }]
export default Dashboard
```
\== Svelte
```svelte
Dashboard
```
:::
### 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
Profile
```
\== React
```jsx
import Layout from './Layout'
const Profile = () => {
return Profile
}
Profile.layout = (props) => [
Layout,
{ title: 'Profile: ' + props.auth.user.name },
]
export default Profile
```
\== Svelte
```svelte
Profile
```
:::
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
Profile
```
\== React
```jsx
const Profile = () => {
return Profile
}
Profile.layout = (props) => ({
title: 'Profile: ' + props.auth.user.name,
showSidebar: false,
})
export default Profile
```
\== Svelte
```svelte
Profile
```
:::
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
Dashboard
```
\== React
```jsx
import { setLayoutProps } from '@inertiajs/react'
export default function Dashboard() {
setLayoutProps({
title: 'Dashboard',
showSidebar: false,
})
return Dashboard
}
```
\== Svelte
```svelte
Dashboard
```
:::
### 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
```
\== React
```jsx
import AppLayout from './AppLayout'
import ContentLayout from './ContentLayout'
Dashboard.layout = {
app: AppLayout,
content: ContentLayout,
}
```
\== Svelte
```svelte
```
:::
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 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 `
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => Home
` elements. However, you can change the tag using the `as` prop.
:::tabs key:frameworks
\== Vue
```vue
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Logout
```
\== Svelte
```svelte
` links is discouraged as it causes "Open Link in New Tab / Window" accessibility issues. The component automatically renders a `` 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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Logout
```
:::
## 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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Save
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Save
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Home
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
<>
Search
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Home
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Show active
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
```
\== React
```jsx
import { usePage } from '@inertiajs/react'
export default () => {
const { url, component } = usePage()
return (
<>
// URL exact match...
Users
Users
Loading...
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
Loading...
}>
)
```
\== Svelte
```svelte
{#snippet fallback()}
Loading...
{/snippet}
{#each permissions as permission}
{/each}
```
:::
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
Loading...
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
Loading...
}>
)
```
\== Svelte
```svelte
{#snippet fallback()}
Loading...
{/snippet}
```
:::
## 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
Loading...
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
Loading...
}
>
)
```
\== Svelte
```svelte
{#snippet fallback()}
Loading...
{/snippet}
{#each permissions as permission}
{/each}
```
:::
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
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
)
```
\== Svelte
```svelte
```
:::
## 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
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
)
```
\== Svelte
```svelte
```
:::
### 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
Refreshing...
Loading...
```
\== React
```jsx
import { WhenVisible } from '@inertiajs/react'
export default () => (
Loading...
}>
{({ fetching }) => (
<>
Refreshing...
}
)}
)
```
\== Svelte
```svelte
{#snippet children({ fetching })}
Refreshing...
{/if}
{/snippet}
{#snippet fallback()}
Loading...
{/snippet}
```
:::
## 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
```
\== React
```jsx
{/* ... */}
```
\== Svelte
```svelte
```
:::
## 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
```
\== 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 (
<>
{/* ... */}
)
}
```
\== Svelte
```svelte
```
:::
---
---
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' })
```
:::
> \[!WARNING]
> Uploading files via `put` or `patch` is not supported in Rails. Instead, make the request via `post`, including a `_method` attribute or a `X-HTTP-METHOD-OVERRIDE` header set to `put` or `patch`. For more info see [`Rack::MethodOverride`](https://github.com/rack/rack/blob/main/lib/rack/method_override.rb).
## 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',
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',
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',
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' })
router.replace({
props: (currentProps) => ({ ...currentProps, search: 'John' }),
})
```
\== React
```js
import { router } from '@inertiajs/react'
router.push({ url: '/users', component: 'Users' })
router.replace({
props: (currentProps) => ({ ...currentProps, search: 'John' }),
})
```
\== Svelte
```js
import { router } from '@inertiajs/svelte'
router.push({ url: '/users', component: 'Users' })
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.8.0 core=2.0.8
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.8.0 core=2.0.8
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(chat_data, match_on: 'messages.id')
}
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 deferred 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
```
## 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 `
```
\== Svelte
```svelte
```
:::
## Form Helper
The `useForm` helper also supports optimistic updates via the same `optimistic()` method.
:::tabs key:frameworks
\== Vue
```vue
Save
```
\== 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 (
)
}
```
\== Svelte
```svelte
Save
```
:::
## 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
Welcome
Hello {{ user.name }}, welcome to your first Inertia app!
```
\== React
```jsx
import Layout from '../Layout'
import { Head } from '@inertiajs/react'
export default function Welcome({ user }) {
return (
Welcome
Hello {user.name}, welcome to your first Inertia app!
)
}
```
\== Svelte
```svelte
Welcome
Welcome
Hello {user.name}, welcome to your first Inertia app!
```
:::
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.
## 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'],
})
```
:::
## 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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Show active
Start polling
Stop polling
```
\== React
```jsx
import { usePoll } from '@inertiajs/react'
export default () => {
const { start, stop } = usePoll(
2000,
{},
{
autoStart: false,
},
)
return (
Start polling
Stop polling
)
}
```
\== Svelte
```svelte
Start polling
Stop polling
```
:::
## Throttling
By default, the poll helper will throttle requests by 90% when the browser tab is in the background. If you'd like to disable this behavior, you can pass the `keepAlive` option to the poll helper.
:::tabs key:frameworks
\== Vue
```js
import { usePoll } from '@inertiajs/vue3'
usePoll(
2000,
{},
{
keepAlive: true,
},
)
```
\== React
```jsx
import { usePoll } from '@inertiajs/react'
usePoll(
2000,
{},
{
keepAlive: true,
},
)
```
\== Svelte
```js
import { usePoll } from '@inertiajs/svelte'
usePoll(
2000,
{},
{
keepAlive: true,
},
)
```
:::
---
---
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Users
```
:::
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
<>
Users
Users
Users
```
:::
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Users
```
:::
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Users
```
:::
You can also combine prefetch strategies by passing an array of values to the `prefetch` prop.
:::tabs key:frameworks
\== Vue
```vue
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Users
```
:::
## 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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
<>
Users
Dashboard
```
:::
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
```
\== React
```jsx
import { Form } from '@inertiajs/react'
export default () => (
)
```
\== Svelte
```svelte
```
:::
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Users
```
:::
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 sever 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,
},
// ...
})
```
You can 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
<%= yield %>
<% 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 `` section to inject SSR-generated meta tags and other head elements.
```erb
# app/views/layouts/inertia.html.erb
<%= inertia_ssr_head %>
<%= yield %>
```
### `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
<%= inertia_meta_tags %>
```
### 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 %>
Hello from my new default template
);
}
```
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'
# 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
```
## 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.
---
---
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
```
\== React
```jsx
import { Link } from '@inertiajs/react'
export default () => (
Home
```
## 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 `` section of your HTML.
```erb
...
<%= inertia_meta_tags %> // [!code ++]
My Inertia App // [!code --]
```
> \[!NOTE]
> Make sure to remove the `` tag in your Rails layout if you plan to manage it with Inertia Rails. Otherwise you will end up with duplicate `<title>` tags.
### Client Side
Copy the following code into your application. It should be rendered **once** in your application, such as in a [layout component
](/guide/pages#creating-layouts).
:::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' } }
])
# 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"
}
}
})
```
## 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.
## 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) but still want to use the other features of the Vite plugin.
```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/assets-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 `resources/js/ssr.js` file for this purpose.
:::tabs key:frameworks
\== Vue
```js
import createServer from '@inertiajs/vue3/server'
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 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 createServer from '@inertiajs/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.
## 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 within your Laravel project.
:::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 createServer from '@inertiajs/vue3/server'
createServer((page) =>
createInertiaApp({
page,
render: renderToString,
resolve: (name) => {
const pages = import.meta.glob('../pges/**/*.vue')
return pages[`../pages/${name}.vue`]()
},
setup({ App, props, plugin }) {
return createSSRApp({
render: () => h(App, props),
}).use(plugin)
},
}),
)
```
\== React
```jsx
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('../pges/**/*.jsx')
return pages[`../pages/${name}.jsx`]()
},
setup: ({ App, props }) => <App {...props} />,
}),
)
```
\== Svelte
```js
import createServer from '@inertiajs/svelte/server'
createServer((page) =>
createInertiaApp({
page,
resolve: (name) => {
const pages = import.meta.glob('../pges/**/*.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 cinfig to turn SSR on.
```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
config.ssr_enabled = ViteRuby.config.ssr_build_enabled
end
```
### 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 },
)
```
:::
## 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 is a no-op when `ssr_enabled` is `false` or the SSR bundle is not found, 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.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.
## 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 ++]
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 { 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 { 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 })
}
},
})
```
:::
## 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. Component resolution errors suggest checking file paths and casing.
The Rails adapter automatically logs SSR failures to `Rails.logger` at the `error` level. To customize error handling, 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.
### Raising on Error
For CI or E2E testing, you may prefer SSR failures to raise an exception instead of falling back silently. Set the `ssr_raise_on_error` option in your initializer.
```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
config.ssr_raise_on_error = true
end
```
## 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
Sometimes you may wish to disable server-side rendering for certain controllers or pages in your application. You may do so by setting the `ssr_enabled` option to `false` using `inertia_config`.
```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
```
## 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/server-side-setup).
## 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` 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:3100/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.
Inertia's adapter will use standard Rails layout inheritance, with `view/layouts/application.html.erb` as a default layout. If you would like to use a different default layout, you can change it using the `InertiaRails.configure`.
```ruby
# config/initializers/inertia_rails.rb
InertiaRails.configure do |config|
config.layout = 'my_inertia_layout'
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 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
```
> \[!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.17.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 [Pest](https://pestphp.com). 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`, and `inertia.deferred_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` |
:::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.
:::tabs key:tests
\== RSpec
```ruby
RSpec.describe '/events' do
it 'shows flash message after create' do
post events_path, params: { event: { title: 'New Event' } }
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' } }
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 using `redirect_to` with `inertia_errors`. 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: '' } }
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: '' } }
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#optional-props) 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.
:::
---
---
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.
```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
```
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
```
## 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.
* `X-Inertia-Version`: The current asset version to check for asset mismatches.
* `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
The following headers should be sent by your server-side adapter in Inertia responses. If you're using an official server-side adapter, these are handled automatically.
* `X-Inertia`: Set to `true` to indicate this is an Inertia response.
* `X-Inertia-Location`: Used for external redirects when a `409 Conflict` response is returned due to asset version mismatches. Triggers a full `window.location` visit.
* `X-Inertia-Redirect`: Used for redirects containing URL fragments when a `409 Conflict` response is returned. Contains the full redirect URL including the fragment. Triggers a standard Inertia visit instead of a full page reload.
* `Vary`: Set to `X-Inertia` to help browsers correctly differentiate between HTML and JSON responses.
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`: Set to `Precognition` on all responses when the Precognition middleware is applied.
## 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 (defaults to `{}` if there are no errors).
* `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.
* `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).
* `sharedProps`: Array of top-level prop keys registered via `Inertia::share()`. 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 optional `expiresAt` timestamp (in milliseconds).
On standard full page visits, the page object is JSON encoded into a `
Your page title
```
\== React
```jsx
import { Head } from '@inertiajs/react'
export default () => (
Your page title
Your page title
```
:::
## Title Shorthand
If you only need to add a `` 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`,
// ...
})
```
After defining the `title` callback, the callback will automatically be invoked when you set a title using the `<Head>` component.
:::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
```
The `title` callback will also be invoked when you set the title using a `` tag within your `<Head>` component.
:::tabs key:frameworks
\== Vue
```vue
<script setup>
import { Head } from '@inertiajs/vue3'
</script>
<template>
<Head>
<title>Home
```
\== React
```jsx
import { Head } from '@inertiajs/react'
export default () => (
Home
)
```
\== Svelte
```js
// Not supported
```
:::
## Multiple Head Instances
It's possible to have multiple instances of the `` component throughout your application. For example, your layout can set some default `` elements, and then your individual pages can override those defaults.
:::tabs key:frameworks
\== Vue
```vue
My app
About - My app
```
\== React
```jsx
// Layout.jsx
import { Head } from '@inertiajs/react'
export default () => (
My app
About - My app
` 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
```
\== React
```jsx
// AppHead.js
import { Head } from '@inertiajs/react'
export default ({ title, children }) => {
return (
{title ? `${title} - My App` : 'My App'}
{children}
)
}
```
\== 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
```
\== React
```jsx
import AppHead from './AppHead'
export default () => ('../pages/**/*.vue')
return pages[`../pages/${name}.vue`]()
},
// ...
})
```
\== React
```tsx
import { createInertiaApp, type ResolvedComponent } from '@inertiajs/react'
createInertiaApp({
resolve: (name) => {
const pages = import.meta.glob('../pages/**/*.tsx')
return pages[`../pages/${name}.tsx`]()
},
// ...
})
```
\== Svelte
```ts
import { createInertiaApp, type ResolvedComponent } from '@inertiajs/svelte'
createInertiaApp({
resolve: (name) => {
const pages = import.meta.glob('../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
```
\== React
```tsx
import { usePage } from '@inertiajs/react'
export default function Posts() {
const page = usePage<{
posts: { id: number; title: string }[]
}>()
return (
{page.props.posts.map((post) => (
{post.title}
))}
)
}
```
\== Svelte
```svelte
```
:::
## 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
```
\== 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
```
:::
### 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 `
)
}
```
\== Svelte
```svelte
{#snippet children({ errors })}
{errors.name}
{/if}
Create User
{/snippet}
```
:::
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()
```
\== Vue
```vue
```
\== Svelte
```svelte
```
:::
## 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({ name: '', email: '' })
```
### Per-Request Response Types
Each HTTP method accepts its own generic type parameter, allowing you to override the response type on a per-call basis. This is useful when different endpoints return different response shapes.
```ts
interface OrderResponse {
orderId: string
total: number
}
// Override the response type per request...
const user: UserResponse = await http.post('/api/users')
const order: OrderResponse = await http.get('/api/orders/123')
const submitted: UserResponse = await http.submit(
'post',
'/api/users',
)
// The onSuccess callback is also typed...
await http.post('/api/users', {
onSuccess: (response) => {
console.log(response.id, response.name)
},
})
```
## 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
```
\== 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
```
:::
## 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('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('/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({
component: 'Users/Show',
url: '/users/1',
props: { user: { id: 1, name: 'John' } },
})
router.replace({
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-route](/guide/server-side-rendering#disabling-ssr) via middleware or facade
* [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.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) => { ...
},
})
```
### `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 `
```
\== 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 (
)
}
```
\== Svelte
```svelte
```
:::
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.
---
---
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
```
\== React
```jsx
import { router } from '@inertiajs/react'
export default () => (
```
\== React
```jsx
import { router } from '@inertiajs/react'
export default () => (
```
```vue
```
\== React
```jsx
// Profile.jsx
export default function Profile() {
return