Responses

Working with InertiaResponse for advanced page rendering.

See also

Official Inertia.js docs: Responses

Basic Usage

For most cases, use the component decorator parameter:

@get("/dashboard", component="Dashboard")
async def dashboard() -> dict:
    return {"stats": {"users": 100}}

InertiaResponse

Use InertiaResponse for more control:

from litestar_vite.inertia import InertiaResponse

@get("/dashboard")
async def dashboard() -> InertiaResponse:
    return InertiaResponse(
        content={"stats": {"users": 100}},
        # Optional parameters
        encrypt_history=True,
        clear_history=False,
    )

InertiaResponse Parameters

Parameter

Type

Description

content

T

Props to pass to the component

template_name

str | None

Override root template name

encrypt_history

bool | None

Enable history encryption for this page

clear_history

bool

Clear encrypted history on navigation

scroll_props

ScrollPropsConfig | None

Pagination config for infinite scroll

prop_filter

PropFilter | None

Server-side prop filtering for partial reloads

context

dict[str, Any] | None

Additional template context

headers

ResponseHeaders | None

Custom response headers

cookies

ResponseCookies | None

Response cookies

Non-Inertia Responses

InertiaResponse automatically handles both Inertia and non-Inertia requests:

  • Inertia request (X-Inertia: true): Returns JSON

  • Non-Inertia request: Returns rendered HTML template

# Works for both browser and Inertia navigation
@get("/dashboard", component="Dashboard")
async def dashboard() -> dict:
    return {"stats": {...}}

Pagination Containers

Return pagination objects directly - they’re automatically unwrapped:

from litestar.pagination import OffsetPagination

@get("/users", component="Users")
async def list_users(offset: int = 0, limit: int = 20) -> OffsetPagination:
    users, total = await User.paginate(offset, limit)
    return OffsetPagination(
        items=users,
        limit=limit,
        offset=offset,
        total=total,
    )

The items are extracted and included in props. Use key opt to customize:

@get("/users", component="Users", key="users")
async def list_users(...) -> OffsetPagination:
    ...  # Props will have "users" instead of "items"

Prop Filtering

Filter which props are sent during partial reloads using only() and except_():

from litestar_vite.inertia import InertiaResponse, only, except_

@get("/users", component="Users")
async def list_users(request: InertiaRequest) -> InertiaResponse:
    return InertiaResponse(
        content={
            "users": User.all(),
            "teams": Team.all(),
            "stats": expensive_stats(),
        },
        # Only send "users" prop during partial reloads
        prop_filter=only("users"),
    )

@get("/dashboard", component="Dashboard")
async def dashboard(request: InertiaRequest) -> InertiaResponse:
    return InertiaResponse(
        content={
            "summary": get_summary(),
            "charts": get_charts(),
            "debug_info": get_debug_info(),
        },
        # Send all props except "debug_info" during partial reloads
        prop_filter=except_("debug_info"),
    )

Note: This is server-side filtering. Clients should use Inertia’s router.reload({ only: [...] }) for client-initiated filtering.

See Also