Migration ~ htmx

Quick Start

There are two major behavioral changes between htmx 2.x and 4.x:

In htmx 2.0 attribute inheritance is implicit by default while in 4.0 it is explicity by default
In htmx 2.0, 400 and 500 response codes are not swapped by default, whereas in htmx 4.0 these requests will be swapped

Add these two config lines to restore htmx 2.x behavior:



<script>
    htmx.config.implicitInheritance = true;
    htmx.config.noSwap = [204, 304, '4xx', '5xx'];
</script>
<script src="https://cdn.jsdelivr.net/npm/htmx.org@next/dist/htmx.min.js"></script>

implicitInheritance restores htmx 2’s implicit attribute inheritance. noSwap prevents swapping error responses.

Or load the htmx-2-compat extension, which restores implicit inheritance, old event names, and previous error-swapping defaults:



<script src="/path/to/htmx.js"></script>
<script src="/path/to/ext/htmx-2-compat.js"></script>

Most htmx 2 apps should work with either approach. Then migrate incrementally using this guide.

What Changed

`fetch()` replaces `XMLHttpRequest`

All requests use the native fetch() API. This cannot be reverted.

Explicit inheritance

Add :inherited to any attribute that should inherit down the DOM tree.


<!-- htmx 2: implicit inheritance -->
<div hx-confirm="Are you sure?">
    <button hx-delete="/item/1">Delete</button>
</div>

<!-- htmx 4: explicit inheritance -->
<div hx-confirm:inherited="Are you sure?">
    <button hx-delete="/item/1">Delete</button>
</div>

Works on any attribute: hx-boost:inherited, hx-target:inherited, hx-confirm:inherited, etc.

Use :append to add to an inherited value instead of replacing it:



<div hx-include:inherited="#global-fields">
    <!-- appends .extra to the inherited value -->
    <form hx-include:inherited:append=".extra">...</form>
</div>

Revert: htmx.config.implicitInheritance = true

Error responses swap

htmx 4 swaps all HTTP responses. Only 204 and 304 do not swap.

htmx 2 did not swap 4xx and 5xx responses. In htmx 4, if your server returns HTML with a 422 or 500, that HTML gets swapped into the target. Design your error responses to work as swap content, or use hx-status to control per-code behavior.

Revert: htmx.config.noSwap = [204, 304, '4xx', '5xx']

`hx-delete` excludes form data

Like hx-get, hx-delete no longer includes the enclosing form’s inputs.

Fix: add hx-include="closest form" where needed.

No history cache

History no longer caches pages in localStorage. When navigating back, htmx re-fetches the page and swaps it into <body>.

Use htmx.config.history = "reload" for a full page reload instead. Use htmx.config.history = false to disable.

OOB swap order

In htmx 2, out-of-band (hx-swap-oob) elements swapped before the main content.

In htmx 4, the main content swaps first. OOB and hx-partial elements swap after (in document order).

This matters if an OOB swap creates or modifies DOM that the main swap depends on. If your app relies on that ordering, restructure so each swap is independent.

60-second timeout

htmx 2 had no timeout (0). htmx 4 sets defaultTimeout to 60000.

Revert: htmx.config.defaultTimeout = 0

Extension loading

Include extension scripts directly. No attribute needed:



<script src="/path/to/htmx.js"></script>
<script src="/path/to/ext/sse.js"></script>

Restrict which extensions can load:



<meta name="htmx-config" content='{"extensions": "sse, ws"}'>

Extension authors use htmx.registerExtension(name, methodMap) to register.

See Extensions documentation for details.

Renames and Removals

Rename `hx-disable`

Do this before upgrading. The name hx-disable has been reassigned:

In htmx 2, hx-disable meant “skip htmx processing on this element”
In htmx 4, that role is hx-ignore
The name hx-disable now does what hx-disabled-elt used to do (disable form elements during requests)

Rename in this order to avoid conflicts:

Rename hx-disable to hx-ignore
Rename hx-disabled-elt to hx-disable

Removed attributes

Removed	Use instead
`hx-vars`	`hx-vals` with `js:` prefix
`hx-params`	`htmx:config:request` event
`hx-prompt`	`hx-confirm` with `js:` prefix
`hx-ext`	Include extension script directly
`hx-disinherit`	Not needed (inheritance is explicit)
`hx-inherit`	Not needed (inheritance is explicit)
`hx-request`	`hx-config`
`hx-history`	Removed (no localStorage)
`hx-history-elt`	Removed

Renamed events

All events follow a new pattern: htmx:phase:action[:sub-action]

All error events are consolidated to htmx:error.

htmx 2.x	htmx 4.x
`htmx:afterOnLoad`	`htmx:after:init`
`htmx:afterProcessNode`	`htmx:after:init`
`htmx:afterRequest`	`htmx:after:request`
`htmx:afterSettle`	`htmx:after:swap`
`htmx:afterSwap`	`htmx:after:swap`
`htmx:beforeCleanupElement`	`htmx:before:cleanup`
`htmx:beforeHistorySave`	`htmx:before:history:update`
`htmx:beforeOnLoad`	`htmx:before:init`
`htmx:beforeProcessNode`	`htmx:before:process`
`htmx:beforeRequest`	`htmx:before:request`
`htmx:beforeSwap`	`htmx:before:swap`
`htmx:configRequest`	`htmx:config:request`
`htmx:historyCacheMiss`	`htmx:before:history:restore`
`htmx:historyRestore`	`htmx:before:history:restore`
`htmx:load`	`htmx:after:init`
`htmx:oobAfterSwap`	`htmx:after:swap`
`htmx:oobBeforeSwap`	`htmx:before:swap`
`htmx:pushedIntoHistory`	`htmx:after:history:push`
`htmx:replacedInHistory`	`htmx:after:history:replace`
`htmx:responseError`	`htmx:error`
`htmx:sendError`	`htmx:error`
`htmx:swapError`	`htmx:error`
`htmx:targetError`	`htmx:error`
`htmx:timeout`	`htmx:error`

`hx-on::` shorthand

The double-colon shorthand for htmx events no longer works. Because event names changed from camelCase to colon-separated (e.g. htmx:afterRequest → htmx:after:request), the hx-on:: prefix can no longer map to the correct event name.

Use the full event name instead:


<!-- htmx 2 -->
<form hx-on::after-request="this.reset()">

    <!-- htmx 4 -->
    <form hx-on:htmx:after:request="this.reset()">

This applies to all hx-on:: event handlers. Find and replace hx-on:: with hx-on:htmx: and update the event name to the new colon-separated format (see table above).

Removed events

Validation events are removed. Use native browser form validation:

htmx:validation:validate
htmx:validation:failed
htmx:validation:halted

XHR events are removed (htmx uses fetch() now):

Removed	Use instead
`htmx:xhr:loadstart`	No replacement
`htmx:xhr:loadend`	`htmx:finally:request`
`htmx:xhr:progress`	No replacement
`htmx:xhr:abort`	`htmx:error`

Config changes

Renamed:

htmx 2.x	htmx 4.x
`defaultSwapStyle`	`defaultSwap`
`globalViewTransitions`	`transitions`
`historyEnabled`	`history`
`includeIndicatorStyles`	`includeIndicatorCSS`
`timeout`	`defaultTimeout`

Changed defaults:

Config	htmx 2	htmx 4
`defaultTimeout`	`0` (no timeout)	`60000` (60 seconds)
`defaultSettleDelay`	`20`	`1`

Removed:

addedClass, allowEval, allowNestedOobSwaps, allowScriptTags, attributesToSettle, defaultSwapDelay, disableSelector (use hx-ignore), getCacheBusterParam, historyCacheSize, ignoreTitle (still works per-swap via hx-swap="... ignoreTitle:true"), methodsThatUseUrlParams, refreshOnHistoryMiss, responseHandling (use hx-status and noSwap), scrollBehavior, scrollIntoViewOnBoost, selfRequestsOnly (use htmx.config.mode), settlingClass, swappingClass, triggerSpecsCache, useTemplateFragments, withCredentials (use hx-config), wsBinaryType, wsReconnectDelay

The htmx-swapping, htmx-settling, and htmx-added CSS classes are still applied during swaps. The config keys to customize their names have been removed.

Request headers

htmx 2.x	htmx 4.x	Notes
`HX-Trigger`	`HX-Source`	Format changed to `tagName#id` (e.g. `button#submit`)
`HX-Target`	`HX-Target`	Format changed to `tagName#id`
`HX-Trigger-Name`	removed	Use `HX-Source`
`HX-Prompt`	removed	Use `hx-confirm` with `js:` prefix
(new)	`HX-Request-Type`	`"full"` or `"partial"`
(new)	`Accept`	Now explicitly `text/html`

Response headers

Removed:

HX-Trigger-After-Swap
HX-Trigger-After-Settle

Use HX-Trigger or JavaScript instead.

Unchanged: HX-Trigger, HX-Location, HX-Push-Url, HX-Redirect, HX-Refresh, HX-Replace-Url, HX-Retarget, HX-Reswap, HX-Reselect.

JavaScript API changes

Removed methods. Use native JavaScript:

htmx 2.x	Use instead
`htmx.addClass()`	`element.classList.add()`
`htmx.removeClass()`	`element.classList.remove()`
`htmx.toggleClass()`	`element.classList.toggle()`
`htmx.closest()`	`element.closest()`
`htmx.remove()`	`element.remove()`
`htmx.off()`	`removeEventListener()` (`htmx.on()` returns the callback)
`htmx.location()`	`htmx.ajax()`
`htmx.logAll()`	`htmx.config.logAll` `= true`
`htmx.logNone()`	`htmx.config.logAll` `= false`

Renamed: htmx.defineExtension() is now htmx.registerExtension().

Still available: htmx.ajax(), htmx.config, htmx.find(), htmx.findAll(), htmx.on(), htmx.onLoad(), htmx.parseInterval(), htmx.process(), htmx.swap(), htmx.trigger().

Note: htmx.onLoad() now listens on htmx:after:process, not htmx:after:init.

What’s New

Attributes

Attribute	Purpose
`hx-action`	Specify URL (use with `hx-method`)
`hx-method`	Specify HTTP method
`hx-config`	Per-element request config (JSON or `key:value` syntax)
`hx-ignore`	Disable htmx processing (was `hx-disable`)
`hx-validate`	Control form validation behavior

`hx-swap` styles



<div hx-get="/data" hx-swap="innerMorph">...</div>
<div hx-get="/data" hx-swap="outerMorph">...</div>
<div hx-get="/text" hx-swap="textContent">...</div>
<div hx-get="/remove" hx-swap="delete">...</div>

innerMorph / outerMorph: morph swaps using the idiomorph algorithm. Better for preserving state in complex UIs.
textContent: set the target’s text content (no HTML parsing).
delete: remove the target element entirely.

New aliases for existing swap styles (both old and new names work):

New	Equivalent to
`before`	`beforebegin`
`after`	`afterend`
`prepend`	`afterbegin`
`append`	`beforeend`

Status code swaps

Set different swap behavior per HTTP status code:



<form hx-post="/save"
      hx-status:422="swap:innerHTML target:#errors select:#validation-errors"
      hx-status:5xx="swap:none push:false">
    <!-- form fields -->
</form>

Available config keys: swap:, target:, select:, push:, replace:, transition:.

Supports exact codes (404), single-digit wildcards (50x), and range wildcards (5xx). Evaluated in order of specificity.

`<hx-partial>`

Target multiple elements from one response:



<hx-partial hx-target="#messages" hx-swap="beforeend">
    <div>New message</div>
</hx-partial>

<hx-partial hx-target="#count">
    <span>5</span>
</hx-partial>

Each <hx-partial> specifies its own hx-target and hx-swap strategy. A cleaner alternative to out-of-band swaps.

Etag support

htmx 4 supports Etag-based conditional requests automatically:

Response includes an Etag header: htmx stores it on the source element
Next request from that element includes an If-None-Match header
304 Not Modified responses do not swap, avoiding unnecessary DOM updates

View transitions

View Transitions API support is available but disabled by default.

Enable: htmx.config.transitions = true

JSX compatibility

Frameworks that don’t support : in attribute names can use metaCharacter to replace it:


htmx.config.metaCharacter = "-";
// hx-ws-connect instead of hx-ws:connect
// hx-confirm-inherited instead of hx-confirm:inherited

JavaScript methods

htmx.forEvent(eventName, timeout): returns a promise that resolves when an event fires
htmx.takeClass(element, className, container): removes class from siblings, adds to element
htmx.timeout(time): returns a promise that resolves after a delay

Request context

All events provide a consistent ctx object with request/response information.

Events

Event	Fires
`htmx:after:cleanup`	After element cleanup
`htmx:after:history:update`	After history update
`htmx:after:process`	After element processing
`htmx:before:response`	Before response body is read (cancellable)
`htmx:before:settle`	Before settle phase
`htmx:after:settle`	After settle phase
`htmx:before:viewTransition`	Before a view transition starts (cancellable)
`htmx:after:viewTransition`	After a view transition completes
`htmx:finally:request`	Always fires after a request (success or failure)

Config keys

Config	Default	Purpose
`extensions`	`''`	Comma-separated list of allowed extension names
`mode`	`'same-origin'`	Fetch mode (replaces `selfRequestsOnly`)
`inlineScriptNonce`	`''`	Nonce for inline scripts
`inlineStyleNonce`	`''`	Nonce for inline styles
`metaCharacter`	`':'`	Separator character in attribute/event names
`morphIgnore`	`''`	CSS selector for elements to ignore during morph
`morphScanLimit`		Max elements to scan during morph matching
`morphSkip`	`''`	CSS selector for elements to skip during morph
`morphSkipChildren`	`''`	CSS selector for elements whose children to skip during morph

SSE extension

The SSE extension uses fetch() and ReadableStream instead of EventSource. This enables request bodies, custom headers, and all HTTP methods.

See the SSE extension documentation for details.

Core extensions

htmx 4 ships with 9 core extensions:

Extension	Description
`alpine-compat`	Alpine.js compatibility: initializes Alpine on fragments before swap
`browser-indicator`	Shows the browser’s native loading indicator during requests
`head-support`	Merges head tag information (styles, etc.) in htmx requests
`htmx-2-compat`	Restores implicit inheritance, old event names, and previous error-swapping defaults
`optimistic`	Shows expected content from a template before the server responds
`preload`	Triggers requests early (on mouseover/mousedown) for near-instant page loads
`sse`	Server-Sent Events streaming support
`upsert`	Updates existing elements by ID and inserts new ones, preserving unmatched elements
`ws`	Bi-directional Web Socket communication

Checklist

Add config options or load htmx-2-compat for backward compatibility
Rename hx-disable to hx-ignore, then hx-disabled-elt to hx-disable
Replace removed attributes with alternatives
Find/replace event names in JavaScript and hx-on:: attributes
Replace removed API methods with native JS
Update extensions
Rename changed config keys
Test error handling (4xx/5xx now swap by default)
Test attribute inheritance
Test history navigation

Migration Notes

Individual documentation pages include migration notes where features changed.

Look for these:

Changes in htmx 4.0

Migration

hx-delete excludes form data

hx-swap styles

`hx-delete` excludes form data

`hx-swap` styles