InertiaJS Partial Reloads: How They Work, When to Use Them, and What to Watch For

What partial reloads actually do

InertiaJS lets you ask the server for a subset of page props instead of a full page visit. The component stays mounted, its local refs and focus remain intact, and only the props you listed are merged into the existing page object.

Requesting a partial reload from the frontend

In a Vue (or React) component you call the router helper with an only array:

// resources/js/Pages/Users/Index.vue
import { usePage, router } from '@inertiajs/vue3';

const page = usePage();

function refreshUsers() {
  router.get(route('users.index'), {
    only: ['users']
  });
}

The only key tells Inertia to apply the returned users prop and discard everything else from the response.

Server‑side rendering still sends the full payload

Your Laravel controller does not change:

// app/Http/Controllers/UserController.php
public function index()
{
    return Inertia::render('Users/Index', [
        'users' => User::latest()->paginate(15),
        'teams' => Team::all(),
    ]);
}

When the partial request arrives, Inertia still serializes users and teams. The client receives the complete JSON response but only merges the props listed in only. Bandwidth savings are therefore limited to client‑side processing; the server still does the full rendering work.

Preserving component state

Because the component is not unmounted, any local state (e.g., a ref holding a scroll position, an open dropdown, or a form’s validation errors) survives the reload. This is the primary reason to prefer partial reloads over full visits when you only need to refresh a list or a computed value.

Using only with useForm

Inertia’s useForm helper accepts an only option after a successful submission:

const form = useForm({
  name: '',
  email: '',
});

form.post(route('users.store'), {
  only: ['users'],
  onSuccess: () => form.reset(),
});

After the POST succeeds, the users prop is refreshed while the form component stays mounted, so the user sees the new record without a full page flash.

Common pitfalls

• Assuming server cost drops. The server still builds the entire view and all props. If the omitted props are expensive to compute, you must move that logic out of the shared endpoint or create a dedicated lightweight endpoint.
• Stale data for excluded props. Props not listed in only keep their previous values. If teams changes on the server, the UI will show the old list until a full visit occurs.
• Interdependent props updated separately. Refreshing users while teams stays stale can produce mismatched UI (e.g., a user assigned to a team that no longer appears in the team list).
• Scroll and navigation guards behave differently. Full visits reset scroll position and run beforeEach guards; partial reloads preserve scroll and may skip some guards depending on the adapter (Vue, React, Svelte). Test the specific behavior in your stack.

Verifying the behavior in the browser

1. Open the Network panel (DevTools → Network). Filter for “Fetch/XHR”.
2. Trigger the partial reload (click the button that calls refreshUsers()).
3. Inspect the response JSON: you should see both users and teams keys present.
4. Confirm the UI updates only the user list. The team dropdown, if any, should retain its previous items.
5. Add a temporary console.log('setup') (or useEffect in React) inside the component’s setup function. Trigger the partial reload again; the log should not appear, proving the component did not re‑mount.
6. Change a team name in the database, then fire the partial reload. The displayed team name should stay unchanged until you perform a full router.visit() or a standard link navigation.

When to choose a partial reload

Use partial reloads when:

• You need to refresh a single collection (e.g., a paginated table) after a create, update, or delete action.
• Preserving form focus, scroll position, or local component state improves UX.
• The omitted props are cheap to compute or rarely change.

Avoid them when:

• The excluded props are expensive and you want to reduce server load.
• Multiple related props must stay consistent; a full visit guarantees atomicity.
• You rely on navigation guards or scroll reset that only run on full visits.

Quick checklist before shipping

• ✅ Verify the only array matches the exact prop keys returned by the controller.
• ✅ Confirm the component’s setup/useEffect does not re‑run on partial reload.
• ✅ Test stale‑prop scenarios by mutating excluded data server‑side.
• ✅ Ensure scroll and focus behavior matches product expectations.