Inertia Rails

https://inertia-rails.dev
Admin
Inertia Rails is a framework for building single-page applications with React, Vue, or Svelte...
Tokens:185,277
Snippets:1,667
Trust Score:6.4
Update:23 hours ago
Show doc for...
Tokens:
Raw
### Install @inertiajs/vite v3.0

Source: https://inertia-rails.dev/guide/upgrade-guide

Install the optional Vite plugin for simplified SSR setup and a 'pages' shorthand for component resolution.

```bash
npm install @inertiajs/vite@^3.0
```

--------------------------------

### Manual setup with resolve and setup callbacks (Vue)

Source: https://inertia-rails.dev/guide/client-side-setup

Provide resolve and setup callbacks manually to load page components and initialize the client-side framework. Note that a manual setup callback prevents the Vite plugin from auto-generating SSR handling; you must create a separate SSR entry point and use client-side hydration.

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

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

--------------------------------

### Start development servers

Source: https://inertia-rails.dev/guide/server-side-setup

Starts both the Rails server and the Vite development server. Recommended to use Overmind.

```bash
bin/dev
```

--------------------------------

### Install qs package

Source: https://inertia-rails.dev/guide/upgrade-guide

Install qs directly if your application imports it, as it is no longer a dependency of @inertiajs/core.

```bash
npm install qs
```

--------------------------------

### Start progress bar on visit start

Source: https://inertia-rails.dev/guide/progress-indicators

Add a 'start' event listener to show the progress bar when a new Inertia visit begins.

```javascript
router.on('start', () => NProgress.start())
```

--------------------------------

### Custom SSR entry point (Vue)

Source: https://inertia-rails.dev/guide/server-side-rendering

Create a separate SSR entry point for Vue when completely different server setup logic is required. This example uses createServer from @inertiajs/vue3/server.

```js
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'

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

--------------------------------

### Build and start SSR server for production

Source: https://inertia-rails.dev/guide/server-side-rendering

Build both bundles and start the SSR server. The node command runs the built SSR entry point.

```bash
npm run build
node public/vite-ssr/inertia.js
```

--------------------------------

### Pass data as second argument to convenience methods

Source: https://inertia-rails.dev/guide/manual-visits

The `get()`, `post()`, `put()`, and `patch()` methods accept `data` as their second argument. This example uses `router.post` to send data.

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

router.post('/users', {
  name: 'John Doe',
  email: '[email protected]',
})
```

--------------------------------

### Install NProgress library

Source: https://inertia-rails.dev/guide/progress-indicators

Install the NProgress library using npm to use it for custom progress indicators.

```bash
npm install nprogress
```

--------------------------------

### Example output of inertia:controller

Source: https://inertia-rails.dev/guide/responses

Example output when running the controller generator for a pages controller with welcome and next_steps actions.

```bash
$ bin/rails generate inertia:controller pages welcome next_steps
      create  app/controllers/pages_controller.rb
       route  get 'pages/welcome'
              get 'pages/next_steps'
      invoke  test_unit
      create    test/controllers/pages_controller_test.rb
      invoke  helper
      create    app/helpers/pages_helper.rb
      invoke    test_unit
      invoke  inertia_templates
      create    app/frontend/pages/pages
      create    app/frontend/pages/pages/welcome.jsx
      create    app/frontend/pages/pages/next_steps.jsx
```

--------------------------------

### Install @inertiajs/vite plugin

Source: https://inertia-rails.dev/guide/server-side-rendering

Install the Vite plugin required for automatic SSR configuration.

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

--------------------------------

### Install @inertiajs/vue3 v3.0

Source: https://inertia-rails.dev/guide/upgrade-guide

Use npm to install the Vue client-side adapter for Inertia.js v3.0.

```bash
npm install @inertiajs/vue3@^3.0
```

--------------------------------

### Install Babel dynamic import plugin

Source: https://inertia-rails.dev/guide/code-splitting

