Events

Inertia provides an event system that allows you to “hook into” the various lifecycle events of the library.

Registering Listeners

To register an event listener, use the router.on() method.

import { router } from "@inertiajs/vue3";

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

import { router } from "@inertiajs/react";

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

import { router } from "@inertiajs/svelte";

router.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 interact with Inertia events using the typical event methods you may already be familiar with - just be sure to prepend inertia: to the event name.

import { router } from "@inertiajs/vue3";

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

import { router } from "@inertiajs/react";

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

import { router } from "@inertiajs/svelte";

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

Removing Listeners

When you register an event listener, Inertia automatically returns a callback that can be invoked to remove the event listener.

import { router } from "@inertiajs/vue3";

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

// Remove the listener...
removeStartEventListener();

import { router } from "@inertiajs/react";

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

// Remove the listener...
removeStartEventListener();

import { router } from "@inertiajs/svelte";

let removeStartEventListener = router.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 when components unmount.

<script setup>
import { router } from '@inertiajs/vue3'
import { onUnmounted } from 'vue'

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

import { useEffect } from "react";
import { router } from "@inertiajs/react";

useEffect(() => {
  return router.on("start", (event) => {
    console.log(`Starting a visit to ${event.detail.visit.url}`);
  });
}, []);

import { router } from "@inertiajs/svelte";

$effect(() => {
  return router.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().

import { router } from "@inertiajs/vue3";

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

import { router } from "@inertiajs/react";

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

import { router } from "@inertiajs/svelte";

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

One-time Listeners

You may register a listener that fires only once using the router.once() method. The listener is automatically removed after the first invocation.

import { router } from "@inertiajs/vue3";

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

import { router } from "@inertiajs/react";

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

import { router } from "@inertiajs/svelte";

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

Like router.on(), this method returns a callback you may invoke to remove the listener before it fires.

import { router } from "@inertiajs/vue3";

let removeStartEventListener = router.once("start", (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`);
});

// Remove the listener before it fires...
removeStartEventListener();

import { router } from "@inertiajs/react";

let removeStartEventListener = router.once("start", (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`);
});

// Remove the listener before it fires...
removeStartEventListener();

import { router } from "@inertiajs/svelte";

let removeStartEventListener = router.once("start", (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`);
});

// Remove the listener before it fires...
removeStartEventListener();

Cancelling Events

Some events, such as before, networkError, httpException, and location, support cancellation, allowing you to prevent Inertia’s default behavior. Just like native events, the event will be cancelled if only one event listener calls event.preventDefault().

import { router } from "@inertiajs/vue3";

router.on("before", (event) => {
  if (!confirm("Are you sure you want to navigate away?")) {
    event.preventDefault();
  }
});

import { router } from "@inertiajs/react";

router.on("before", (event) => {
  if (!confirm("Are you sure you want to navigate away?")) {
    event.preventDefault();
  }
});

import { router } from "@inertiajs/svelte";

router.on("before", (event) => {
  if (!confirm("Are you sure you want to navigate away?")) {
    event.preventDefault();
  }
});

For convenience, if you register your event listener using router.on(), you can cancel the event by returning false from the listener.

import { router } from "@inertiajs/vue3";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

import { router } from "@inertiajs/react";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

import { router } from "@inertiajs/svelte";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

Note, browsers do not allow cancelling the native popstate event, so preventing forward and back history visits while using Inertia.js is not possible.

Before

The before event fires when a request is about to be made to the server. This is useful for intercepting visits.

import { router } from "@inertiajs/vue3";

router.on("before", (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/react";

router.on("before", (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/svelte";

router.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 { router } from "@inertiajs/vue3";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

import { router } from "@inertiajs/react";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

import { router } from "@inertiajs/svelte";

router.on("before", (event) => {
  return confirm("Are you sure you want to navigate away?");
});

Start

The start event fires when a request to the server has started. This is useful for displaying loading indicators.

import { router } from "@inertiajs/vue3";

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

import { router } from "@inertiajs/react";

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

import { router } from "@inertiajs/svelte";

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

The start event is not cancelable.

Progress

The progress event fires as progress increments during file uploads.

import { router } from "@inertiajs/vue3";

router.on("progress", (event) => {
  this.form.progress = event.detail.progress.percentage;
});

import { router } from "@inertiajs/react";

router.on("progress", (event) => {
  this.form.progress = event.detail.progress.percentage;
});

import { router } from "@inertiajs/svelte";

router.on("progress", (event) => {
  this.form.progress = event.detail.progress.percentage;
});

The progress event is not cancelable.

Success

The success event fires on successful page visits, unless validation errors are present. However, this does not include history visits.

import { router } from "@inertiajs/vue3";

router.on("success", (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`);
});

