Refresh Only What Changed: Inertia.js Partial Reloads with only and except

The problem: reloading everything to change one filter

Imagine a project dashboard with a persistent sidebar showing the current user, notification count, and billing plan. The main area lists projects with a search box. Every time the user submits a search, Inertia reloads the page. That means the server re-serializes the user, notifications, and plan even though none of them changed. On a slow connection or a large payload, the user waits for data that never needed to move.

Inertia.js partial reloads let you ask the server to send back only a subset of page props. Instead of replacing the entire page state, the client merges the returned props into the existing ones. This is useful when a single interaction—filtering a list, toggling a preference, updating a counter—should not touch the rest of the page.

What only and except actually do

Inertia supports two mutually exclusive options on client-side router calls: only and except.

• only: ['projects', 'filters'] — the response includes just those props.
• except: ['user', 'notifications'] — the response includes every prop except those listed.

You can use them with Inertia links, forms, and programmatic navigation such as router.get, router.post, or form.put in the React, Vue, and Svelte adapters. A key point that is easy to miss: the server still executes the full controller or route logic. Inertia filters which props are serialized into the JSON response; it does not skip database queries or business logic on the server.

Worked example: search without reloading the sidebar

This example uses the Inertia React adapter. The page receives projects, filters, user, and notifications. When the user submits the search, we want to refresh projects and filters while leaving user and notifications untouched.

import { useForm } from '@inertiajs/react';

export default function ProjectPage({ projects, filters, user, notifications }) {
  const form = useForm({ search: '' });

  const handleSearch = () => {
    form.put(route('projects.update'), {
      preserveForm: true,
      only: ['projects', 'filters'],
    });
  };

  return (
    
      
        
Account
        
{user.name}
        
Notifications: {notifications.count}
      

      
         form.setField('search', e.target.value)}
          onBlur={handleSearch}
        />
        

          {projects.map((project) => (
            
{project.name}
          ))}
        
      
    
  );
}

On the server, the controller still loads user and notifications as usual. Inertia removes them from the JSON payload before sending it back because the request asked for only projects and filters. If you later add a component that reads notifications after this reload, that prop will not be present in the updated response, so you must include it in the only list when it is needed.

Check your adapter version first

Partial reload behavior and option names can differ between Inertia.js v1 and v2, and among framework adapters. Run this read-only command in your project root to confirm which adapter version is installed:

# Run in your project root. No special permissions required.
grep '@inertiajs' package.json

Expected check: the output shows an installed adapter such as @inertiajs/react, @inertiajs/vue3, or @inertiajs/svelte with a version number. Risk: none; this only reads a file.

Verify the reload in DevTools

After deploying the code, confirm the partial reload is working:

1. Open browser DevTools and go to the Network tab.
2. Filter for XHR or fetch requests to your Inertia route.
3. Trigger the search or form action.
4. Inspect the request header X-Inertia-Partial-Data. It should list the props you passed to only or except.
5. Inspect the response JSON. Its top-level keys should match the filtered set, not the full page prop list.
6. Add a temporary console.log in your component to log a prop before and after the reload, and confirm it updates only when expected.

Trade-offs and limitations

• No server savings. Because the full controller runs, partial reloads reduce network payload, not server processing time.
• Missing props. Any prop omitted by an only list is unavailable after the reload. Shared layout data must be explicitly included if components depend on it.
• Adapter differences. Option support and merge semantics vary by Inertia version and adapter, so check your installed version's documentation.

Closing

Use except when most props should stay and only a few should drop out. Use only when you know exactly which props changed and want the smallest possible response. Always verify with the X-Inertia-Partial-Data header and the response body before assuming the client received what you intended.