Install `@babel/plugin-syntax-dynamic-import` to enable dynamic imports for Webpack code splitting.

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

--------------------------------

### Manual start and stop with autoStart: false

Source: https://inertia-rails.dev/guide/polling

Provides start and stop methods for manual control. The autoStart: false option prevents automatic polling on mount. Available since @inertiajs/core:3.7.0.

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

const { start, stop } = usePoll(
  2000,
  {},
  {
    autoStart: false,
  },
)
</script>

<template>
  <button @click="start">Start polling</button>
  <button @click="stop">Stop polling</button>
</template>
```

--------------------------------

### Install Vue and Vite plugin

Source: https://inertia-rails.dev/guide/client-side-setup

Install Vue and its Vite plugin using npm. Required before configuring Vite.

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

--------------------------------

### Start SSR server manually with bin/vite ssr

Source: https://inertia-rails.dev/guide/server-side-rendering

Starts the SSR server manually when not using Puma or when managing the process yourself. With the server running, server-side rendering is enabled in the browser.

```bash
bin/vite ssr
```

--------------------------------

### Example output of inertia:scaffold

Source: https://inertia-rails.dev/guide/responses

Example output when running the scaffold generator for a Post model with title and body fields.

```bash
$ bin/rails generate inertia:scaffold Post title:string body:text
      invoke  active_record
      create    db/migrate/20240611123952_create_posts.rb
      create    app/models/post.rb
      invoke    test_unit
      create      test/models/post_test.rb
      create      test/fixtures/posts.yml
      invoke  resource_route
       route    resources :posts
      invoke  scaffold_controller
      create    app/controllers/posts_controller.rb
      invoke    inertia_templates
      create      app/frontend/pages/posts
      create      app/frontend/pages/posts/index.svelte
      create      app/frontend/pages/posts/edit.svelte
      create      app/frontend/pages/posts/show.svelte
      create      app/frontend/pages/posts/new.svelte
      create      app/frontend/pages/posts/form.svelte
      create      app/frontend/pages/posts/post.svelte
      invoke    resource_route
      invoke    test_unit
      create      test/controllers/posts_controller_test.rb
      create      test/system/posts_test.rb
      invoke    helper
      create      app/helpers/posts_helper.rb
      invoke      test_unit
```

--------------------------------

### usePoll(interval, options, { autoStart: false })

Source: https://inertia-rails.dev/guide/polling

Starts polling with manual control. The `autoStart: false` option prevents polling from starting automatically when the component is mounted. The returned `start` and `stop` methods allow manual control.

```APIDOC
## usePoll(interval, options, { autoStart: false })

### Description
Starts polling with manual control. The `autoStart: false` option prevents polling from starting automatically when the component is mounted. The returned `start` and `stop` methods allow manual control.

### Method
usePoll

### Parameters
- **interval** (number) - Required - The polling interval in milliseconds.
- **options** (object) - Optional - Request options to pass to `router.reload`.
- **autoStart** (boolean) - Optional - If `false`, polling does not start automatically. Default is `true`.

### Request Example
```js
import { usePoll } from '@inertiajs/vue3'

const { start, stop } = usePoll(
  2000,
  {},
  {
    autoStart: false,
  },
)
```

