Partial reloads

When making visits to the same page you are already on, it's not always necessary to re-fetch all of the page's data from the server. In fact, selecting only a subset of the data can be a helpful performance optimization if it's acceptable that some page data becomes stale. Inertia makes this possible via its "partial reload" feature.

As an example, consider a "user index" page that includes a list of users, as well as an option to filter the users by their company. On the first request to the page, both the users and companies props are passed to the page component. However, on subsequent visits to the same page (maybe to filter the users), you can request only the users data from the server without requesting the companies data. Inertia will then automatically merge the partial data returned from the server with the data it already has in memory client-side.

NOTE

Partial reloads only work for visits made to the same page component.

Only certain props

To perform a partial reload, use the only visit option to specify which data the server should return. This option should be an array of keys which correspond to the keys of the props.

import { router } from '@inertiajs/vue3'

router.visit(url, {
  only: ['users'],
})

Except certain props

In addition to the only visit option you can also use the except option to specify which data the server should exclude. This option should also be an array of keys which correspond to the keys of the props.

import { router } from '@inertiajs/vue3'

router.visit(url, {
  except: ['users'],
})

Dot notation

Both the only and except visit options support dot notation to specify nested data, and they can be used together. In the following example, only settings.theme will be rendered, but without its colors property.

import { router } from '@inertiajs/vue3'

router.visit(url, {
  only: ['settings.theme'],
  except: ['setting.theme.colors'],
})

Please remember that, by design, partial reloading filters props before they are evaluated, so it can only target explicitly defined prop keys. Let's say you have this prop:

users: -> { User.all }

Requesting only: ['users.name'] will exclude the entire users prop, since users.name is not available before evaluating the prop.

Requesting except: ['users.name'] will not exclude anything.

Router shorthand

Since partial reloads can only be made to the same page component the user is already on, it almost always makes sense to just use the router.reload() method, which automatically uses the current URL.

import { router } from '@inertiajs/vue3'

router.reload({ only: ['users'] })

Using links

It's also possible to perform partial reloads with Inertia links using the only property.

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

<template>
  <Link href="/users?active=true" :only="['users']">Show active</Link>
</template>

Lazy data evaluation

For partial reloads to be most effective, be sure to also use lazy data evaluation when returning props from your server-side routes or controllers. This can be accomplished by wrapping all optional page data in a lambda.

class UsersController < ApplicationController
  def index
    render inertia: 'Users/Index', props: {
      users: -> { User.all },
      companies: -> { Company.all },
    }
  end
end

When Inertia performs a request, it will determine which data is required and only then will it evaluate the closure. This can significantly increase the performance of pages that contain a lot of optional data.

Additionally, Inertia provides an InertiaRails.optional method to specify that a prop should never be included unless explicitly requested using the only option:

class UsersController < ApplicationController
  def index
    render inertia: 'Users/Index', props: {
      users: InertiaRails.optional { User.all },

      # Also works with a lambda:
      # users: InertiaRails.optional(-> { User.all }),

      # Also works with a simple value,
      # but this way the prop is always evaluated,
      # even if not included:
      # users: InertiaRails.optional(User.all),
    }
  end
end

NOTE

Prior to Inertia.js v2, the method InertiaRails.lazy was used. It is now deprecated and has been replaced by InertiaRails.optional. Please update your code accordingly to ensure compatibility with the latest version.

On the inverse, you can use the InertiaRails.always method to specify that a prop should always be included, even if it has not been explicitly required in a partial reload.

class UsersController < ApplicationController
  def index
    render inertia: 'Users/Index', props: {
      users: InertiaRails.always { User.all },
    }
  end
end

Here's a summary of each approach:

class UsersController < ApplicationController
  def index
    render inertia: 'Users/Index', props: {
      # ALWAYS included on standard visits
      # OPTIONALLY included on partial reloads
      # ALWAYS evaluated
      users: User.all,

      # ALWAYS included on standard visits
      # OPTIONALLY included on partial reloads
      # ONLY evaluated when needed
      users: -> { User.all },

      # NEVER included on standard visits
      # OPTIONALLY included on partial reloads
      # ONLY evaluated when needed
      users: InertiaRails.lazy { User.all },

      # ALWAYS included on standard visits
      # ALWAYS included on partial reloads
      # ALWAYS evaluated
      users: InertiaRails.always(User.all),
    }
  end
end