/litestar-htmx

name: litestar-htmx
description: "Auto-activate for litestar_htmx, HTMXPlugin, HTMXConfig, HTMXRequest, HTMXTemplate, HXLocation, ReplaceUrl, TriggerEvent, HX-* headers, or Litestar partial HTML. Not for generic browser-side HTMX or Litestar Vite JSON templating — those are client concerns."

litestar-htmx

`litestar-htmx` is the standalone Litestar integration for HTMX. Version 0.5.0 ships the `litestar_htmx` import package with request helpers, an optional application plugin, template responses, and typed HTMX response-header helpers.

Code Style Rules

• Import the integration from `litestar_htmx`, never

`litestar.plugins.htmx`; Litestar no longer owns this package's import surface.

• Use `HTMXRequest` when handlers inspect HTMX request headers.
• Return template fragments from HTMX endpoints; keep full-page routes and

fragment routes distinct.

• Use the response classes for `HX-*` headers; do not assemble those headers

by hand.

• Keep browser-side HTMX extensions separate from this server package.

Quick Reference

Configure the plugin

from litestar import Litestar
from litestar_htmx import HTMXPlugin

app = Litestar(
    route_handlers=[...],
    plugins=[HTMXPlugin()],
)

`HTMXPlugin()` is the convenience path: it registers the package's request and response types. Its default `HTMXConfig(set_request_class_globally=True)` sets `HTMXRequest` only when the application does not already have a request class.

Preserve an existing custom request class by extending `HTMXRequest`:

from litestar_htmx import HTMXRequest


class ApplicationRequest(HTMXRequest):
    """Application request with HTMX helpers."""

If the application only needs response helpers, use `HTMXConfig(set_request_class_globally=False)`. To inspect `request.htmx`, configure `HTMXRequest` (or a subclass) as the application request class. The plugin never replaces a request class already present in `AppConfig`.

The plugin itself is optional. Applications can instead set `request_class=HTMXRequest` directly and return the response subclasses without registering `HTMXPlugin`.

Inspect request headers

`request.htmx` is always an `HTMXDetails` object. Its truth value is `True` only when `HX-Request` is exactly `"true"`.

from litestar import get
from litestar.response import Template
from litestar_htmx import HTMXRequest


@get("/items")
async def list_items(request: HTMXRequest) -> Template:
    template_name = "partials/item-list.html" if request.htmx else "pages/items.html"
    return Template(template_name=template_name, context={"items": []})

Available request helpers:

| Property | Source | Result | | --- | --- | --- | | `bool(request.htmx)` | `HX-Request` | Whether this is an HTMX request | | `request.htmx.boosted` | `HX-Boosted` | `bool` | | `request.htmx.current_url` | `HX-Current-URL` | `str \| None` | | `request.htmx.current_url_abs_path` | `HX-Current-URL` | Same-origin path, query, and fragment, or `None` | | `request.htmx.history_restore_request` | `HX-History-Restore-Request` | `bool` | | `request.htmx.prompt` | `HX-Prompt` | `str \| None` | | `request.htmx.target` | `HX-Target` | `str \| None` | | `request.htmx.trigger` | `HX-Trigger` | `str \| None` | | `request.htmx.trigger_name` | `HX-Trigger-Name` | `str \| None` | | `request.htmx.triggering_event` | `Triggering-Event` | Decoded JSON value, or `None` |

`triggering_event` is supplied by HTMX's `event-header` extension. Malformed JSON resolves to `None`. Headers accompanied by `<Header>-URI-AutoEncoded: true` are URL-decoded before use.

Return template fragments with HTMX headers

`HTMXTemplate` extends Litestar's `Template`. Annotate handlers with `Template`, then pass normal `Template` arguments plus HTMX-specific options:

from litestar import get
from litestar.response import Template
from litestar_htmx import HTMXTemplate


@get("/items/fragment")
async def item_list() -> Template:
    return HTMXTemplate(
        template_name="partials/item-list.html",
        context={"items": []},
        push_url=False,
        re_swap="outerHTML",
        re_target="#item-list",
        trigger_event="itemsLoaded",
        params={"count": 0},
        after="receive",
    )

`trigger_event`, `params`, and `after` form one event declaration. When triggering an event, set `after` to `"receive"`, `"settle"`, or `"swap"`.

Response helper signatures

All helpers are exported from `litestar_htmx` and `litestar_htmx.response`.

| Helper | Constructor | Behavior | | --- | --- | --- | | `HXStopPolling` | `HXStopPolling()` | Returns status `286` | | `ClientRedirect` | `ClientRedirect(redirect_to)` | Sets `HX-Redirect`; no `Location` header | | `ClientRefresh` | `ClientRefresh()` | Sets `HX-Refresh: true` | | `PushUrl` | `PushUrl(content, push_url, **response_kwargs)` | Sets `HX-Push-Url` | | `ReplaceUrl` | `ReplaceUrl(content, replace_url, **response_kwargs)` | Sets `HX-Replace-Url` | | `Reswap` | `Reswap(content, method, **response_kwargs)` | Sets `HX-Reswap` | | `Retarget` | `Retarget(content, target, **response_kwargs)` | Sets `HX-Retarget` | | `TriggerEvent` | `TriggerEvent(content, name, after, params=None, **response_kwargs)` | Sets the selected `HX-Trigger*` header | | `HXLocation` | `HXLocation(redirect_to, source=None, event=None, target=None, select=None, swap=None, hx_headers=None, values=None, **response_kwargs)` | Sets JSON in `HX-Location` |

`push_url=False` and `replace_url=False` emit `"false"` to prevent the corresponding history update.

Soft navigation with `HXLocation`

Use `HXLocation` for an HTMX navigation request without a full-page reload. `select` chooses a fragment from the fetched response before it is swapped:

from litestar import post
from litestar_htmx import HXLocation


@post("/items")
async def create_item() -> HXLocation:
    return HXLocation(
        redirect_to="/items",
        source="#create-item",
        event="sub