### Response
Returns an object with `start`, `stop`, and `polling` properties.
```

--------------------------------

### Start timeout to show progress after delay

Source: https://inertia-rails.dev/guide/progress-indicators

Update the 'start' event listener to start a timeout that shows the progress bar after 250 milliseconds.

```javascript
router.on('start', () => {
  timeout = setTimeout(() => NProgress.start(), 250)
})
```

--------------------------------

### Install @inertiajs/vue3 v2.0

Source: https://inertia-rails.dev/guide/upgrade-guide

Use npm to install the Vue 3 client-side adapter for Inertia.js v2.0. This is the first step in upgrading dependencies.

```bash
npm install @inertiajs/vue3@^2.0
```

--------------------------------

### Install Inertia Vue3 adapter and Vite plugin

Source: https://inertia-rails.dev/guide/client-side-setup

Install the Inertia client-side adapter and Vite plugin using npm. The @inertiajs/vite plugin supports Vite 7 and Vite 8.

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

--------------------------------

### Update configuration at runtime with config.set() and config.get()

Source: https://inertia-rails.dev/guide/client-side-setup

Use the exported config instance to set or get configuration values at runtime. Supports dot notation for single values, an object for multiple values, and get() to retrieve a value.

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

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

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

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

--------------------------------

### Create a new Rails app with Inertia

Source: https://inertia-rails.dev/cookbook/integrating-shadcn-ui

Commands to create a new Rails application with Inertia, add the inertia_rails gem, and generate the Inertia installer with React, TypeScript, Vite, and Tailwind CSS. The installer runs non-interactively.

```bash
rails new -JA shadcn-inertia-rails
cd shadcn-inertia-rails

bundle add inertia_rails

rails generate inertia:install --framework=react --typescript --vite --tailwind --no-interactive
Installing Inertia's Rails adapter
...
```

--------------------------------

### Install @inertiaui/modal-vue NPM package

Source: https://inertia-rails.dev/cookbook/inertia-modal

Install the InertiaUI Modal Vue package via npm. Version 3.0+ includes TypeScript support.

```bash
npm install @inertiaui/modal-vue
```

--------------------------------

### Use Typelizer route helpers

Source: https://inertia-rails.dev/guide/routing

Example of importing and using Typelizer-generated route helpers. Each helper returns an object with `url` and `method` keys.

```js
import { users } from '@/routes'

users.index() // => { url: '/users', method: 'get' }
users.show(1) // => { url: '/users/1', method: 'get' }
users.update(1) // => { url: '/users/1', method: 'patch' }
```

--------------------------------

### Add data to a manual visit

Source: https://inertia-rails.dev/guide/manual-visits

Use the `data` option to add data to the request. This example sends a POST request with a JSON payload.

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

router.visit('/users', {
  method: 'post',
  data: {
    name: 'John Doe',
    email: '[email protected]',
  },
})
```

--------------------------------

### router.visit(url, { method: 'post' })

Source: https://inertia-rails.dev/guide/manual-visits

Makes a manual visit to the given URL using the specified HTTP method. The method option can be set to 'get', 'post', 'put', 'patch', or 'delete', with 'get' as the default.

```APIDOC
## router.visit(url, options)

### Description
Makes a manual visit to the given URL using the specified HTTP method. The method option can be set to 'get', 'post', 'put', 'patch', or 'delete', with 'get' as the default.

### Method
POST (example)

### Endpoint
(url)

### Parameters
#### Options
- **method** (string) - Optional - The HTTP method to use: 'get', 'post', 'put', 'patch', or 'delete'. Default is 'get'.
- **data** (object) - Optional - Data to include in the request body.

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

router.visit(url, { method: 'post' })
```

### Response
No response body is documented.
```

--------------------------------

### Install @inertiajs/core as direct dependency

Source: https://inertia-rails.dev/guide/typescript

Alternative to hoisting: add @inertiajs/core as a direct dependency to resolve module augmentation issues with pnpm.

```bash
pnpm add @inertiajs/core
```

--------------------------------

### Install inertia_rails gem

Source: https://inertia-rails.dev/guide/server-side-setup

Adds the Inertia server-side adapter gem to the application's Gemfile.

```bash
bundle add inertia_rails
```

--------------------------------

### router.get(url, data, options)

Source: https://inertia-rails.dev/guide/manual-visits

Shortcut method to perform a GET visit. Shares all options with router.visit().

```APIDOC
## router.get(url, data, options)

### Description
Shortcut method to perform a GET visit. Shares all options with router.visit().

### Method
get

### Endpoint
router.get(url, data, options)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to visit.

#### Request Body
- **data** (object) - Optional - Data to send with the request.
- **options** (object) - Optional - Options object, same as router.visit() options.

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

