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: {},
  errorBag: null,
  forceFormData: false,
  onCancelToken: cancelToken => {},
  onCancel: () => {},
  onBefore: visit => {},
  onStart: visit => {},
  onProgress: progress => {},
  onSuccess: page => {},
  onError: errors => {},
  onFinish: visit => {},
})

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.reload(options) // Uses the current URL

The reload() method is simply a shorthand that automatically visits the current page, with preserveState and preserveScroll both set to true.

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 })

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 })

You can also lazily evaluate the preserveState option based on the response by providing a callback.

Inertia.post('/users', data, {
  preserveState: (page) => Object.keys(page.props.errors).length,
})

For convenience, the post, put, patch, delete and reload methods all default 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 })

You can also lazily evaluate the preserveScroll option based on the response by providing a callback.

Inertia.post('/users', data, {
  preserveScroll: (page) => Object.keys(page.props.errors).length,
})

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.

Error bags

For pages that have more than one form, it's possible to run into conflicts when displaying validation errors if two forms share the same field names. To get around this, you can use error bags. Error bags scope the validation errors returned from the server within a unique key specific to that form.

Inertia.post('/companies', data, {
  errorBag: 'createCompany',
})

For more information, see the validation page.

File uploads

When making visits that include files, Inertia will automatically convert the request data into a FormData object. If you'd like the visit to always use a FormData object, you can force this using the forceFormData option.

Inertia.post('/companies', data, {
  forceFormData: true,
})

See the file uploads page for more information.

Custom headers

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

Inertia.post('/users', data, {
  headers: {
    'Custom-Header': 'value',
  },
})

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, {
  onBefore: (visit) => {},
  onStart: (visit) => {},
  onProgress: (progress) => {},
  onSuccess: (page) => {},
  onError: (errors) => {},
  onCancel: () => {},
  onFinish: visit => {},
})

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

Inertia.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. This will delay the "finish" event until the promise has resolved.

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