import { router } from "@inertiajs/react";

router.on("success", (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`);
});

import { router } from "@inertiajs/svelte";

router.on("success", (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`);
});

The success event is not cancelable.

Flash

The flash event fires when flash data is received from the server. This is useful for displaying toast notifications or handling temporary data in a central location.

import { router } from "@inertiajs/vue3";

router.on("flash", (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast);
  }
});

import { router } from "@inertiajs/react";

router.on("flash", (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast);
  }
});

import { router } from "@inertiajs/svelte";

router.on("flash", (event) => {
  if (event.detail.flash.toast) {
    showToast(event.detail.flash.toast);
  }
});

The flash event is not cancelable and fires on every response that carries flash data.

Error

The error event fires when validation errors are present on “successful” page visits.

import { router } from "@inertiajs/vue3";

router.on("error", (event) => {
  console.log(event.detail.errors);
});

import { router } from "@inertiajs/react";

router.on("error", (event) => {
  console.log(event.detail.errors);
});

import { router } from "@inertiajs/svelte";

router.on("error", (event) => {
  console.log(event.detail.errors);
});

The error event is not cancelable.

HTTP Exception

The httpException event fires when a non-Inertia response is received from the server, such as an HTML or vanilla JSON response. A valid Inertia response is a response 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 { router } from "@inertiajs/vue3";

router.on("httpException", (event) => {
  console.log(`An invalid Inertia response was received.`);
  console.log(event.detail.response);
});

import { router } from "@inertiajs/react";

router.on("httpException", (event) => {
  console.log(`An invalid Inertia response was received.`);
  console.log(event.detail.response);
});

import { router } from "@inertiajs/svelte";

router.on("httpException", (event) => {
  console.log(`An invalid Inertia response was received.`);
  console.log(event.detail.response);
});

You may cancel the httpException event to prevent Inertia from showing the non-Inertia response modal.

import { router } from "@inertiajs/vue3";

router.on("httpException", (event) => {
  event.preventDefault();

  // Handle the invalid response yourself...
});

import { router } from "@inertiajs/react";

router.on("httpException", (event) => {
  event.preventDefault();

  // Handle the invalid response yourself...
});

import { router } from "@inertiajs/svelte";

router.on("httpException", (event) => {
  event.preventDefault();

  // Handle the invalid response yourself...
});

Network Error

The networkError event fires on unexpected XHR errors such as network interruptions. In addition, this event fires for errors generated when resolving page components.

import { router } from "@inertiajs/vue3";

router.on("networkError", (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`);
  console.log(event.detail.error);
});

import { router } from "@inertiajs/react";

router.on("networkError", (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`);
  console.log(event.detail.error);
});

import { router } from "@inertiajs/svelte";

