htmx

Covers HTMX 2.x: the hypermedia-driven architecture (HATEOAS), HTML-over-the-wire approach, core attributes (hx-get, hx-post, hx-put, hx-patch, hx-delete), hx-trigger with event modifiers (delay, thro

SKILL.md

GitHub

HTMX

This skill covers HTMX 2.x, including:

  • HATEOAS philosophy: server returns HTML, the DOM is the state, no client-side data model
  • Core attributes: hx-get, hx-post, hx-put, hx-patch, hx-delete
  • Trigger system: hx-trigger with event modifiers (delay, throttle, changed, once, revealed, intersect, polling)
  • Targeting: hx-target with CSS selectors, closest, find, next, previous
  • Swap strategies: innerHTML, outerHTML, beforeend, afterbegin, beforebegin, afterend, delete, none, morph via Idiomorph
  • Out-of-band swaps: hx-swap-oob for updating multiple DOM elements from a single response
  • Progressive enhancement: hx-boost for upgrading links and forms to AJAX
  • Request/response header model: HX-Request, HX-Trigger, HX-Redirect, HX-Reswap, HX-Retarget
  • Extensions: SSE, WebSocket, Idiomorph, response-targets, preload, loading-states, head-support
  • Scripting companions: Alpine.js for client-side state, Hyperscript for behavior DSL
  • Security: CSRF tokens, selfRequestsOnly (default true in 2.0), CSP compatibility
  • Backend integration: Django, Flask, Rails, ASP.NET, Go, FastAPI, Laravel, Spring, Phoenix
  • Diagnostics: htmx.logAll(), event listeners, Network tab inspection

HTMX is a hypermedia-driven library: the server controls application state by returning HTML fragments. The browser remains a hypermedia client.

How to Approach Tasks

When you receive a request:

  1. Classify the request type:

    • Swap/targeting issues -- Load references/architecture.md
    • Backend integration -- Load references/patterns/backend-integration.md
    • Progressive enhancement -- Load references/patterns/progressive-enhancement.md
    • Swap strategy selection -- Load references/patterns/swap-strategies.md
    • Debugging -- Load references/diagnostics.md
    • Best practices / design -- Load references/best-practices.md
  2. Identify the backend -- HTMX is backend-agnostic. Ask what server framework is in use (Django, Flask, Rails, ASP.NET, Go, etc.) to provide framework-specific examples.

  3. Load context -- Read the relevant reference file for deep knowledge.

  4. Analyze -- Apply hypermedia-driven reasoning. HTMX is not a SPA framework. Avoid recommending JSON APIs, client-side state management, or JavaScript-heavy patterns.

  5. Recommend -- Provide actionable guidance with HTML + server-side examples. Prefer the simplest attribute combination that solves the problem.

  6. Verify -- Suggest validation steps (browser DevTools Network tab, htmx.logAll()).

Core Expertise

Philosophy

HTMX extends HTML's native hypermedia controls. HTML already supports <a> (GET) and <form> (GET/POST). HTMX generalizes this: any element can issue any HTTP verb, any event can trigger a request, any element can be the target, and the response is always HTML.

No build step. No virtual DOM. No node_modules. A single ~15KB gzipped script.

Locality of behavior: hx-get="/search" on an <input> tells you everything about what it does. No tracing through JS files or component trees.

Core Attributes

hx-get="/endpoint"       hx-post="/endpoint"
hx-put="/endpoint"       hx-patch="/endpoint"
hx-delete="/endpoint"

hx-trigger

Controls what event initiates the request. Default: click for most elements, change for inputs, submit for forms.

hx-trigger="click"
hx-trigger="keyup changed delay:300ms"    <!-- debounce, only if changed -->
hx-trigger="click throttle:2s"            <!-- at most once per 2s -->
hx-trigger="click once"                    <!-- fires only first time -->
hx-trigger="load"                          <!-- on page load -->
hx-trigger="revealed"                      <!-- enters viewport -->
hx-trigger="intersect threshold:0.5"       <!-- 50% visible -->
hx-trigger="every 5s"                      <!-- polling -->
hx-trigger="click from:document"           <!-- listen on document -->

hx-target

hx-target="#result"            hx-target="this"
hx-target="closest div"       hx-target="find .child"
hx-target="next .sibling"     hx-target="previous .sibling"

hx-swap

hx-swap="innerHTML"       <!-- replace inner content (default) -->
hx-swap="outerHTML"        <!-- replace entire element -->
hx-swap="beforeend"        <!-- append as last child -->
hx-swap="afterbegin"       <!-- prepend as first child -->
hx-swap="delete"           <!-- delete target, ignore response -->
hx-swap="none"             <!-- no DOM change -->

Modifiers: swap:500ms, settle:300ms, scroll:top, show:top, transition:true.

Out-of-Band Swaps

One response updates multiple DOM elements:

<!-- Primary content swaps into hx-target -->
<div id="search-results"><p>Result 1</p></div>

<!-- OOB: swaps into matching IDs elsewhere in DOM -->
<span id="result-count" hx-swap-oob="true">2 results</span>
<div id="status-bar" hx-swap-oob="innerHTML">Search complete</div>

hx-boost

Upgrades all <a> and <form> elements within scope to HTMX AJAX. Pages work without JavaScript; boost is layered on.

<body hx-boost="true">
  <a href="/about">About</a>          <!-- AJAX navigation -->
  <form method="post" action="/save">  <!-- AJAX submit -->
</body>

Request/Response Headers

HTMX sends: HX-Request, HX-Trigger, HX-Target, HX-Current-URL.

Server can respond with: HX-Trigger (fire events), HX-Redirect, HX-Reswap, HX-Retarget, HX-Push-Url, HX-Refresh.

HTTP 204 No Content: HTMX performs no swap.

CSS Lifecycle Classes

  • htmx-request -- on element while request is in-flight
  • htmx-settling -- on new content during settle phase
  • htmx-swapping -- on old content before swap

Extensions

Extensions are separate scripts activated with hx-ext:

  • SSE: hx-ext="sse" sse-connect="/stream" sse-swap="message"
  • WebSocket: hx-ext="ws" ws-connect="/ws/chat"
  • Idiomorph: hx-ext="morph" -- intelligent DOM merging preserving focus and state
  • response-targets: Map HTTP status codes to different targets
  • preload: Preload links on mouseenter
  • loading-states: Automatic loading UI management
  • head-support: Merge <head> content from responses

Common Pitfalls

1. Target element does not exist If hx-target references a nonexistent element, the swap silently fails. Use htmx.logAll() to see warnings.

2. innerHTML vs outerHTML mismatch If the response returns a wrapper <div id="target"> and the strategy is innerHTML, the ID appears twice in the DOM.

3. OOB swap ID mismatch hx-swap-oob finds targets by ID. No error if no match is found.

4. HTMX 2.0 selfRequestsOnly blocks cross-origin Default true in 2.0. Set htmx.config.selfRequestsOnly = false for cross-origin APIs.

5. SSE/WS moved to extensions in 2.0 hx-sse and hx-ws no longer built-in. Load the extension script.

6. DELETE sends URL parameters in 2.0 In 1.x DELETE used request body. In 2.0 it uses query parameters.

7. Nested forms are invalid HTML Browsers ignore inner forms. HTMX cannot fix this.

8. CSRF tokens not forwarded HTMX sends cookies but not CSRF tokens from meta tags. Set hx-headers on <body>.

9. Third-party JS libraries need re-init after swap Use htmx:afterSwap event to reinitialize date pickers, tooltips, etc.

10. Response not HTML If server returns JSON, HTMX inserts raw text. Verify Content-Type is text/html.

Reference Files

  • references/architecture.md -- Attributes, swap strategies, OOB, request/response model, extensions
  • references/best-practices.md -- Progressive enhancement, backend integration, scripting companions, security
  • references/diagnostics.md -- Request debugging, swap issues, extension conflicts

Pattern Guides

  • references/patterns/swap-strategies.md -- innerHTML vs outerHTML vs morph, OOB, infinite scroll
  • references/patterns/backend-integration.md -- Django, Flask, Rails, ASP.NET, Go, FastAPI patterns
  • references/patterns/progressive-enhancement.md -- hx-boost, graceful degradation