router.get(url, data, options)
```

### Response
No response body is documented. The method returns a visit object or triggers callbacks.
```

--------------------------------

### Register event listener with router.on()

Source: https://inertia-rails.dev/guide/events

Use router.on() to register an event listener for the 'start' event. The event object contains a detail.visit.url property.

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

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

--------------------------------

### Initialize shadcn/ui

Source: https://inertia-rails.dev/cookbook/integrating-shadcn-ui

Run npx shadcn@latest init to initialize shadcn/ui. The output shows the interactive prompts and the files created, including app/frontend/lib/utils.js.

```bash
npx shadcn@latest init

✔ Preflight checks.
✔ Verifying framework. Found Vite.
✔ Validating Tailwind CSS.
✔ Validating import alias.
✔ Which style would you like to use? › New York
✔ Which color would you like to use as the base color? › Neutral
✔ Would you like to use CSS variables for theming? … no / yes
✔ Writing components.json.
✔ Checking registry.
✔ Updating tailwind.config.js
✔ Updating app/frontend/entrypoints/application.css
✔ Installing dependencies.
✔ Created 1 file:
  - app/frontend/lib/utils.js

Success! Project initialization completed.
You may now add components.
```

--------------------------------

### Assert optional props after enabling evaluate_optional_props

Source: https://inertia-rails.dev/guide/testing

After enabling `evaluate_optional_props`, optional and deferred props are included in `inertia.props` on first load. This example shows asserting `:analytics` and `:statistics` props after a GET request.

```ruby
get events_path

expect(inertia.props[:analytics]).to be_present
expect(inertia.props[:statistics]).to eq({ views: 100 })
```

--------------------------------

### progress.start()

Source: https://inertia-rails.dev/guide/progress-indicators

Begins the progress animation.

```APIDOC
## progress.start()

### Description
Begins the progress animation.

### Method
start

### Parameters
None

### Returns
None

### Example
```js
progress.start()
```
```

--------------------------------

### Run Inertia Rails generator

Source: https://inertia-rails.dev/guide/server-side-setup

Executes the built-in generator to install and set up Inertia in a Rails application. It checks for Vite Rails, asks about TypeScript, frontend framework, and Tailwind CSS, and copies example files.

```bash
bin/rails generate inertia:install
```

--------------------------------

### Vue: Specify HTTP method with `method` prop

Source: https://inertia-rails.dev/guide/links

Use the `method` prop to make POST, PUT, PATCH, or DELETE requests via links. The default is GET. This example creates a logout button that submits a POST request.

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

<template>
  <Link href="/logout" method="post" as="button">Logout</Link>
</template>
```

--------------------------------

### Enable Precognition with withPrecognition()

Source: https://inertia-rails.dev/guide/http-requests

Chain withPrecognition() after useHttp() to enable real-time validation. Requires server-side support; see the Precognition guide for Rails setup. Once enabled, validate(), touch(), touched(), valid(), and invalid() methods become available.

```javascript
import { useHttp } from '@inertiajs/vue3'

const http = useHttp({
  name: '',
  email: '',
}).withPrecognition('post', '/api/users')
```

--------------------------------

### router.post with all event callbacks

Source: https://inertia-rails.dev/guide/manual-visits

Example of using the router.post method with all available per-visit event callbacks. Each callback receives specific parameters and can be used to react to different stages of the visit.

```APIDOC
## router.post

### Description
Performs a POST request to the given URL and attaches per-visit event callbacks to handle the visit lifecycle.

### Method
POST

### Endpoint
`/users`

### Parameters
#### Request Body
- `data` (object) - Required - The data to send in the request body.

