Inertia.js Reference¶

Create a deferred prop with optional grouping (v2 feature).

Deferred props are loaded lazily after the initial page render. Props in the same group are fetched together in a single request.

Parameters:

Returns:

defer("permissions", lambda: Permission.all())

defer("teams", lambda: Team.all(), group="attributes")
defer("projects", lambda: Project.all(), group="attributes")

defer("stats", lambda: compute_expensive_stats()).once()

Create a prop that resolves once and is cached client-side (v2.2.20+ feature).

Once props are included in the initial page load and resolved immediately. After resolution, the client caches the value and won't request it again on subsequent page visits, unless explicitly requested via partial reload.

This is useful for: - Expensive computations that rarely change - User preferences or settings - Feature flags - Static configuration

Unlike lazy props, once props ARE included in initial loads. The "once" behavior tells the client to cache the result.

Parameters:

Returns:

from litestar_vite.inertia import once, InertiaResponse

@get("/dashboard", component="Dashboard")
async def dashboard() -> InertiaResponse:
    return InertiaResponse({
        "user": current_user,
        "settings": once("settings", lambda: Settings.for_user(user_id)),
        "feature_flags": once("feature_flags", get_feature_flags()),
    })

Create a prop only included when explicitly requested (v2 feature).

Optional props are NEVER included in initial page loads or standard partial reloads. They're only sent when the client explicitly requests them via only: ['prop_name'] in a partial reload.

This is designed for use with Inertia's WhenVisible component, which triggers a partial reload requesting specific props when an element becomes visible in the viewport.

The callback is only evaluated when requested, providing both bandwidth and CPU optimization.

Parameters:

Returns:

from litestar.params import FromPath
from litestar_vite.inertia import optional, InertiaResponse

@get("/posts/{post_id}", component="Posts/Show")
async def show_post(post_id: FromPath[int]) -> InertiaResponse:
    post = await Post.get(post_id)
    return InertiaResponse({
        "post": post,
        "comments": optional("comments", lambda: Comment.for_post(post_id)),
        "related_posts": optional("related_posts", lambda: Post.related(post_id)),
    })

<WhenVisible data="comments" :params="{ only: ['comments'] }">
    <template #fallback>
        <LoadingSpinner />
    </template>
    <CommentList :comments="comments" />
</WhenVisible>

Create a lazy prop only included during partial reloads.

Lazy props are excluded from the initial page load and only sent when explicitly requested via partial reload (X-Inertia-Partial-Data header). This optimizes initial page load by deferring non-critical data.

There are two use cases for lazy():

1. Static Value (bandwidth optimization): The value is computed eagerly but only sent during partial reloads. Use when the value is cheap to compute but you want to reduce initial payload.

>>> lazy("user_count", len(users))

2. Callable (bandwidth + CPU optimization): The callable is only invoked during partial reloads. Use when the value is expensive to compute.

>>> lazy("permissions", lambda: Permission.all())

Parameters:

Returns:

Create a prop always included, even during partial reloads (v2 feature).

Always props bypass partial reload filtering entirely. They're included in every response regardless of what keys the client requests.

Use for critical data that must always be present: - Authentication state - Permission flags - Feature toggles - Error states

Parameters:

Returns:

from litestar_vite.inertia import always, lazy, InertiaResponse

@get("/dashboard", component="Dashboard")
async def dashboard(request: Request) -> InertiaResponse:
    return InertiaResponse({
        "auth": always("auth", {"user": request.user, "can": permissions}),
        "analytics": lazy("analytics", get_analytics),
        "reports": lazy("reports", get_reports),
    })

Create a merge prop for combining data during partial reloads (v2 feature).

Merge props allow new data to be combined with existing props rather than replacing them entirely. This is useful for infinite scroll, load more buttons, and similar patterns.

Note: Prop merging only works during partial reloads. Full page visits will always replace props entirely.

Parameters:

Returns:

merge("posts", new_posts)
merge("messages", new_messages, strategy="prepend")
merge("user_data", updates, strategy="deep")
merge("posts", updated_posts, match_on="id")

Create scroll props configuration for infinite scroll (v2 feature).

Scroll props allow Inertia to manage pagination state for infinite scroll patterns, providing next/previous page information to the client.

Parameters:

Returns:

from litestar.params import FromQuery
from litestar_vite.inertia import scroll_props, InertiaResponse

@get("/posts", component="Posts")
async def list_posts(page: FromQuery[int] = 1) -> InertiaResponse:
    posts = await Post.paginate(page=page, per_page=20)
    return InertiaResponse(
        {"posts": merge("posts", posts.items)},
        scroll_props=scroll_props(
            current_page=page,
            previous_page=page - 1 if page > 1 else None,
            next_page=page + 1 if posts.has_more else None,
        ),
    )

Create a filter that only includes the specified prop keys.

Use this to explicitly limit which props are sent during partial reloads. Only the specified props will be included in the response.

Parameters:

Returns:

from litestar_vite.inertia import only, InertiaResponse

@get("/users", component="Users")
async def list_users(
    request: InertiaRequest,
    user_service: UserService,
) -> InertiaResponse:
    return InertiaResponse(
        {
            "users": user_service.list(),
            "teams": team_service.list(),
            "stats": stats_service.get(),
        },
        prop_filter=only("users"),
    )

Create a filter that excludes the specified prop keys.

Use this to explicitly exclude certain props during partial reloads. All props except the specified ones will be included in the response.

Parameters:

Returns:

