Partial Reloads

Optimize performance by reloading only specific props.

See also

Official Inertia.js docs: Partial Reloads

What Are Partial Reloads?

Partial reloads let you request only specific props instead of the entire page data. This reduces payload size and server processing.

Lazy Props

Use lazy() to mark props that should only load during partial reloads:

from litestar_vite.inertia import lazy

@get("/dashboard", component="Dashboard")
async def dashboard() -> dict:
    return {
        "stats": get_stats(),                    # Always included
        "notifications": lazy("notifications", get_notifications),  # Partial only
        "activity": lazy("activity", get_activity_feed),            # Partial only
    }

Lazy props are excluded from the initial page load and only sent when explicitly requested via partial reload.

Static vs Callable Lazy Props

Static value - computed eagerly, sent lazily:

# Value computed now, but only sent during partial reload
lazy("count", len(expensive_query()))

Callable - computed and sent lazily:

# Function only called during partial reload
lazy("count", lambda: len(expensive_query()))
lazy("data", expensive_async_function)  # Async works too

Warning

Avoid the “False Lazy” pitfall:

# WRONG - function called immediately!
lazy("data", get_expensive_data())

# CORRECT - function reference passed
lazy("data", get_expensive_data)

Frontend Partial Reloads

Request specific props from the client:

import { router } from "@inertiajs/react";

// Reload only specific props
router.reload({ only: ["notifications"] });

// Exclude specific props
router.reload({ except: ["stats"] });

import { router } from "@inertiajs/vue3";

router.reload({ only: ["notifications"] });
router.reload({ except: ["stats"] });

Prop Filtering Helpers

Use only() and except_() for server-side filtering:

from litestar_vite.inertia import only, except_

# Include only specific props
filter_users = only("users", "pagination")

# Exclude specific props
filter_no_debug = except_("debug_info", "internal_stats")

# Check if a key should be included
if filter_users.should_include("users"):  # True
    pass
if filter_users.should_include("settings"):  # False
    pass

Protocol Headers

The v2 protocol uses these headers for partial reloads:

Header

Description

X-Inertia-Partial-Data

Comma-separated list of props to include (e.g., users,teams)

X-Inertia-Partial-Except

Comma-separated list of props to exclude (takes precedence over Partial-Data)

X-Inertia-Reset

Comma-separated list of props to reset/remove from shared state

When X-Inertia-Partial-Except is present, it takes precedence over X-Inertia-Partial-Data. This matches the v2 protocol behavior where exclusion is stronger than inclusion.

Reset Props

The X-Inertia-Reset header removes specified props from the shared state:

// Client-side: reset specific props during partial reload
router.reload({
  only: ["users"],
  reset: ["flash", "errors"]  // Clear flash and errors
})

On the backend, reset props are removed from shared_props before building the page response. This is useful for clearing one-time data like flash messages or validation errors.

Example Use Case

Dashboard with heavy charts data:

@get("/dashboard", component="Dashboard")
async def dashboard() -> dict:
    return {
        "user": get_current_user(),              # Always needed
        "summary": get_summary_stats(),          # Always needed
        "charts": lazy("charts", get_chart_data),  # Load on demand
        "activity": lazy("activity", get_activity),  # Load on demand
    }

Frontend:

// Initial load: only user and summary
// Click "Load Charts" button:
router.reload({ only: ["charts"] });

See Also