#### Options
- `onBefore` (function) - Optional - Called before the visit starts. Returning `false` cancels the visit.
- `onStart` (function) - Optional - Called when the visit starts.
- `onProgress` (function) - Optional - Called with progress information during the visit.
- `onSuccess` (function) - Optional - Called when the visit succeeds. Can return a promise to delay the finish event.
- `onError` (function) - Optional - Called when the visit fails with validation errors. Can return a promise to delay the finish event.
- `onHttpException` (function) - Optional - Called when an HTTP exception occurs. Returning `false` prevents the corresponding global event.
- `onNetworkError` (function) - Optional - Called when a network error occurs. Returning `false` prevents the corresponding global event.
- `onCancel` (function) - Optional - Called when the visit is canceled.
- `onFinish` (function) - Optional - Called when the visit finishes, after all other callbacks and any promises have resolved.
- `onPrefetching` (function) - Optional - Called when prefetching starts.
- `onPrefetched` (function) - Optional - Called when prefetching completes.

### Request Example
```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: () => {},
})
```

### Response
#### Success Response (200)
- `page` (object) - The Inertia page object passed to the `onSuccess` callback.

#### Error Response (4xx/5xx)
- `errors` (object) - Validation errors passed to the `onError` callback.
- `response` (object) - The HTTP response passed to the `onHttpException` callback.
- `error` (object) - The network error passed to the `onNetworkError` callback.

### Notes
- Returning `false` from `onBefore()` cancels the visit.
- Returning `false` from `onHttpException()` or `onNetworkError()` prevents the corresponding global event from firing and its default behavior.
- Returning a promise from `onSuccess()` or `onError()` delays the `onFinish` callback until the promise resolves.
```

--------------------------------

### Initialize Inertia app with Vue3

Source: https://inertia-rails.dev/guide/client-side-setup

Minimal entry point to boot the Inertia app. The Vite plugin handles page resolution and mounting automatically. The pages path is relative to the entry point; the Rails generator uses '../pages'.

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

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

--------------------------------

### Install lodash-es package

Source: https://inertia-rails.dev/guide/upgrade-guide

Install lodash-es directly if your application imports it, as it is no longer a dependency of @inertiajs/core.

```bash
npm install lodash-es
```

--------------------------------

### Pass defaults to createInertiaApp()

Source: https://inertia-rails.dev/guide/client-side-setup

Configure default settings for form, prefetch, and visit options. The visitOptions callback receives the target URL and current options, and returns an object with overrides.

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

--------------------------------

### Create SSR entry point file

Source: https://inertia-rails.dev/guide/server-side-rendering

Creates the SSR entry point file at app/frontend/ssr/ssr.js using the touch command.

```bash
touch app/frontend/ssr/ssr.js
```

--------------------------------

### Customize progress indicator with createInertiaApp progress options

Source: https://inertia-rails.dev/guide/progress-indicators

Configure the default NProgress-based progress bar by passing a `progress` object to `createInertiaApp()`. Options include `delay` (ms), `color`, `includeCSS`, and `showSpinner`. For CSP-restricted apps, pass a `nonce` to permit injected styles.

```javascript
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,
  },
  // ...
})
```

--------------------------------

### router.visit() with all options

Source: https://inertia-rails.dev/guide/manual-visits

Use this method to manually make an Inertia visit with full control over the request. It accepts a URL and an options object with many configuration options, including method, data, callbacks, and more.

```javascript
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: () => {},
})
```

--------------------------------

### Configure .babelrc for dynamic imports

Source: https://inertia-rails.dev/guide/code-splitting

Create a `.babelrc` file with the plugin configuration to enable dynamic import syntax.

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

--------------------------------

### Check if progress bar started on progress

Source: https://inertia-rails.dev/guide/progress-indicators

In the 'progress' event listener, check if the progress bar has started to avoid updating it before the timeout.

```javascript
router.on('progress', (event) => {
  if (!NProgress.isStarted()) {
    return
  }
  // ...
})
```

--------------------------------

### Check if progress bar started on finish

Source: https://inertia-rails.dev/guide/progress-indicators

In the 'finish' event listener, check if the progress bar has started to avoid showing it after the timeout.

```javascript
router.on('finish', (event) => {
  clearTimeout(timeout)

  if (!NProgress.isStarted()) {
    return
  }
  // ...
})
```

--------------------------------

### Deferred props response example

Source: https://inertia-rails.dev/guide/the-protocol

Example JSON response showing deferredProps grouping: default group for comments and analytics, sidebar group for relatedPosts.

```json
{
  "component": "Posts/Index",
  "props": {
    "errors": {},
    "user": {
      "name": "Jonathan"
    }
  },
  "url": "/posts",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "deferredProps": {
    "default": ["comments", "analytics"],
    "sidebar": ["relatedPosts"]
  }
}
```

--------------------------------

### router.visit(url, options)

Source: https://inertia-rails.dev/guide/manual-visits

Manually make an Inertia visit to the given URL with the provided options. This is the core method for programmatic visits.

```APIDOC
## router.visit(url, options)

