/litestar-htmx

name: litestar-htmx
description: "Use when working with litestar_htmx, HTMXPlugin, HTMXConfig, HTMXRequest, HTMXTemplate, HXLocation, ReplaceUrl, TriggerEvent, or HX-* headers. Not for client-only HTMX — use litestar-vite."

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 the

`litestar.plugins.htmx` compatibility re-export shim.

• 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: its `on_app_init` hook registers `HTMXRequest` and all ten HTMX response classes in `app_config.signature_types`. Its default `HTMXConfig(set_request_class_globally=True)` sets `HTMXRequest` only when `app_config.request_class is None`.

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 and decoded using the active route handler's `type_decoders`. 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 `trigger_event` is set, `after` must be `"receive"`, `"settle"`, or `"swap"` (leaving `after=None` raises `ImproperlyConfiguredException`). `HTMXTemplate` supports `push_url`, `re_swap`, `re_target`, `trigger_event`, `params`, and `after`; it does not accept `replace_url`.

Response helper signatures

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

| Helper | Constructor | Behavior | | --- | --- | --- | | `HXStopPolling` | `HXStopPolling()` | Returns status `286` (`HTMX_STOP_POLLING`) | | `ClientRedirect` | `ClientRedirect(redirect_to)` | Status `200`; sets URL-quoted `HX-Redirect` and deletes `Location` | | `ClientRefresh` | `ClientRefresh()` | Status `200`; sets `HX-Refresh: true` | | `PushUrl` | `PushUrl(content, push_url, **kwargs)` | Status `200`; sets `HX-Push-Url` | | `ReplaceUrl` | `ReplaceUrl(content, replace_url, **kwargs)` | Status `200`; sets `HX-Replace-Url` | | `Reswap` | `Reswap(content, method, **kwargs)` | Sets `HX-Reswap` | | `Retarget` | `Retarget(content, target, **kwargs)` | Sets `HX-Retarget` | | `TriggerEvent` | `TriggerEvent(content, name, after, params=None, **kwargs)` | Sets `HX-Trigger`, `HX-Trigger-After-Settle`, or `HX-Trigger-After-Swap` | | `HXLocation` | `HXLocation(redirect_to, source=None, event=None, target=None, select=None, swap=None, hx_headers=None, values=None, **kwargs)` | Status `200`; sets JSON in `HX-Location` and deletes `Location` | | `HTMXTemplate` | `HTMXTemplate(push_url=None, re_swap=None, re_target=None, trigger_event=None, params=None, after=None, **kwargs)` | `Template` subclass combining `HX-Push-Url`, `HX-Reswap`, `HX-Retarget`, and