{"id":"af64b697-b2cb-4ae1-a060-61b9c427937c","shortId":"4uGXLS","kind":"skill","title":"litestar-htmx","tagline":"Auto-activate for litestar_htmx imports, HTMXPlugin, HTMXRequest, HTMXTemplate, TriggerEvent, PushUrl, HXLocation, hx-* attributes in Litestar templates, or partial HTML responses. Use when building HTMX-powered Litestar handlers, templates, and server-triggered client events. No","description":"# litestar-htmx\n\nLitestar has first-party HTMX support in `litestar_htmx`. It exposes `HTMXPlugin`, `HTMXRequest` (request-side helpers), `HTMXTemplate` (template response with HTMX headers), and HTMX-specific response objects (`TriggerEvent`, `Reswap`, `Retarget`, `PushUrl`, `HXLocation`, `ClientRedirect`, `ClientRefresh`).\n\nThis skill is **Litestar-specific**. For generic HTMX `hx-*` attributes and patterns that aren't Litestar-bound, refer directly to .\n\n## Code Style Rules\n\n- PEP 604 unions: `T | None`, never `Optional[T]`\n- Consumer Litestar app modules MAY use `from __future__ import annotations`\n- Async all I/O — handlers are `async def`\n- Return partial HTML, not full pages, from HTMX-targeted endpoints\n- Use Jinja2 (or Mako) templates for partials; do not string-concat HTML\n\n## Quick Reference\n\n### HTMXRequest\n\n`HTMXRequest` is a `Request` subclass with HTMX-aware properties:\n\n```python\nfrom litestar import get\nfrom litestar_htmx import HTMXRequest\n\n@get(\"/items\")\nasync def list_items(request: HTMXRequest) -> ...:\n if request.htmx: # True if HX-Request header present\n ... # return partial\n else:\n ... # full page\n\n # Other helpers\n request.htmx.target # HX-Target header (str | None)\n request.htmx.trigger # HX-Trigger header\n request.htmx.trigger_name # HX-Trigger-Name header\n request.htmx.boosted # HX-Boosted (bool)\n request.htmx.current_url # HX-Current-URL\n request.htmx.history_restore_request\n request.htmx.prompt # HX-Prompt (user input from hx-prompt)\n```\n\nWire it into the app:\n\n```python\nfrom litestar import Litestar\nfrom litestar_htmx import HTMXPlugin\n\napp = Litestar(route_handlers=[...], plugins=[HTMXPlugin()])\n```\n\n### HTMXTemplate + Partial HTML\n\nReturn Jinja partials from handlers:\n\n```python\nfrom litestar import get\nfrom litestar.response import Template\n\n@get(\"/items\")\nasync def list_items() -> Template:\n items = await item_service.list()\n return Template(template_name=\"partials/item_list.html\", context={\"items\": items})\n```\n\nFor HTMX-targeted endpoints, the template is a fragment (no `` / ``), e.g.:\n\n```html\n\n
\n {% for item in items %}\n
{{ item.name }}
\n {% endfor %}\n
\n```\n\n### Server-driven HTMX Responses\n\n| Response Object | Purpose |\n| --- | --- |\n| `TriggerEvent(name, after=\"receive\", params={...})` | Sets `HX-Trigger` / `HX-Trigger-After-Swap` / `HX-Trigger-After-Settle` |\n| `ClientRedirect(redirect_to=...)` | Sets `HX-Redirect` — client-side hard redirect |\n| `ClientRefresh()` | Sets `HX-Refresh: true` |\n| `PushUrl(push_url=...)` | Sets `HX-Push-Url` — adds entry to browser history |\n| `Reswap(method=\"outerHTML\")` | Sets `HX-Reswap` — overrides client `hx-swap` |\n| `Retarget(target=\"#new\")` | Sets `HX-Retarget` — overrides client `hx-target` |\n| `HXLocation(redirect_to=...)` | Sets `HX-Location` — client-side soft navigation |\n| `HXStopPolling()` | Returns 286 — HTMX stops polling on this element |\n\nExample: trigger a custom event after a successful save:\n\n```python\nfrom litestar_htmx import TriggerEvent\n\n@post(\"/items\")\nasync def create_item(data: ItemCreate) -> TriggerEvent:\n item = await item_service.create(data)\n return TriggerEvent(\n name=\"itemCreated\",\n params={\"id\": item.id, \"name\": item.name},\n after=\"receive\",\n )\n```\n\n### OOB (Out-of-Band) Swaps\n\nFor a single response that updates multiple regions, render multiple fragments and use `hx-swap-oob`:\n\n```html\n\n
Saved!
\n\n\n
New notification!
\n
42
\n```\n\nReturn the combined HTML as a `Template` or `HTMXTemplate`.\n\n### CSRF\n\nUse Litestar's CSRF middleware; expose the token to templates as a `` tag and forward it via HTMX:\n\n```html\n\n\n```\n\n### Pairing with `litestar-vite` (template mode)\n\nFor HTMX projects with bundled JS/CSS and HMR, use `litestar-vite` in `template` mode. Vite bundles HTMX + extensions + CSS; Litestar returns partials. See `../litestar-vite/SKILL.md` and [`../litestar-vite/references/modes.md`](../litestar-vite/references/modes.md#htmx--template-mode).\n\n```html\n\n\n\n\n {{ vite_hmr() }}\n {{ vite('resources/main.js') }}\n\n \n {% block content %}{% endblock %}\n\n\n```\n\n### The `hx-ext=\"litestar\"` client-side templating extension\n\nActivating `hx-ext=\"litestar\"` (on `` or any enclosing element) unlocks **client-side JSON rendering** via `` tags. When an HTMX swap uses `hx-swap=\"json\"`, the response body is parsed as JSON and matched against `ls-*` attributes on descendant `` tags.\n\nThis lets you render JSON API responses as HTML **without** server-side templates — complementary to the partial-HTML pattern.\n\n| Attribute | Purpose |\n| --- | --- |\n| `ls-for=\"item in $data\"` | Iterate over the JSON response array |\n| `ls-key=\"item.id\"` | Stable key for list reconciliation |\n| `ls-if=\"condition\"` | Render only when truthy |\n| `ls-else` | Fallback block for `ls-if` |\n| `${expression}` | Interpolate JS expression into text content |\n| `:attr=\"expression\"` | Dynamic attribute binding |\n| `$data` | The raw JSON response body |\n\nArray rendering:\n\n```html\n\n\n
\n \n \n
${book.title}
\n
${book.author} • ${book.year}
\n \n \n
\n```\n\nSingle-item rendering (properties on `$data` accessible directly via prototype inheritance):\n\n```html\n
\n \n
${title}
\n
${author} • ${year}
\n
\n \n ${tag}\n \n
\n \n \n
Click to load…
\n \n
\n```\n\n**When to use this vs server-side partials:**\n\n| Case | Approach |\n| --- | --- |\n| Data shape simple, rendering trivial, already have JSON endpoint | Client `ls-*` templating (no `HTMXTemplate`) |\n| Complex conditionals, auth-sensitive fields, heavy formatting | Server partials via `HTMXTemplate` |\n| Same endpoint serving both JSON (for JS clients) and HTML (for HTMX clients) | Branch on `request.htmx`; return JSON always and let `ls-*` render it for HTMX consumers |\n\nBoth coexist in one page. The canonical `jinja-htmx` example in `litestar-vite/examples/jinja-htmx/` demonstrates both side by side.\n\n### Common HTMX Attributes (quick refresher)\n\n```html\n\n\n\n\n\n\n\n
Polling
\n\n\n
Replace element
\n
Append
\n\n\nBoost\nNavigate with history\n```\n\nFor full HTMX attribute reference, see .\n\n\n\n## Workflow\n\n### Step 1: Wire HTMXRequest\n\nPass `request_class=HTMXRequest` to `Litestar(...)`. All handlers can now type-annotate `request: HTMXRequest`.\n\n### Step 2: Decide Page vs Partial Boundaries\n\nFor each route, decide:\n\n- **Page route** — returns full layout (one `Template` rendering `base.html`)\n- **Partial route** — returns a fragment used by `hx-get`/`hx-post`\n\nCluster partial routes under a sub-path like `/htmx/...` or differentiate by `request.htmx`.\n\n### Step 3: Templates for Partials\n\nBuild Jinja2 partials as fragments — no ``, no ``. Mount your full-page templates separately.\n\n### Step 4: Server-driven Behavior\n\nUse `TriggerEvent`, `Refresh`, `Reswap`, `Retarget` to push behavior from the server. Avoid putting business logic in the client.\n\n### Step 5: Pair with `litestar-vite` (optional)\n\nIf the app needs bundled CSS/JS or HMR for non-HTMX assets, add `litestar-vite` in `template` or `htmx` mode. See `../litestar-vite/SKILL.md`.\n\n### Step 6: CSRF + Auth\n\nApply Litestar Guards / middleware as usual. Include CSRF token via `htmx:configRequest`.\n\n### Step 7: Test\n\nUse `litestar.testing.AsyncTestClient` with the `HX-Request: true` header to exercise partial responses. See `../litestar-testing/SKILL.md`.\n\n```python\nresp = await client.get(\"/items\", headers={\"HX-Request\": \"true\", \"HX-Target\": \"#item-list\"})\nassert \"\n\n\n\n## Guardrails\n\n- **Use `litestar_htmx`**, not generic ASGI patterns — the plugin integrates with Litestar's lifecycle, OpenAPI, and DI.\n- **Register `HTMXPlugin()`** at the app level — handlers shouldn't construct `HTMXRequest` ad-hoc.\n- **Return partial HTML for HTMX-targeted routes** — never return a full layout to an `hx-get` target.\n- **Use `Template` (Litestar response) — never string-concat HTML** — XSS risk and template caching benefits.\n- **CSRF protection applies to HTMX too** — non-GET HTMX requests must include the CSRF token (header preferred).\n- **Use server-driven response objects** (`TriggerEvent`, `Reswap`, `Retarget`) rather than ad-hoc JS — keeps logic on the server.\n- **Pair with `litestar-vite` only when you need bundled assets / HMR** — pure HTMX with a CDN htmx.min.js works fine without Vite.\n- **Don't return JSON to HTMX endpoints** — HTMX expects HTML; JSON breaks `hx-swap` semantics.\n- **Test with `HX-Request: true`** to exercise the HTMX path.\n\n\n\n\n\n### Validation Checkpoint\n\nBefore delivering Litestar + HTMX code, verify:\n\n- [ ] `HTMXPlugin()` is registered on the `Litestar(...)` constructor\n- [ ] HTMX-targeted routes return Jinja2 fragments (no `` / ``)\n- [ ] `Template` response object used (not raw HTML strings)\n- [ ] CSRF middleware enabled; token forwarded via `htmx:configRequest`\n- [ ] Server-driven behavior uses `TriggerEvent` / `Reswap` / `Retarget` (not ad-hoc JS)\n- [ ] Tests assert against partial HTML with `HX-Request: true` header\n- [ ] If using `litestar-vite`, mode is `template`\n\n\n\n\n\n## Example\n\n**Task:** Items page with an HTMX-driven create form, OOB notification, and server-triggered refresh event.\n\n```python\n# app/domain/items/controllers.py\nfrom litestar import Controller, get, post\nfrom litestar.response import Template\nfrom litestar_htmx import HTMXRequest, TriggerEvent\n\n\nclass ItemController(Controller):\n path = \"/items\"\n\n @get(\"/\")\n async def index(self) -> Template:\n items = await item_service.list()\n return Template(\"pages/items.html\", context={\"items\": items})\n\n @get(\"/list\")\n async def list_partial(self, request: HTMXRequest) -> Template:\n \"\"\"Partial used by hx-get on initial load and after create.\"\"\"\n items = await item_service.list()\n return Template(\"partials/item_list.html\", context={\"items\": items})\n\n @post(\"/\")\n async def create(self, data: ItemCreate) -> TriggerEvent:\n item = await item_service.create(data)\n return TriggerEvent(\n name=\"itemCreated\",\n params={\"id\": item.id, \"name\": item.name},\n after=\"receive\",\n )\n```\n\n```html\n\n{% extends \"base.html\" %}\n\n{% block content %}\n \n \n \n \n\n