Manual visits

In addition to creating links, it's also possible to manually make Inertia visits. This is done using the Inertia.visit() method.

// import { Inertia } from '@inertiajs/inertia'

this.$inertia.visit(url, {
  method: 'get',
  data: {},
  replace: false,
  preserveState: false,
  preserveScroll: false,
  only: [],
  headers: {},
  onCancelToken: cancelToken => {},
  onCancel: () => {},
  onStart: visit => {},
  onProgress: progress => {},
  onSuccess: page => {},
  onFinish: () => {},
})

However, generally it's preferred to use one of the shortcut methods instead. These methods share all the same options as Inertia.visit().

// import { Inertia } from '@inertiajs/inertia'

this.$inertia.get(url, data, options)
this.$inertia.post(url, data, options)
this.$inertia.put(url, data, options)
this.$inertia.patch(url, data, options)
this.$inertia.delete(url, options)
this.$inertia.replace(url, options)
this.$inertia.reload(options) // Uses the current URL

Method

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

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

Data

Use the data option to add data to the request.

Inertia.visit('/users', {
  method: 'post',
  data: {
    name: 'John Doe',
    email: 'john.doe@example.com',
  },
})

As a convenience, the get(), post(), put() and patch() methods all include data as the second argument.

Inertia.post('/users', {
  name: 'John Doe',
  email: 'john.doe@example.com',
})

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 using by setting the replace option to true.

Inertia.get('/users', { search: 'John' }, { replace: true })

As a shortcut, you can use replace() method to automatically do this.

Inertia.replace('/users', { search: 'John' })
Note that visits made to the same URL (including query strings) automatically set replace to true.

Component state

By default page visits to the same page force a fresh page component instance, which clears out any local state, such as form inputs, scroll positions and focus states.

In certain 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 validation errors come back.

This can be done by setting the preserveState option to true.

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

For convenience, the post(), put(), patch() and replace() methods autmatically set preserveState to true.

Scroll preservation

When navigating between pages, Inertia mimics default browser behaviour by automatically resetting the scroll position of the document body (as well as any scroll regions you've defined), back to the top. Use the preserveScroll option to disable this behaviour.

Inertia.visit(url, { preserveScroll: true })

For more information, see the scroll management page.

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.

Inertia.visit('/users', { search: 'John' }, { only: ['users'] })

For more information, see the partial reloads page.

Custom headers

The headers option allows you to add custom headers to a request.

Inertia.post('/users', data, {
  headers: {
    'Custom-Header': 'value',
  },
})
The Inertia headers take priority and therefore cannot be overwritten.

Visit cancellation

You can cancel a visit using a cancel token, which Inertia automatically generates and provides via the onCancelToken() callback prior to making the visit.

Inertia.post('/users', data, {
  onCancelToken: cancelToken => (this.cancelToken = cancelToken),
})

// Cancel the visit
this.cancelToken.cancel()

When a visit is cancelled, both the onCancel() and onFinish() event callbacks will be called.

Event callbacks

In addition to the global events, Inertia also provides a number of per-visit event callbacks.

Inertia.post('/users', data, {
  onStart: visit => {},
  onProgress: progress => {},
  onSuccess: page => {},
  onCancel: () => {},
  onFinish: () => {},
})

Returning false from the onStart() callback will cause the visit to be cancelled.

Inertia.delete(`/users/${user.id}`, {
  onStart: () => confirm('Are you sure you want to delete this user?'),
})

It's also possible to return a promise from the onSuccess() callback. This will delay the "finish" event until the promise has resolved.

Inertia.post(url, {
  onSuccess: () => {
    return Promise.all([
      this.doThing(),
      this.doAnotherThing()
    ])
  }
  onFinish: () => {
    // This won't be called until doThing()
    // and doAnotherThing() have finished.
  },
})

Promise deprecation

As of v0.3.0, Inertia deprecated the promise that is returned from Inertia.visit(). If you call then(), catch() or finally() on an Inertia visit, you will now get the following console warning:

Inertia.js visit promises have been deprecated and will be removed in a future release. Please use the new visit event callbacks instead.
Learn more at https://inertiajs.com/manual-visits#promise-deprecation

The preferred approach is to use the new event callbacks instead. For example, instead of using then(), use the onSuccess() callback.

Inertia.post('/profile', data, {
  onSuccess: () => {
    // Handle success event
  },
})

Instead of using finally(), use the onFinish() callback.

Inertia.post('/profile', data, {
  onFinish: () => {
    // Handle finish event
  },
})

And instead of using catch(), it's better to handle these unexpected errors using a global error event handler.

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