### Description
Manually make an Inertia visit to the given URL with the provided options. This is the core method for programmatic visits.

### Method
visit

### Endpoint
router.visit(url, options)

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to visit.

#### Options
- **method** (string) - Optional - The HTTP method to use (e.g., 'get', 'post'). Default: 'get'.
- **data** (object) - Optional - Data to send with the request.
- **replace** (boolean) - Optional - Whether to replace the current history entry. Default: false.
- **preserveState** (boolean) - Optional - Whether to preserve the component state. Default: false.
- **preserveScroll** (boolean) - Optional - Whether to preserve the scroll position. Default: false.
- **only** (array) - Optional - List of props to load.
- **except** (array) - Optional - List of props to exclude.
- **headers** (object) - Optional - Custom headers.
- **errorBag** (string|null) - Optional - Error bag name.
- **forceFormData** (boolean) - Optional - Force FormData encoding. Default: false.
- **queryStringArrayFormat** (string) - Optional - Format for array query parameters. Default: 'brackets'.
- **async** (boolean) - Optional - Whether the request is asynchronous. Default: false.
- **showProgress** (boolean) - Optional - Whether to show progress. Default: true.
- **fresh** (boolean) - Optional - Whether to force a fresh visit. Default: false.
- **reset** (array) - Optional - List of fields to reset.
- **preserveUrl** (boolean) - Optional - Whether to preserve the URL. Default: false.
- **prefetch** (boolean) - Optional - Whether to prefetch the page. Default: false.
- **preserveErrors** (boolean) - Optional - Whether to preserve errors. Default: false.
- **viewTransition** (boolean) - Optional - Whether to use view transitions. Default: false.
- **component** (string|null) - Optional - Component name.
- **pageProps** (object|null) - Optional - Page props.
- **onCancelToken** (function) - Optional - Callback for cancel token.
- **onCancel** (function) - Optional - Callback on cancel.
- **onBefore** (function) - Optional - Callback before visit.
- **onStart** (function) - Optional - Callback on start.
- **onProgress** (function) - Optional - Callback on progress.
- **onSuccess** (function) - Optional - Callback on success.
- **onError** (function) - Optional - Callback on error.
- **onHttpException** (function) - Optional - Callback on HTTP exception.
- **onNetworkError** (function) - Optional - Callback on network error.
- **onFinish** (function) - Optional - Callback on finish.
- **onPrefetching** (function) - Optional - Callback when prefetching starts.
- **onPrefetched** (function) - Optional - Callback when prefetching completes.

### Request Example
```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: () => {},
})
```

### Response
No response body is documented. The method returns a visit object or triggers callbacks.
```

--------------------------------

### Rescued deferred props response example

Source: https://inertia-rails.dev/guide/the-protocol

Example JSON response showing rescuedProps array containing the key of a deferred prop that raised an exception, with the prop omitted from props.

```json
{
  "component": "Users/Index",
  "props": {
    "errors": {}
  },
  "url": "/users",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "rescuedProps": ["permissions"]
}
```

--------------------------------

### http.post() with Event Callbacks

Source: https://inertia-rails.dev/guide/http-requests

Each submit method (e.g., post) accepts an options object with lifecycle callbacks: onBefore, onStart, onProgress, onSuccess, onError, onHttpException, onNetworkError, onCancel, and onFinish. Returning false from onBefore cancels the request.

```APIDOC
## http.post() with Event Callbacks

