Inertia provides an event system that allows you to "hook into" the various lifecycle events of the library.
To register an event listener, use the Inertia.on() method.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('start', (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
})Under the hood Inertia uses native browser events, so you can also work with them that way as well. Just be sure to append inertia: to the event name.
document.addEventListener('inertia:start', (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
})When you register an event listener, Inertia automatically returns you a callback to remove the event listener.
let removeStartEventListener = Inertia.on('start', (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
})
// Remove the listener
removeStartEventListener()Combined with hooks, you can automatically remove the event listener on component unmount.
import { Inertia } from '@inertiajs/inertia'
import { onUnmounted } from 'vue'
export default {
setup() {
onUnmounted(
Inertia.on('start', (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
})
)
},
}Alternatively, if you're using native browser events, you can remove the event listener using removeEventListener().
let startEventListener = (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
}
document.addEventListener('inertia:start', startEventListener)
// Remove the listener
document.removeEventListener('inertia:start', startEventListener)Some events (before, invalid, error) support cancellation, allowing you to prevent Inertia's default behaviour. Just like native events, if only one event listener calls event.preventDefault(), the event will be cancelled.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('before', (event) => {
if (!confirm('Are you sure you want to navigate away?')) {
event.preventDefault()
}
})As a convenience, if you register your event listener using Inertia.on(), you can also cancel the event by returning false from the listener.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('before', (event) => {
return confirm('Are you sure you want to navigate away?')
})The before event fires when a request is about to be made to the server. This is useful for intercepting visits.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('before', (event) => {
console.log(`About to make a visit to ${event.detail.visit.url}`)
})The primary purpose of this event is to allow you to prevent a visit from happening.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('before', (event) => {
return confirm('Are you sure you want to navigate away?')
})The start event fires when a request to the server has started. This is useful for displaying loading indicators.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('start', (event) => {
console.log(`Starting a visit to ${event.detail.visit.url}`)
})The start event is not cancelable.
The progress event fires as progress increments during file uploads.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('progress', (event) => {
this.form.progress = event.detail.progress.percentage
})The progress event is not cancelable.
The success event fires on successful page visits, unless validation errors are present. Note, this does not include history visits.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('success', (event) => {
console.log(`Successfully made a visit to ${event.detail.page.url}`)
})The success event is not cancelable.
The error event fires when validation errors are present on "successful" page visits.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('error', (errors) => {
console.log(errors)
})The error event is not cancelable.
The invalid event fires when a non-Inertia response is received from the server, such as an html or json response. A valid Inertia response is one that has the X-Inertia header set to true with a json payload containing the page object.
This event is fired for all response types, including 200, 400, and 500 response codes.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('invalid', (event) => {
console.log(`An invalid Inertia response was received.`)
console.log(event.detail.response)
})Cancel the invalid event to prevent Inertia from showing the non-Inertia response modal.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('invalid', (event) => {
event.preventDefault()
// Handle the invalid response yourself
})The exception event fires on unexpected XHR errors, such as network interruptions, and for errors generated when resolving page components.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('exception', (event) => {
console.log(`An unexpected error occurred during an Inertia visit.`)
console.log(event.detail.error)
})Cancel the exception event to prevent the error from being thrown.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('exception', (event) => {
event.preventDefault()
// Handle the error yourself
})Note, this event will not fire for XHR requests that receive 400 and 500 level responses, or for non-Inertia responses, as these situations are handled in other ways by Inertia. See the error handling page for more information.
The finish event fires after an XHR request has completed for both successful and unsuccessful responses. This event is useful for hiding loading indicators.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('finish', (event) => {
NProgress.done()
})The finish event is not cancelable.
The navigate event fires on successful page visits, as well as when navigating through history. This event is useful for tracking analytics and things of that nature.
import { Inertia } from '@inertiajs/inertia'
Inertia.on('navigate', (event) => {
console.log(`Navigated to ${event.detail.page.url}`)
})The navigate event is not cancelable.
In addition to the global events, Inertia also provides a number of event callbacks when manually making Inertia visits.