HTMX
Use this skill for HTMX implementation and integration. Covers htmx 2.x (current stable) and htmx 4.x (beta). Reference files are annotated with [htmx 4], [htmx 4 change], and [htmx 4 removed] admonitions. Read only the reference file(s) needed for the task.
Quick Start
- Identify the domain of the task (attributes, requests, swapping, events, patterns).
- Open the matching file from
references/. - Implement using HTML-first, hypermedia-driven patterns.
- Validate that server responses return HTML fragments, not JSON.
Minimal example — a button that loads content via GET:
html<button hx-get="/contacts" hx-target="#results" hx-swap="innerHTML"> Load Contacts </button> <div id="results"></div>
The server endpoint (/contacts) must return an HTML fragment, not JSON:
html<!-- Server response (HTML fragment, no <html>/<body> wrappers) --> <ul> <li>Alice</li> <li>Bob</li> </ul>
The default swap is innerHTML — the response replaces the target's children. Use hx-swap="outerHTML" to replace the target element itself.
Critical Rules
- HTML responses - HTMX expects HTML responses from the server, not JSON
- Attribute inheritance - (v2) Most attributes inherit to children; use
hx-disinheritorunsetto stop. (v4) Inheritance is explicit — use:inheritedsuffix to opt in. Not inherited in either version:hx-trigger,hx-on*,hx-swap-oob,hx-preserve,hx-history-elt,hx-validate - Default swap is innerHTML - Always confirm the intended swap method
- Form values auto-included - Non-GET requests automatically include the closest enclosing form's values
- Progressive enhancement - Use
hx-boost="true"— pages must work without JS - Escape user content - Escape all user-supplied content server-side to prevent XSS. Wrap areas rendering user-generated content with
hx-disableto prevent HTMX processing of injected attributes - CSS lifecycle classes - HTMX adds/removes CSS classes during requests — use for transitions and indicators
- data-prefix supported - All
hx-*attributes can also be written asdata-hx-*for HTML validation compliance - Stop polling with HTTP 286 - Server returns status
286to stopeveryorload delaypolling. Always use 286 for poll termination, not conditional client-side logic - Error swaps - (v2) Non-2xx responses are not swapped by default — add an
htmx:beforeSwaplistener to enable. (v4) All responses swap by default except 204/304 — usehx-statusfor per-code control - Decouple with HX-Trigger headers - Use
HX-Triggerresponse headers to fire client-side events instead of hardcoding DOM element IDs in server responses - Detect HTMX requests server-side - Check the
HX-Requestheader to serve HTML fragments for HTMX requests and full pages for direct browser requests. SetVary: HX-Requestfor caching
Reference Map
- All
hx-*attributes, values, and modifiers:references/attributes.md - Triggers, headers, parameters, CSRF, caching, CORS:
references/requests.md - Swap methods, targets, OOB swaps, morphing, view transitions:
references/swapping.md - Events, JS API, configuration, extensions, debugging:
references/events-api.md - Common UI patterns and examples:
references/patterns.md - Official extensions (WS, SSE, Idiomorph, response-targets, head-support, preload, hx-live, hx-prompt):
references/extensions.md - Gotchas, pitfalls, and practical guidance:
references/gotchas.md - Cross-file index and routing:
references/REFERENCE.md
Task Routing
- Adding HTMX behavior to elements ->
references/attributes.md - Configuring how/when requests fire ->
references/requests.md - Controlling where/how responses render ->
references/swapping.md - Handling events, JS interop, or config ->
references/events-api.md - Building common UI patterns (search, infinite scroll, modals, etc.) ->
references/patterns.md - Using WebSockets, SSE, morphing, preloading, response targeting, or head merging ->
references/extensions.md - Avoiding common pitfalls, accessibility, error handling, architecture decisions ->
references/gotchas.md - Cross-cutting concerns or architecture ->
references/REFERENCE.mdthen domain-specific files