### Description
Submits a POST request with lifecycle event callbacks. The options object can include onBefore, onStart, onProgress, onSuccess, onError, onHttpException, onNetworkError, onCancel, and onFinish. Returning false from onBefore cancels the request.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **onBefore** (Function) - Optional - Called before the request is sent. Return false to cancel the request.
- **onStart** (Function) - Optional - Called when the request starts.
- **onProgress** (Function) - Optional - Called with progress information.
- **onSuccess** (Function) - Optional - Called on success. Receives (data, response).
- **onError** (Function) - Optional - Called on validation errors (422). Receives errors object.
- **onHttpException** (Function) - Optional - Called on non-422 HTTP errors. Receives response object.
- **onNetworkError** (Function) - Optional - Called on network errors. Receives Error object.
- **onCancel** (Function) - Optional - Called when the request is cancelled.
- **onFinish** (Function) - Optional - Called when the request finishes.

### Request Example
```js
http.post('/api/users', {
  onBefore: () => { /*...*/ },
  onStart: () => { /*...*/ },
  onProgress: (progress) => { /*...*/ },
  onSuccess: (data, response) => { /*...*/ },
  onError: (errors) => { /*...*/ },
  onHttpException: (response) => { /*...*/ },
  onNetworkError: (error) => { /*...*/ },
  onCancel: () => { /*...*/ },
  onFinish: () => { /*...*/ },
})
```

### Response
No direct response; the callbacks handle the response.
```

--------------------------------

### Set HTTP method with router.visit

Source: https://inertia-rails.dev/guide/manual-visits

Use the `method` option to set the request's HTTP method to `get`, `post`, `put`, `patch`, or `delete`. The default method is `get`.

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

router.visit(url, { method: 'post' })
```

--------------------------------

### Generate Inertia controller

Source: https://inertia-rails.dev/guide/responses

Run this command to create a controller with Inertia responses. Replace ControllerName, action1, action2 with your controller name and actions.

```bash
bin/rails generate inertia:controller ControllerName action1 action2
```

--------------------------------

### progress.reset()

Source: https://inertia-rails.dev/guide/progress-indicators

Resets the progress to the start.

```APIDOC
## progress.reset()

### Description
Resets the progress to the start.

### Method
reset

### Parameters
None

### Returns
None

### Example
```js
progress.reset()
```
```

--------------------------------

### Programmatic instant visit with router.visit()

Source: https://inertia-rails.dev/guide/instant-visits

Use the component option on router.visit() to make a programmatic instant visit. The target component must be able to render without its page-specific props.

```javascript
router.visit('/dashboard', {
  component: 'dashboard/index',
})
```

--------------------------------

### Example page object with merge props and matchPropsOn

Source: https://inertia-rails.dev/guide/the-protocol

Shows a page object with mergeProps, prependProps, deepMergeProps, and matchPropsOn arrays. The mergeProps array appends posts, prependProps prepends notifications, deepMergeProps deep merges conversations, and matchPropsOn keys each array by the specified field.

```json
{
  "component": "Feed/Index",
  "props": {
    "errors": {},
    "user": {
      "name": "Jonathan"
    },
    "posts": [
      {
        "id": 1,
        "title": "First Post"
      }
    ],
    "notifications": [
      {
        "id": 2,
        "message": "New comment"
      }
    ],
    "conversations": {
      "data": [
        {
          "id": 1,
          "title": "Support Chat",
          "participants": ["John", "Jane"]
        }
      ]
    }
  },
  "url": "/feed",
  "version": "6b16b94d7c51cbe5b1fa42aac98241d5",
  "mergeProps": ["posts"],
  "prependProps": ["notifications"],
  "deepMergeProps": ["conversations"],
  "matchPropsOn": ["posts.id", "notifications.id", "conversations.data.id"]
}
```

