htmx Patterns skill for Codex

Done well, every htmx endpoint returns HTML that is correct on its own (full page for a normal request, fragment for an htmx request), the app still works for a plain link or form submit where that matters, errors render somewhere visible, and the back button shows the right page.

Before writing code

1. Read AGENTS.md, find the template engine and how routes render views.
2. Check the htmx version (script tag, package.json, or vendored file). This skill targets htmx 2.x. If the project is on 1.x, note the 2.0 changes below before copying examples; if on a newer major, read its migration notes first (needs network).
3. Find existing conventions: a base layout, partial templates directory, a helper that detects htmx requests, how CSRF tokens are exposed.

Core rule: one URL, two renderings

The server checks the HX-Request: true header and returns a fragment for htmx and the full page otherwise:

# Flask / Jinja
@app.get("/contacts")
def contacts():
    q = request.args.get("q", "")
    rows = Contact.search(q)
    tpl = "contacts/_rows.html" if request.headers.get("HX-Request") else "contacts/index.html"
    resp = make_response(render_template(tpl, rows=rows, q=q))
    resp.headers["Vary"] = "HX-Request"
    return resp

index.html includes _rows.html, so there is one source for the fragment markup. Always send Vary: HX-Request on such URLs, or a browser/CDN cache serves a fragment when the user reloads the page. For boosted or history-restored requests, also check HX-History-Restore-Request and return the full page.

Choosing target and swap

Goal	Attributes
Replace an element’s contents	hx-target="#results" hx-swap="innerHTML" (default swap)
Replace the element itself (row edit)	hx-target="closest tr" hx-swap="outerHTML"
Append items (infinite list, chat)	hx-swap="beforeend" on the container
Remove an element after DELETE	server returns empty 200, hx-swap="outerHTML"; or hx-swap="delete"
Fire and forget, no DOM change	hx-swap="none", or server returns 204
Take part of a full-page response	hx-select="#main"
Update a second region too (counter, flash)	hx-swap-oob="true" on an element with matching id in the response

Extended selectors: this, closest <sel>, find <sel>, next <sel>, previous <sel>. Swap modifiers: swap:200ms, settle:, scroll:top, show:window:top, focus-scroll:false, transition:true (View Transitions).

Triggers

<input type="search" name="q"
       hx-get="/contacts" hx-target="#rows"
       hx-trigger="input changed delay:300ms, keyup[key=='Enter'], search"
       hx-sync="this:replace"
       hx-indicator="#spinner">

Need	Trigger
Debounced typing	input changed delay:300ms
Rate-limit scroll/resize	throttle:500ms
Infinite scroll	revealed on the last item, or intersect once
Lazy load a panel	load (or revealed for below the fold)
Polling	every 5s; server returns status 286 to stop
Listen to a custom/server event	my-event from:body

hx-sync="this:replace" aborts the in-flight search when a new one starts; without it, slow responses can arrive out of order and overwrite newer results.

Patterns

Inline edit (click to edit)

<!-- _contact_row.html -->
<tr id="contact-{{ c.id }}">
  <td>{{ c.name }}</td>
  <td><button hx-get="/contacts/{{ c.id }}/edit" hx-target="closest tr" hx-swap="outerHTML">Edit</button></td>
</tr>

<!-- _contact_edit.html -->
<tr id="contact-{{ c.id }}">
  <td><input name="name" value="{{ c.name }}" autofocus></td>
  <td>
    <button hx-put="/contacts/{{ c.id }}" hx-include="closest tr" hx-target="closest tr" hx-swap="outerHTML">Save</button>
    <button hx-get="/contacts/{{ c.id }}" hx-target="closest tr" hx-swap="outerHTML">Cancel</button>
  </td>
</tr>

Delete with confirmation and disabled button

<button hx-delete="/contacts/{{ c.id }}" hx-confirm="Delete {{ c.name }}?"
        hx-target="closest tr" hx-swap="outerHTML swap:300ms" hx-disabled-elt="this">Delete</button>

Form with server-side validation errors: re-render the form fragment with errors and return it. In htmx 2, 4xx/5xx responses are not swapped by default, so either return 200 with the error markup for validation failures, or configure htmx.config.responseHandling to swap 422:

htmx.config.responseHandling = [
  { code: '204', swap: false },
  { code: '[23]..', swap: true },
  { code: '422', swap: true },        // validation errors render in place
  { code: '[45]..', swap: false, error: true },
];

Out-of-band update (add a row and bump a counter in one response):

<tr id="contact-42">...</tr>
<span id="contact-count" hx-swap-oob="true">43 contacts</span>

Modal form: hx-get the dialog fragment into a container, call showModal() from hx-on::after-swap="this.querySelector('dialog').showModal()", and on success return HX-Trigger: contactSaved so the list refreshes via hx-trigger="contactSaved from:body".

Response headers the server can send

Header	Effect
HX-Redirect: /login	Full client-side redirect
HX-Location: /contacts/42	htmx-style navigation without full reload
HX-Refresh: true	Reload the page
HX-Retarget: #errors / HX-Reswap: innerHTML	Change target or swap from the server
HX-Trigger: {"showToast": {"msg": "Saved"}}	Fire client events after the response
HX-Push-Url: /contacts?page=2	Update the address bar

For session expiry, return HX-Redirect rather than a 302: a 302 makes htmx swap the login page into the target element.

Security

• CSRF: put the token on a common ancestor so every request sends it: <body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'> (Django) or the framework’s equivalent header. Non-GET requests without it should fail.
• Escape everything in templates as usual; fragments are HTML injected into the page, so a missed escape is XSS. Never return user content with |safe/raw helpers.
• Authorisation on every fragment endpoint: /contacts/42/edit must check ownership just like the full page.
• hx-on attributes and inline scripts in responses need a CSP that allows them; with a strict CSP, set htmx.config.allowEval = false and use event listeners in JS files.

htmx 1.x to 2.x changes that bite

• hx-on uses hx-on:click / hx-on::after-request syntax; the old hx-on="click: ..." form is gone.
• DELETE requests send parameters in the query string, not the body.
• Extensions (SSE, WebSockets, json-enc, etc.) ship as separate packages; load them explicitly.
• Error responses (4xx/5xx) are not swapped unless configured, as above.

History and boosting

• hx-boost="true" on <body> or a nav upgrades links and forms to AJAX with full-page responses; keep the server rendering full pages for those routes.
• History snapshots are taken from the DOM; elements holding sensitive or stale data can opt out with hx-history="false" on the page.
• Third-party widgets initialised on DOMContentLoaded must also initialise on htmx:load (fires for new content), or they break after swaps.

Gotchas

• Swapping innerHTML of a container that contains the triggering element destroys the trigger mid-request; target a sibling or use outerHTML on a wrapper.
• hx-target is inherited by children; an unexpected target often comes from an ancestor. Use hx-disinherit or set the target explicitly.
• Returning a full page to an htmx request nests a whole <html> inside a div. Check HX-Request in a shared helper, not per view.
• Duplicate ids after swaps break OOB swaps and label associations.
• Loading state needs CSS: .htmx-indicator { opacity: 0 } .htmx-request .htmx-indicator, .htmx-request.htmx-indicator { opacity: 1 }.

Verification

• Each endpoint returns a fragment with HX-Request and a full page without it (curl both)
• Vary: HX-Request present; hard reload after navigation shows a full page
• Validation errors, 401/403 and 500 responses render visibly, not silently ignored
• Back and forward buttons restore correct content after boosted navigation and pushes
• Rapid typing in search shows results for the final query only
• Non-GET requests fail without the CSRF token

curl -s -H 'HX-Request: true' 'http://localhost:8000/contacts?q=ann' | head -20
curl -sI 'http://localhost:8000/contacts' | grep -i vary