from litestar_vite.inertia import except_, InertiaResponse

@get("/users", component="Users")
async def list_users(
    request: InertiaRequest,
    user_service: UserService,
) -> InertiaResponse:
    return InertiaResponse(
        {
            "users": user_service.list(),
            "teams": team_service.list(),
            "stats": expensive_stats(),
        },
        prop_filter=except_("stats"),
    )

Extract deferred props metadata for the Inertia v2 protocol.

This extracts all DeferredProp instances from the props dict and groups them by their group name, returning a dict mapping group -> list of prop keys.

Note: DeferredProp instances with is_once=True are excluded from the result because once props should not be re-fetched after initial resolution.

Parameters:

Returns:

props = {
    "users": [...],
    "teams": defer("teams", get_teams, group="attributes"),
    "projects": defer("projects", get_projects, group="attributes"),
    "permissions": defer("permissions", get_permissions),
}
result = extract_deferred_props(props)

Extract merge props metadata for the Inertia v2 protocol.

This extracts all MergeProp instances from the props dict and categorizes them by their merge strategy, returning the appropriate lists for the page response.

Parameters:

Returns:

props = {
    "users": [...],
    "posts": merge("posts", new_posts),
    "messages": merge("messages", new_msgs, strategy="prepend"),
    "data": merge("data", updates, strategy="deep"),
    "items": merge("items", items, match_on="id"),
}
merge_props, prepend_props, deep_merge_props, match_props_on = extract_merge_props(props)

Extract once props for the Inertia v2.2.20+ protocol.

Once props are cached client-side after first resolution. This function extracts all OnceProp instances and DeferredProp instances with is_once=True.

Parameters:

Returns:

props = {
    "user": current_user,
    "settings": once("settings", get_settings),
    "stats": defer("stats", get_stats).once(),
}
result = extract_once_props(props)

Check if value should be rendered based on partial reload filtering.

For v2 protocol, partial_except takes precedence over partial_data. When a key is provided, filtering applies to all props (not just lazy props).

Prop types have different behaviors: - AlwaysProp: Always included, bypasses all filtering - OptionalProp: Only included when explicitly requested via partial_data - LazyProp (StaticProp/DeferredProp): Excluded from initial load, included on partial reload - OnceProp: Included in initial load, cached client-side - Regular values: Follow standard partial reload filtering

Parameters:

Returns:

Stage a shared value for the current Inertia response.

Shared values are included in the props of every Inertia response for the current request. This is useful for data that should be available to all components (e.g., authenticated user, permissions, settings). Top-level special props remain raw in request scope and are materialized lazily in the handler frame only when the response includes them. Redirect responses persist supported synchronous values when the request exposes a session transport. Async special props remain available to the current response but cannot cross a redirect.

Parameters:

Returns:

Return shared session props for a request.

For v2 protocol, partial_except takes precedence over partial_data.

Parameters:

Returns:

Stage a flash message for the current Inertia response.

Flash messages are consumed into the top-level flash page field. Redirect responses persist them when the request exposes a session transport.

This function works without requiring Litestar's FlashPlugin or any Jinja2 template configuration, making it ideal for SPA-only Inertia applications.

Parameters:

Returns:

from litestar_vite.inertia import flash

@post("/create")
async def create_item(request: Request) -> InertiaResponse:
    flash(request, "Item created successfully!", "success")
    return InertiaResponse(...)

Stage an error message for the current Inertia response.

Error messages are included in the errors prop of Inertia responses, typically used for form validation errors. The key usually corresponds to a form field name.

Parameters:

Returns:

Mark that the next response should clear client history encryption keys.

This function stages a request-local flag consumed by the current InertiaResponse. Redirect responses persist the flag when the request exposes a session transport.

This should typically be called during logout to ensure sensitive data cannot be recovered from browser history after a user logs out.

Parameters:

from litestar_vite.inertia import clear_history

@post("/logout")
async def logout(request: Request) -> InertiaRedirect:
    request.session.clear()
    clear_history(request)
    return InertiaRedirect(request, redirect_to="/login")

Decorator to enable Precognition on a route handler.

When a Precognition request passes DTO validation, this decorator returns a 204 No Content response instead of executing the handler body. This prevents side effects (database writes, emails, etc.) during validation.

Parameters:

Returns:

from litestar import post
from litestar_vite.inertia import precognition, InertiaRedirect

@post("/users")
@precognition
async def create_user(data: UserDTO) -> InertiaRedirect:
    # This only runs for actual form submissions
    # Precognition validation requests return 204 automatically
    user = await User.create(**data.dict())
    return InertiaRedirect(request, f"/users/{user.id}")

Create an exception handler for ValidationException that supports Precognition.

This handler checks if the request is a Precognition request and returns errors in Laravel's format. For non-Precognition requests, it either uses the fallback handler or returns Litestar's default format.

Parameters:

Returns:

Normalize Litestar validation errors to Laravel format.

Laravel's Precognition protocol expects errors in this format:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password must be at least 8 characters."]
    }
}

Parameters:

Returns:

Create the inertia exception response.

This function handles exceptions for Inertia-enabled routes, returning appropriate responses based on the exception type and status code.

Parameters:

Returns:

Handler for all exceptions subclassed from HTTPException.

Inertia detection:

• For InertiaRequest instances, uses the request's derived flags (route component + headers).
• For plain Request instances (e.g., before routing/when middleware didn't run), falls back to checking the X-Inertia header.

Parameters:

Returns: