Inertia partial reloads in Vue

Your filter dropdown re-runs the expensive category query on every click. Your “load more” button replaces the list instead of growing it. Partial reloads fix both: ask Laravel for one prop, defer the slow ones, and append rows on demand.

A normal Inertia visit runs every prop on the page. Partial reloads exist so a filter, a poll, or a “load more” button does not redo the expensive ones. The visit has to target the page you are already on. A link to a different component always loads the full page.

The list those props come from is the CRUD guide. Counted pages versus cursors are pagination. The app is Inertia, a SPA, or Nuxt.

Reload one prop with only and except#

Wrap props you can skip in a closure. Inertia evaluates the closure when that key is needed. A value computed before Inertia::render runs on every visit, including a partial one.

return Inertia::render('posts/Index', [
    'posts' => Post::query()->latest('id')->paginate(10)->withQueryString(),
    'categories' => Category::query()->orderBy('name')->get(['id', 'name']),
]);

return Inertia::render('posts/Index', [
    'posts' => fn () => Post::query()->latest('id')->paginate(10)->withQueryString(),
    'categories' => fn () => Category::query()->orderBy('name')->get(['id', 'name']),
]);

Then ask for the one you need:

<script setup lang="ts">
import { router } from "@inertiajs/vue3";

function refreshPosts() {
  router.reload({ only: ["posts"] });
}
</script>

only: ['posts'] tells Laravel to skip categories. except: ['categories'] is the same idea written the other way. A <Link> can do it without a function.

<Link href="/posts?published=1" :only="['posts']">Published</Link>

Dot keys work for nested props. only: ['auth.notifications'] reloads that nested value and leaves the rest of auth alone.

Defer slow props until after the first paint#

Inertia::defer leaves the prop out of the first response and fetches it immediately after the first paint. The Vue <Deferred> component renders the fallback until the key arrives. #default="{ reloading }" is how you dim the list during a later reload. #rescue renders when you passed rescue: true and the callback threw.

'permissions' => Inertia::defer(fn () => Permission::query()->orderBy('name')->get(), rescue: true),

<script setup lang="ts">
import { Deferred, router } from "@inertiajs/vue3";

defineProps<{
  permissions?: { id: number; name: string }[];
}>();
</script>

<template>
  <Deferred data="permissions" #default="{ reloading }">
    <template #fallback>
      <p>Loading permissions...</p>
    </template>

    <template #rescue="{ reloading }">
      <button
        type="button"
        :disabled="reloading"
        @click="router.reload({ only: ['permissions'] })"
      >
        Retry
      </button>
    </template>

    <ul :class="{ 'opacity-50': reloading }">
      <li v-for="permission in permissions" :key="permission.id">
        {{ permission.name }}
      </li>
    </ul>
  </Deferred>
</template>

once() and WhenVisible#

->once() on a deferred prop is remembered only while later pages still include that prop. A visit that leaves it out forgets the value, and the next page that includes it resolves the callback again. Reload that one prop when you need a fresh value sooner.

Inertia also ships WhenVisible for a deferred prop that should wait until the block scrolls into view. The prop name is the same contract. Use it for a block below the fold, not for the main list.

Load more with Inertia::merge()#

Inertia::merge() appends on a partial reload. A full visit replaces the prop even if you marked it for merging. The documented way to append a paginator’s rows is append('data').

'posts' => Inertia::merge(
    fn () => Post::query()->latest('id')->paginate(10)
)->append('data'),

function more() {
  router.reload({
    only: ["posts"],
    data: { page: props.posts.current_page + 1 },
  });
}

function search(value: string) {
  router.reload({
    only: ["posts"],
    data: { search: value, page: 1 },
    reset: ["posts"], 
  });
}

Previous and Next links that replace the list, instead of appending, stay on the pagination page. simplePaginate is the right object when you do not want a total. Merge is the wrong tool for that footer.

Which tool for which job#

Where this stops#

Live updates from the server are Reverb, not a timer that calls router.reload. A reload still asks Laravel. A broadcast pushes.

Recap#

• Closures make props lazy; only/except pick which ones run on a partial reload.
• Partial reloads only work on the page you are on.
• Inertia::defer() + <Deferred> shows a fallback, then the prop; rescue: true adds a retry slot.
• Inertia::merge() appends on partial reloads only; pass reset when the query changes.

FAQ#

Next steps#

• Paginate a Laravel list in Vue: counted pages, simple pages and cursors.
• Inertia 3.9: background polling: pair usePoll with only.
• Server-render an Inertia app: deferred props and the first HTML.
• Inertia docs: partial reloads

Sources#

• Inertia v3: Partial reloads
• Inertia v3: Deferred props
• Inertia v3: Merging props
• Inertia v3: Load when visible