inertia@v0.3.0

Global events

This release adds a new event system to Inertia.js, allowing developers to "hook into" the various lifecycle events of the library. Here's how to use it:

import { Inertia } from '@inertiajs/inertia'

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

When you register an event, Inertia automatically returns you a callback to unregister the event. Combined with a destroyed hook, you can do something like this to automatically unregister the event when you navigate to a different page.

export default {
  mounted() {
    this.$once(
      'hook:destroyed',
      Inertia.on('start', (event) => {
        if (!confirm('Are you sure you want to navigate away?')) {
          event.preventDefault()
        }
      })
    )
  },
}

Under the hood this uses native browser events, so you can also work with them that way. For example:

document.addEventListener('inertia:start', (event) => {
  console.log(`starting a visit to ${event.detail.visit.url}`)
})

Some events 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.

Here is a complete list of all the available events:

Event callbacks

In addition to the global events, this release adds a number of visit event callbacks.

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

Visit promise deprecated

This release deprecates the promise that is returned from Inertia.visit(). If you call then(), catch() or finally() on an Inertia visit, you'll get the following 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/events

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

Inertia.post('/profile', data, {
  onSuccess: () => {
    if (this.errors.isEmpty()) {
      this.form.password = null
    }
  },
})

And, instead of using finally(), use onFinish() instead:

Inertia.post('/profile', data, {
  onFinish: () => (this.sending = false),
})

NProgress removed (breaking change)

This PR removes the direct NProgress integration, since the new event system makes this so easy to do outside of Inertia core. This behaviour is now available via a first-class package called @inertiajs/progress.

To add the new progress library to your project, first install the package:

npm install @inertiajs/progress
yarn add @inertiajs/progress

Once it's been installed, initialize it in your app:

import { InertiaProgress } from '@inertiajs/progress'

InertiaProgress.init({
  // The delay after which the progress bar will
  // appear during navigation, 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,
})

Other changes

• Restored lazy evaluation of preserveScroll and preserveState (#231).
• Scroll region improvements (refactored to a single scroll event listener).