litestar-org/litestar-skills/litestar-htmx

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:

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.

Pass a URL str to push_url or replace_url to update history, or False (or "False") to emit "false" and prevent the history update. Do not pass True: any bool value is serialized as "false".

Exported types and header enum

litestar_htmx exports the typing definitions (from litestar_htmx.types) and the HTMXHeaders enum (from litestar_htmx.request and litestar_htmx._utils) used across request and response helpers:

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="submit",
        target="#content",
        select="#item-list",
        swap="innerHTML",
        hx_headers={"X-View": "compact"},
        values={"created": "true"},
    )

The response uses status 200, carries HX-Location, and removes the ordinary Location header.

Trigger an event while returning content

TriggerEvent requires the response content, event name, and after phase:

from litestar import post
from litestar_htmx import TriggerEvent
@post("/items")
async def create_item() -> TriggerEvent[str]:
    return TriggerEvent(
        content="<li>Saved</li>",
        name="itemCreated",
        after="swap",
        params={"id": 42},
        media_type="text/html",
    )

Prefer HTMXTemplate when the content is HTML assembled from application data.

Litestar Vite is a separate client layer

The standalone package owns Python request parsing and response headers:

from litestar_htmx import HTMXPlugin, HTMXRequest, HTMXTemplate

Litestar Vite's hx-ext="litestar" JSON templating and CSRF integration come from the separate litestar-vite-plugin/helpers JavaScript export. They are not installed, registered, or enabled by HTMXPlugin(). Use them only when the project already uses Litestar Vite and needs client-side JSON swaps. See Litestar Vite Integration.

<workflow>

Workflow

1. Check the project's installed litestar-htmx version and existing request

class.

1. Register HTMXPlugin() or set request_class=HTMXRequest directly. Extend

HTMXRequest when the application needs custom request behavior.

1. Separate full-page endpoints from fragment endpoints. Branch on

request.htmx only when one URL intentionally supports both.

1. Render fragments with Template or HTMXTemplate.
2. Select the narrow response helper matching the required HTMX header.
3. Configure CSRF protection for every state-changing HTMX request.
4. Test the response body, status, and exact HX-* header.
5. Add Litestar Vite's client extension only for bundled assets, CSRF header

injection, or JSON templating.

</workflow>

<guardrails>

Guardrails

• Use `litestar_htmx`, never `litestar.plugins.htmx`. The 0.5.0 package is a

standalone distribution; litestar.plugins.htmx is only a compatibility re-export shim.

• Pass every required response-helper argument. TriggerEvent requires

content, name, and a non-null after ("receive", "settle", or "swap"); PushUrl, ReplaceUrl, Reswap, and Retarget also require content.

• Pass a URL `str` or `False` for `push_url` and `replace_url`. Any boolean

value (including True) is serialized as "false".

• Use `select=` on `HXLocation` to choose returned content. Do not confuse

it with target=, which chooses the receiving element.

• Do not assume `HTMXPlugin` overrides an existing request class. It

preserves a non-null AppConfig.request_class.

• Do not treat `request.htmx` as an optional object. Test its truth value to

identify HTMX requests.

• Do not send a normal redirect for `HXLocation` or `ClientRedirect`. These

helpers return 200 with HTMX response headers and delete Location.

• Do not attribute `hx-ext="litestar"` to `litestar-htmx`. That browser

extension ships with Litestar Vite's npm package.

• Do not return unsanitized, concatenated HTML. Render templates so escaping

and template caching remain intact.

</guardrails>

<validation>

Validation Checkpoint