HTMX

Execution Workflow

1. Decide whether HTMX should be enabled globally with HTMXPlugin or locally with request_class=HTMXRequest.
2. Shape handlers around one contract: full page for normal requests, fragment or HTMX-aware response for HTMX requests.
3. Read request context from request.htmx instead of hand-parsing HTMX headers.
4. Choose the right response primitive: HTMXTemplate for rendered fragments or the dedicated HTMX response classes for redirect, refresh, swap, retarget, event, history, or polling behavior.
5. Keep templates small and swap-oriented so each endpoint returns only the markup or signal the target element needs.
6. Verify both non-HTMX and HTMX behaviors in tests, including headers, redirect semantics, and fragment shape.

Core Rules

• Use HTMXPlugin() when most of the app should speak HTMX-aware requests.
• Use request_class=HTMXRequest locally when only one app layer or route needs HTMX support.
• Prefer request.htmx and HTMXDetails properties over manual header inspection.
• Keep full-page and fragment rendering intentional; do not accidentally return layout HTML into a fragment swap target.
• Annotate HTMXTemplate handlers as returning Template, matching the Litestar docs.
• If you trigger an HTMX event from HTMXTemplate, provide after= and keep it to receive, settle, or swap.