Optimizing Inertia.js Payloads with Partial Reloads and Lazy Props

The Payload Bloat Problem

In a standard Inertia.js application, every server-side visit returns the full set of props defined for that page. As a page grows—adding complex filters, large data tables, or heavy metadata—the server must query all this data on every request, and the browser must download the entire JSON payload, even if only a small section of the UI is updating.

The solution is Partial Reloads. This feature allows the client to request only a specific subset of props, reducing server processing time and network latency while preserving the current client-side state.

Choosing Your Loading Strategy

Deciding between a full visit and a partial reload depends on whether the user is navigating to a new context or updating data within the current view.

Feature	Full Visit (Default)	Partial Reload (only)
Data Transfer	All defined props	Specified keys only
Server Load	Executes all queries	Executes only requested queries
Client State	Resets component state	Preserves component state
Use Case	Initial page load, navigation	Filtering, pagination, polling

The Role of Lazy Props

Using the only property on the client is only half the battle. If your server-side controller simply returns an array of data, the server still performs the database queries before Inertia filters the response. To truly optimize, you must use Lazy Props.

Lazy props are defined as closures (anonymous functions). The server-side adapter (such as the Laravel adapter) will only execute these closures if the requested prop is missing from the only list or if it is explicitly requested. If a request is a partial reload and the lazy prop is not requested, the closure is never called, and the database query is skipped entirely.

Implementation Example (Laravel/PHP)

In this scenario, we have a user profile page. The basic user info is needed immediately, but the activity_log is heavy and only needed when the user clicks a "View Activity" tab.

// In the Controller
return Inertia::render('UserProfile', [ 
    'user' => $user, // Standard prop: always sent
    'activity_log' => Inertia::lazy(fn () => $user->activityLogs()->get()), // Lazy prop
]);

Triggering the Reload (Vue/React)

To fetch the activity log without refreshing the entire page or re-fetching the user object, use the only option in the visit helper.

// Vue.js example
import { router } from '@inertiajs/vue3'

function loadActivity() {
  router.reload({
    only: ['activity_log'],
  })
}

Technical Constraints and Risks

• Closure Execution: Lazy props are executed normally during the initial page load. They only provide optimization during subsequent router.reload or router.visit calls that specify only.
• State Fragmentation: If you rely exclusively on partial reloads for critical data, ensure that the client-side state remains synchronized. If a prop is updated on the server but not requested in a partial reload, the UI may display stale data.
• Adapter Support: This behavior requires a server-side adapter that supports closure-based prop resolution. Ensure you are using a current version of the Inertia server-side library.

Verification and Diagnostics

To confirm that partial reloads are functioning and that lazy props are not executing unnecessarily, perform the following checks:

1. Network Inspection: Open the Browser Developer Tools > Network tab. Trigger a partial reload. Inspect the XHR response; the JSON body should only contain the keys specified in the only array and the standard Inertia metadata.
2. Server-Side Logging: Place a log statement inside the lazy closure: Inertia::lazy(fn () => { Log::info('Query executed'); return $data; }). Trigger a full visit (log should appear) and then a partial reload for a different prop (log should not appear).
3. Payload Comparison: Compare the Content-Length of a full page response versus a partial reload response to quantify the bandwidth savings.