name	htmx
description	Implements HTMX interactions, configures swap behaviors, debugs hx-* requests, and builds hypermedia-driven UI components. Use when tasks involve hx-* attributes, HTMX AJAX requests, swap strategies, server-sent events, WebSockets, or hypermedia-driven UIs.

HTMX

Use this skill for HTMX implementation and integration. 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:

<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:

<!-- 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 - Most attributes inherit to children. Not inherited: hx-trigger, hx-on*, hx-swap-oob, hx-preserve, hx-history-elt, hx-validate. Use hx-disinherit or unset to stop inheritance
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-disable to 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 as data-hx-* for HTML validation compliance
Stop polling with HTTP 286 - Server returns status 286 to stop every or load delay polling. Always use 286 for poll termination, not conditional client-side logic
Error swaps need htmx:beforeSwap - Non-2xx responses (e.g., 422 validation errors) are not swapped by default. Add an htmx:beforeSwap listener to enable swapping for error status codes
Decouple with HX-Trigger headers - Use HX-Trigger response headers to fire client-side events instead of hardcoding DOM element IDs in server responses
Detect HTMX requests server-side - Check the HX-Request header to serve HTML fragments for HTMX requests and full pages for direct browser requests. Set Vary: HX-Request for 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): 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.md then domain-specific files

HTMX

Use this skill for HTMX implementation and integration. 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:

<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:

 <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 - Most attributes inherit to children. Not inherited: hx-trigger, hx-on*, hx-swap-oob, hx-preserve, hx-history-elt, hx-validate. Use hx-disinherit or unset to stop inheritance

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-disable to 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 as data-hx-* for HTML validation compliance

Stop polling with HTTP 286 - Server returns status 286 to stop every or load delay polling. Always use 286 for poll termination, not conditional client-side logic

Error swaps need htmx:beforeSwap - Non-2xx responses (e.g., 422 validation errors) are not swapped by default. Add an htmx:beforeSwap listener to enable swapping for error status codes

Decouple with HX-Trigger headers - Use HX-Trigger response headers to fire client-side events instead of hardcoding DOM element IDs in server responses

Detect HTMX requests server-side - Check the HX-Request header to serve HTML fragments for HTMX requests and full pages for direct browser requests. Set Vary: HX-Request for 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): 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.md then domain-specific files