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.mdplugins/frontend/skills/htmx/SKILL.md
GitHubHTMX
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-triggerwith event modifiers (delay, throttle, changed, once, revealed, intersect, polling) - Targeting:
hx-targetwith 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-oobfor updating multiple DOM elements from a single response - Progressive enhancement:
hx-boostfor 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:
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
- Swap/targeting issues -- Load
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.
Load context -- Read the relevant reference file for deep knowledge.
Analyze -- Apply hypermedia-driven reasoning. HTMX is not a SPA framework. Avoid recommending JSON APIs, client-side state management, or JavaScript-heavy patterns.
Recommend -- Provide actionable guidance with HTML + server-side examples. Prefer the simplest attribute combination that solves the problem.
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-flighthtmx-settling-- on new content during settle phasehtmx-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, extensionsreferences/best-practices.md-- Progressive enhancement, backend integration, scripting companions, securityreferences/diagnostics.md-- Request debugging, swap issues, extension conflicts
Pattern Guides
references/patterns/swap-strategies.md-- innerHTML vs outerHTML vs morph, OOB, infinite scrollreferences/patterns/backend-integration.md-- Django, Flask, Rails, ASP.NET, Go, FastAPI patternsreferences/patterns/progressive-enhancement.md-- hx-boost, graceful degradation