--------------------------------

### One call per action - bad and good examples

Source: https://inertia-rails.dev/guide/precognition

Shows that calling precognition! twice in a controller action raises InertiaRails::DoublePrecognitionError. The good example uses a form object to validate multiple models in a single call.

```ruby
# Bad — raises DoublePrecognitionError
def create
  precognition!(@user)
  precognition!(@profile) # Error!
end

# Good — validate everything in one call
def create
  form = RegistrationForm.new(params)
  precognition!(form) # Validates user + profile together
end
```

--------------------------------

### Preserve state with router.get using preserveState: true

Source: https://inertia-rails.dev/guide/manual-visits

Sets preserveState to true to keep the page component's local state (e.g., form inputs) when using the get method. This is needed because get does not preserve state by default.

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

router.get('/users', { search: 'John' }, { preserveState: true })
```

--------------------------------

### useHttp().post() for File Uploads

Source: https://inertia-rails.dev/guide/http-requests

Demonstrates how to use the useHttp hook to upload files. The hook automatically sends the request as multipart/form-data and provides upload progress via the progress property.

```APIDOC
## useHttp().post() for File Uploads

### Description
Use the `useHttp` hook to upload files. When the data includes files, the request is automatically sent as `multipart/form-data`. Upload progress is available through the `progress` property.

### Method
`post`

### Endpoint
`/api/uploads`

### Parameters
#### Request Body
- **file** (File) - Required - The file to upload.

### Request Example
```js
const http = useHttp({
  file: null,
})

function upload() {
  http.post('/api/uploads')
}
```

### Response
#### Success Response
- **progress** (object) - Contains upload progress information, including `percentage`.

#### Response Example
```html
<progress v-if="http.progress" :value="http.progress.percentage" max="100" />
```
```

--------------------------------

### Configure Inertia with withInertiaModal (Vue)

Source: https://inertia-rails.dev/cookbook/inertia-modal

Update the Inertia app setup to mount the modal root component using the withInertiaModal function. If a setup callback or custom layout is already defined, render <ModalRoot /> inside the existing layout instead.

```js
// app/frontend/entrypoints/inertia.js
import { createInertiaApp } from '@inertiajs/vue3'
import { withInertiaModal } from '@inertiaui/modal-vue'

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

--------------------------------

### progress.isStarted()

Source: https://inertia-rails.dev/guide/progress-indicators

Returns a boolean indicating whether the progress has started.

```APIDOC
## progress.isStarted()

### Description
Returns a boolean indicating whether the progress has started.

### Method
isStarted

### Parameters
None

### Returns
- **boolean** - True if progress has started, false otherwise.

### Example
```js
progress.isStarted()
```
```

--------------------------------

### useForm

Source: https://inertia-rails.dev/guide/forms

Initializes a form instance with the given initial data. The returned form object provides methods and properties for managing form state and submission.

```APIDOC
## useForm

### Description
Initializes a form instance with the given initial data. The returned form object provides methods and properties for managing form state and submission.

### Method
useForm

### Parameters
- **initialData** (Object) - Required - The initial form data.

### Request Example
```js
const form = useForm({
  email: null,
  password: null,
  remember: false,
})
```

### Response
Returns a form object with methods and properties for form management.
```

--------------------------------

### Basic Precognition Controller Example

Source: https://inertia-rails.dev/guide/precognition

Use `precognition!` in a controller action to handle precognition requests. It raises an exception to halt the action on precognition requests, returning false for non-precognition requests. The example shows a `create` action that validates a user and redirects on success or failure.

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

    if @user.save
      redirect_to @user
    else
      redirect_back_or_to new_user_path, inertia: { errors: @user.errors }
    end
  end
end
```
Tokens:
Raw