htmx 2.x → htmx 4.x Migration Guide

The purpose of this guide is to provide instructions for migrations from htmx 2.x to htmx 4.x.

htmx 4 is a significant architectural rewrite which involves breaking changes. We have tried to maintain backwards compatibility where possible but this upgrade will require more work than the htmx 1 to htmx 2 migration.

Table of Contents

• Biggest Changes
• Attribute Changes
• Out-of-Band Swap Order
• Configuration Changes
• Event Name Changes
• JavaScript API Changes
• HTTP Header Changes
• Extension Changes
• Upgrade Music

Biggest Changes

The three most impactful changes in htmx 4 are:

• Switching to fetch() for issuing ajax requests
• Making attribute inheritance explicit by default
• Adopting the response targets extension concept for retargeting based on HTTP response codes, and making most HTTP response codes swap content (including 4xx and 5xx response codes)

While there is no way to “undo” the first item in htmx 4, the second two changes can be undone by:

• Setting htmx.config.implicitInheritance to true, which will restore implicit attribute inheritance
• Setting htmx.config.noSwap to [204, 304, '4xx', '5xx']

Making these to changes will make many htmx 2-based applications work with htmx 4 without further changes.

Attribute Changes

Renamed Attributes

Important Note on hx-disable:

In htmx 2, hx-disable disables htmx processing. In htmx 4, hx-ignore serves this purpose. Before upgrading:

1. Search for any usage of hx-disable in your htmx 2 codebase
2. Rename hx-disable → hx-ignore
3. Then rename hx-disabled-elt → hx-disable

Removed Attributes

The following attributes have been removed:

New Attributes

Attribute Inheritance Changes

Inheritance is now, by default, explicit using the :inherited modifier.

Before (htmx 2):

<!-- Attributes inherited automatically -->
<div hx-confirm="Are you sure?">
    <button hx-delete="/item/1">Delete 1</button>
    <button hx-delete="/item/2">Delete 2</button>
</div>

After (htmx 4):

<!-- Must use :inherited modifier -->
<div hx-confirm:inherited="Are you sure?">
    <button hx-delete="/item/1">Delete 1</button>
    <button hx-delete="/item/2">Delete 2</button>
</div>

Any attribute can use the :inherited modifier: hx-boost:inherited, hx-headers:inherited, hx-target:inherited, etc.

As mentioned above, you can revert this behavior by setting htmx.config.implicitInheritance to true

GET/DELETE Form Data

In htmx 4 hx-delete, like hx-get, no longer includes the enclosing form’s inputs by default. Use hx-include="closest form" if you need this behavior.

Out-of-Band Swap Order

In htmx 2, out-of-band (hx-swap-oob) elements were swapped before the main content. In htmx 4, the main content is swapped first, and OOB/hx-partial elements are swapped after. This is generally more intuitive but may affect code that relied on the previous ordering.

Configuration Changes

If you customize htmx.config, you will need to update your configuration for htmx 4.

Renamed Config Keys

Changed Defaults

Removed Config Keys

The following configuration keys have been removed in htmx 4:

data-hx-* Attribute Prefix

In htmx 2, both hx-* and data-hx-* attributes were recognized automatically. In htmx 4, only hx-* is recognized by default. If you use data-hx-* attributes, set the prefix in your config:

<meta name="htmx-config" content='{"prefix": "data-hx-"}'>

Note: When using a custom prefix, all htmx attributes must use that prefix.

Event Name Changes

htmx 4 uses a new event naming convention: htmx:phase:action[:sub-action], and so if you are using htmx events you need to rename the events that they are listening for. Here is a complete table with the htmx 4 equivalent events:

XHR Upload Progress Events Removed

In htmx 2.x, the following XHR upload progress events were available:

• htmx:xhr:loadstart
• htmx:xhr:loadend
• htmx:xhr:progress
• htmx:xhr:abort

These events provided detailed upload progress information with lengthComputable, loaded, and total properties.

In htmx 4.x these events have been removed because htmx now uses the fetch() API instead of XMLHttpRequest.

If you need upload progress tracking in htmx 4:

1. Use the htmx:config:request event to access the request context
2. Implement custom fetch with progress tracking using fetch streams or a library
3. Consider using a specialized upload library for complex upload scenarios

