Prefetching

Inertia supports prefetching data for pages that are likely to be visited next. This can be useful for improving the perceived performance of your app by allowing the data to be fetched in the background while the user is still interacting with the current page.

Link prefetching

To prefetch data for a page, you can use the prefetch method on the Inertia link component. By default, Inertia will prefetch the data for the page when the user hovers over the link after more than 75ms.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch>Users</Link>
</template>

By default, data is cached for 30 seconds before being evicted. You can customize this behavior by passing a cacheFor prop to the Link component.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch cache-for="1m">Users</Link>
  <Link href="/users" prefetch cache-for="10s">Users</Link>
  <Link href="/users" prefetch :cache-for="5000">Users</Link>
</template>

You can also start prefetching on mousedown by passing the click value to the prefetch prop.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch="click">Users</Link>
</template>

If you're confident that the user will visit a page next, you can prefetch the data on mount as well.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch="mount">Users</Link>
</template>

You can also combine strategies by passing an array of values to the prefetch prop.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" :prefetch="['mount', 'hover']">Users</Link>
</template>

Programmatic prefetching

You can also prefetch data programmatically using router.prefetch. The signature is identical to router.visit with the exception of a third argument that allows you to specify prefetch options.

When the cacheFor option is not specified, it defaults to 30 seconds.

router.prefetch('/users', { method: 'get', data: { page: 2 } })

router.prefetch(
  '/users',
  { method: 'get', data: { page: 2 } },
  { cacheFor: '1m' },
)

Inertia also provides a usePrefetch hook that allows you to track the prefetch state for the current page. It returns information about whether the page is currently prefetching, has been prefetched, when it was last updated, and a flush method that flushes the cache for the current page only.

import { usePrefetch } from '@inertiajs/vue3'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch()

You can also pass visit options when you need to differentiate between different request configurations for the same URL.

import { usePrefetch } from '@inertiajs/vue3'

const { lastUpdatedAt, isPrefetching, isPrefetched, flush } = usePrefetch({
  headers: { 'X-Custom-Header': 'value' },
})

Cache tags

Available since:@inertiajs/core:2.1.2

Cache tags allow you to group related prefetched data and invalidate it all at once when specific events occur.

To tag cached data, pass a cacheTags prop to your Link component.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch cache-tags="users">Users</Link>
  <Link href="/dashboard" prefetch :cache-tags="['dashboard', 'stats']">
    Dashboard
  </Link>
</template>

When prefetching programmatically, pass cacheTags in the third argument to router.prefetch.

router.prefetch('/users', {}, { cacheTags: 'users' })
router.prefetch('/dashboard', {}, { cacheTags: ['dashboard', 'stats'] })

Cache invalidation

You can manually flush the prefetch cache by calling router.flushAll to remove all cached data, or router.flush to remove cache for a specific page.

// Flush all prefetch cache
router.flushAll()

// Flush cache for a specific page
router.flush('/users', { method: 'get', data: { page: 2 } })

// Using the usePrefetch hook
const { flush } = usePrefetch()

flush() // Flush cache for the current page

For more granular control, you can flush cached data by their tags using router.flushByCacheTags. This removes any cached response that contains any of the specified tags.

// Flush all responses tagged with 'users'
router.flushByCacheTags('users')

// Flush all responses tagged with 'dashboard' OR 'stats'
router.flushByCacheTags(['dashboard', 'stats'])

Invalidate on requests

Available since:@inertiajs/core:2.1.2

To automatically invalidate caches when making requests, pass an invalidateCacheTags prop to the Form component. The specified tags will be flushed when the form submission succeeds.

<script setup>
import { Form } from '@inertiajs/vue3'
</script>

<template>
  <Form
    action="/users"
    method="post"
    :invalidate-cache-tags="['users', 'dashboard']"
  >
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
  </Form>
</template>

With the useForm helper, you can include invalidateCacheTags in the visit options.

import { useForm } from '@inertiajs/vue3' const form = useForm({ name: '',
email: '', }) const submit = () => { form.post('/users', { invalidateCacheTags:
['users', 'dashboard'] }) }

You can also invalidate cache tags with programmatic visits by including invalidateCacheTags in the options.

router.delete(
  `/users/${userId}`,
  {},
  {
    invalidateCacheTags: ['users', 'dashboard'],
  },
)

router.post('/posts', postData, {
  invalidateCacheTags: ['posts', 'recent-posts'],
})

Stale while revalidate

By default, Inertia will fetch a fresh copy of the data when the user visits the page if the cached data is older than the cache duration. You can customize this behavior by passing a tuple to the cacheFor prop.

The first value in the array represents the number of seconds the cache is considered fresh, while the second value defines how long it can be served as stale data before fetching data from the server is necessary.

<script setup>
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <Link href="/users" prefetch :cacheFor="['30s', '1m']">Users</Link>
</template>

How it works

If a request is made within the fresh period (before the first value), the cache is returned immediately without making a request to the server.

If a request is made during the stale period (between the two values), the stale value is served to the user, and a request is made in the background to refresh the cached value. Once the value is returned, the data is merged into the page so the user has the most recent data.

If a request is made after the second value, the cache is considered expired, and the value is fetched from the sever as a regular request.