router.on("networkError", (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`);
  console.log(event.detail.error);
});

You may cancel the networkError event to prevent the error from being thrown.

import { router } from "@inertiajs/vue3";

router.on("networkError", (event) => {
  event.preventDefault();
  // Handle the error yourself
});

import { router } from "@inertiajs/react";

router.on("networkError", (event) => {
  event.preventDefault();
  // Handle the error yourself
});

import { router } from "@inertiajs/svelte";

router.on("networkError", (event) => {
  event.preventDefault();
  // Handle the error yourself
});

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. Please consult the error handling documentation for more information.

Finish

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 { router } from "@inertiajs/vue3";

router.on("finish", (event) => {
  NProgress.done();
});

import { router } from "@inertiajs/react";

router.on("finish", (event) => {
  NProgress.done();
});

import { router } from "@inertiajs/svelte";

router.on("finish", (event) => {
  NProgress.done();
});

The finish event is not cancelable.

Navigate

The navigate event fires on successful page visits, as well as when navigating through history.

import { router } from "@inertiajs/vue3";

router.on("navigate", (event) => {
  console.log(`Navigated to ${event.detail.page.url}`);
});

import { router } from "@inertiajs/react";

router.on("navigate", (event) => {
  console.log(`Navigated to ${event.detail.page.url}`);
});

import { router } from "@inertiajs/svelte";

router.on("navigate", (event) => {
  console.log(`Navigated to ${event.detail.page.url}`);
});

The navigate event is not cancelable.

Location

v3.6.0+ The location event fires whenever Inertia is about to force a full-page navigation, either because the asset version changed or because the server returned an Inertia::location() redirect. The event detail includes a versionChange boolean so you may tell an automatic asset version change apart from a manual redirect.

import { router } from "@inertiajs/vue3";

router.on("location", (event) => {
  console.log(`Navigating to ${event.detail.url}`);
  console.log(`Triggered by a version change: ${event.detail.versionChange}`);
});

import { router } from "@inertiajs/react";

router.on("location", (event) => {
  console.log(`Navigating to ${event.detail.url}`);
  console.log(`Triggered by a version change: ${event.detail.versionChange}`);
});

import { router } from "@inertiajs/svelte";

router.on("location", (event) => {
  console.log(`Navigating to ${event.detail.url}`);
  console.log(`Triggered by a version change: ${event.detail.versionChange}`);
});

You may cancel the location event to take over the navigation yourself, for example to show a “new version available” banner instead of reloading.

import { router } from "@inertiajs/vue3";

router.on("location", (event) => {
  if (event.detail.versionChange) {
    event.preventDefault();
    showBanner("A new version is available.");
  }
});

import { router } from "@inertiajs/react";

router.on("location", (event) => {
  if (event.detail.versionChange) {
    event.preventDefault();
    showBanner("A new version is available.");
  }
});

import { router } from "@inertiajs/svelte";

router.on("location", (event) => {
  if (event.detail.versionChange) {
    event.preventDefault();
    showBanner("A new version is available.");
  }
});

Prefetching

The prefetching event fires when the router starts prefetching a page.

import { router } from "@inertiajs/vue3";

router.on("prefetching", (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/react";

router.on("prefetching", (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/svelte";

router.on("prefetching", (event) => {
  console.log(`Prefetching ${event.detail.visit.url}`);
});

The prefetching event is not cancelable.

Prefetched

The prefetched event fires when the router has successfully prefetched a page.

import { router } from "@inertiajs/vue3";

router.on("prefetched", (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/react";

router.on("prefetched", (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`);
});

import { router } from "@inertiajs/svelte";

router.on("prefetched", (event) => {
  console.log(`Prefetched ${event.detail.visit.url}`);
});

The prefetched event is not cancelable.

Event Callbacks

In addition to the global events described throughout this page, Inertia also provides a number of event callbacks that fire when manually making Inertia visits.

Getting Started

Installation

Core Concepts

The Basics

Data & Props

Security

Advanced

Registering Listeners

Removing Listeners

One-time Listeners

Cancelling Events

Before

Start

Progress

Success

Flash

Error

HTTP Exception

Network Error

Finish

Navigate

Location

Prefetching

Prefetched

Event Callbacks

​Registering Listeners

​Removing Listeners

​One-time Listeners

​Cancelling Events

​Before

​Start

​Progress

​Success

​Flash

​Error

​HTTP Exception

​Network Error

​Finish

​Navigate

​Location

​Prefetching

​Prefetched

​Event Callbacks

Registering Listeners

Removing Listeners

One-time Listeners

Cancelling Events

Before

Start

Progress

Success

Flash

Error

HTTP Exception

Network Error

Finish

Navigate

Location

Prefetching

Prefetched

Event Callbacks