New Events in htmx 4

• htmx:after:cleanup - Triggered after element cleanup
• htmx:after:history:update - Triggered after history is updated
• htmx:after:process - Triggered after processing an element
• htmx:before:response - Triggered after response headers are available but before the body is read (cancellable)
• htmx:before:settle - Triggered before settle phase begins
• htmx:after:settle - Triggered after settle phase completes
• htmx:after:viewTransition - Triggered after view transition completes
• htmx:finally:request - Always triggered after request completes (success or error)

JavaScript API Changes

The htmx JavaScript API has changed significantly in htmx 4.

Removed API Methods

The following JavaScript API methods have been removed in htmx 4:

Retained API Methods

These methods continue to exist in htmx 4:

• htmx.ajax(verb, path, context) - Issue AJAX requests programmatically
• htmx.config - Configuration object (with new options)
• htmx.registerExtension(name, extension) - Register extensions
• htmx.find(selector) - Find elements (supports extended selectors)
• htmx.findAll(selector) - Find all matching elements (supports extended selectors)
• htmx.onLoad(callback) - a callback that will be called with the newly added content on every swap by htmx
• htmx.on(eventName, handler) - Add event listener
• htmx.parseInterval(str) - Parse interval strings like “1s”, “500ms”
• htmx.process(element) - Process htmx attributes on an element
• htmx.swap(ctx) - Swap content into the DOM (signature changed: now takes a request context object)
• htmx.takeClass(element, className, container) - Take a class from sibling elements
• htmx.trigger(element, eventName, detail) - Trigger custom events

New API Methods

• htmx.forEvent(eventName, timeout) - Returns a promise that resolves when an event fires
• htmx.timeout(time) - Returns a promise that resolves after specified time

Extension API Changes

Extensions in htmx 4 use a new event-based hook system instead of the callback-based API. The method name has also changed from defineExtension() to registerExtension() to avoid conflicts with htmx 2.x.

Key changes:

• Method renamed: htmx.defineExtension() → htmx.registerExtension()
• Event-based hooks instead of callback methods
• Hook names use underscores: htmx_before_request instead of onEvent
• Extensions load by including the script (config whitelist is optional)
• Full request context available via detail.ctx

Extensions will almost certainly need a rewrite. Please see our Extensions documentation and Extension Migration Guide for more information.

HTTP Header Changes

htmx 4 makes some changes to the HTTP headers sent with requests and the response headers it processes. If your server-side code relies on htmx headers, you will need to update it.

Changed Request Headers

HX-Source is the direct replacement for HX-Trigger. If your server was using HX-Trigger to identify which element initiated the request, use HX-Source in htmx 4. Note that the format has changed from just an ID to tagName#id.

Removed Request Headers

The following request headers have been removed in htmx 4:

New Request Headers

Removed Response Headers

The following response headers are no longer processed in htmx 4:

Unchanged Response Headers

The following response headers continue to work the same in htmx 4:

• HX-Trigger - Triggers events immediately on response
• HX-Location - Client-side redirect
• HX-Push-Url - Pushes a URL into history
• HX-Redirect - Full page redirect
• HX-Refresh - Refresh the current page
• HX-Replace-Url - Replaces the current URL in history
• HX-Retarget - Change the target element
• HX-Reswap - Change the swap strategy
• HX-Reselect - Change the content selector

Extension Changes

Loading Extensions

htmx 4 no longer uses the hx-ext attribute. Extensions are activated by including the script file:

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

To restrict which extensions can register, use the extensions config as a whitelist:

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

Server-Sent Events (SSE)

The SSE extension has been rewritten for htmx 4. It now uses fetch() instead of EventSource, hooks into htmx’s standard request pipeline, and replaces sse-connect/sse-swap with hx-sse:connect.

See the SSE extension upgrade guide for full details.

WebSockets (WS)

The WebSocket extension has been rewritten for htmx 4 with a new JSON envelope message format, reference-counted connections, and renamed attributes (ws-connect → hx-ws:connect).

See the WebSocket extension upgrade guide for full details.

Custom Extensions

Extensions in htmx 4 use an event-based hook system instead of the callback-based API. See the Extension Migration Guide for details on rewriting extensions.

Upgrade Music

This is the official htmx 2.x -> 4.x upgrade music: