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 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": []})