Htmx Knowledge Patch

htmx Knowledge Patch

Use this skill when implementing, reviewing, debugging, or upgrading htmx applications. For established applications, begin with the migration guidance, then open the topic reference that matches the work.

Reference index

Breaking migrations first

Upgrade separately distributed extensions

Extensions are versioned outside the core repository. Audit and upgrade each installed extension independently. Most 1.x extensions still work, but the SSE extension has a breaking change and must be upgraded. Replace the removed hx-sse and hx-ws attributes with the corresponding extension attributes.

See Migration and configuration.

Load the build for the module system

The ESM distribution has a default export:

import htmx from "htmx.org/dist/htmx.esm.js";

Account for changed defaults

Requests are same-origin-only by default, DELETE values use URL parameters, and swap scrolling is instant. Restore earlier behavior only where the application depends on it:

htmx.config.methodsThatUseUrlParams = ["get"];
htmx.config.selfRequestsOnly = false;
htmx.config.scrollBehavior = "smooth";

If cross-origin requests are enabled, enforce an explicit htmx:validateUrl allowlist and configure CORS for the htmx headers. See Requests and validation.

Replace removed JavaScript and attribute APIs

Use one hx-on:<event> attribute per inline handler; the legacy multi-event hx-on form is removed.

<button hx-post="/save" hx-on:click="this.disabled = true">Save</button>

Use the public htmx.swap() API instead of the removed internal selectAndSwap() method:

htmx.swap(document.querySelector("#result"), "<p>Updated</p>", {
  swapStyle: "innerHTML"
});

High-value request controls

Confirm requests asynchronously

htmx:confirm fires for every request trigger, including triggers without hx-confirm. Cancel the event, then call event.detail.issueRequest() only after approval:

document.body.addEventListener("htmx:confirm", (event) => {
  if (!event.target.matches("[data-confirm]")) return;
  event.preventDefault();
  Promise.resolve(window.confirm("Continue?")).then((ok) => {
    if (ok) event.detail.issueRequest();
  });
});

Stop server-driven polling

For an hx-trigger="every ..." request, return HTTP status 286 when the server should stop the poll.

Report native validation when desired

Invalid form requests are blocked, but native validation UI and focus on the first invalid control are disabled by default. Enable them with:

htmx.config.reportValidityOfForms = true;

Use hx-validate="true" when a non-form request trigger must validate too.

High-value swap and response controls

Swap literal text

Use the core textContent swap style when the response must be assigned as literal text instead of parsed as HTML:

<button hx-get="/source" hx-target="#result" hx-swap="textContent">Show source</button>
<pre id="result"></pre>

Return context-sensitive out-of-band elements

Wrap elements such as table rows in <template> so they retain the parsing context that a free-standing response node lacks:

<template>
  <tr id="status-row" hx-swap-oob="outerHTML">
    <td>Ready</td>
  </tr>
</template>

Process only top-level out-of-band fragments with:

htmx.config.allowNestedOobSwaps = false;

Handle response statuses in order

htmx.config.responseHandling uses the first matching regular expression. Prepend specific rules ahead of broad defaults:

htmx.config.responseHandling.unshift({
  code: "422", swap: true, error: false
});

The browser consumes HTTP 3xx responses before htmx can process htmx-specific headers. Return a non-redirect response when using HX-Redirect, HX-Location, or HX-Trigger.

History and cache safety

Every pushed URL must be able to return a complete document after a history cache miss. A miss carries HX-History-Restore-Request: true; when ordinary HX-Request handling selects fragments, use:

htmx.config.historyRestoreAsHxRequest = false;

Use refreshOnHistoryMiss when a hard refresh is the intended fallback.

Place hx-history="false" anywhere in the current document or loaded fragment when its URL must not be snapshotted. Keep a custom hx-history-elt present on every page, and undo temporary DOM mutations in htmx:beforeHistorySave.

For URLs that serve both complete documents and fragments, send Vary: HX-Request and distinct ETags. If the cache cannot vary on that header, enable htmx.config.getCacheBusterParam = true.

Trigger and inheritance rules

The selector in from:<selector> is resolved once, so it does not track later DOM additions. Trigger-filter names resolve against the triggering event before the global scope, and this is the element carrying hx-trigger.

Clear a single inherited attribute with an unset value such as hx-confirm="unset". Use hx-disinherit to block selected inheritance. To make inheritance opt-in globally, set:

htmx.config.disableInheritance = true;

Descendants can then opt in with hx-inherit.

Extension selection guide

Read Extensions and security before choosing between similarly shaped URL or JSON extensions.

Security checklist

• Keep same-origin-only requests unless cross-origin access is necessary.
• Cancel htmx:validateUrl for destinations outside an explicit allowlist.
• Allow htmx request headers and expose required response headers in CORS.
• Configure inlineStyleNonce before htmx loads when CSP protects inline styles.
• Put rotating boosted-navigation CSRF tokens inside content that is replaced.
• Prefer framework-provided hidden CSRF inputs when available.

Working approach

Preserve working behavior unless a fix or feature requires change. Prefer configuration switches for behavioral improvements and extensions for new functionality. Upgrade selectively when a particular fix or feature is needed.