The htmx team announced the release of htmx 4.0.0, marking the culmination of eight months of development work. The new version represents a significant internal refactoring while maintaining behavioral compatibility with htmx 2.x in most cases.
The modernization effort was sparked when the team decided to build fixi and became more familiar with the fetch() API and async JavaScript programming. According to the announcement, htmx had historically relied on XMLHttpRequest for backwards compatibility. After Christian contributed ideas around streaming HTML, the team began exploring a migration to fetch(), which the team felt would simplify both the library’s internals and extension development.
The behavioral differences between 2.x and 4.x are relatively small, with the team making explicit choices they believe will position htmx-based applications as “100-year web services.”
Three major changes affect users upgrading to 4.0. First, attribute inheritance is now explicit by default rather than implicit. In htmx 2, attributes placed on parent elements would automatically apply to child elements. In htmx 4, developers must add :inherited after attribute names to enable this behavior, such as hx-confirm:inherited. The team notes this will be “the largest upgrade burden” and has provided a command-line tool to identify locations requiring this modification.
Second, htmx event names have been standardized and reorganized. Events now follow the pattern htmx:phase:action[:sub-action]. For example, htmx:beforeRequest becomes htmx:before:request. Most error events collapse into htmx:error, while HTTP error responses fire htmx:response:error. The htmx:xhr:* events are removed since htmx 4 uses fetch().
Third, history support no longer uses localStorage by default. In htmx 2, page snapshots were cached in localStorage for restoration, but this often included DOM mutations from third-party libraries that caused issues. In htmx 4, back navigation re-fetches pages instead. A new hx-history-cache extension restores history from sessionStorage for those preferring local caching.
New features include morph swaps for seamless DOM updates and the <hx-partial> tag for clearer multi-element updates. The release also introduces numerous new extensions, including hx-preload, hx-download, hx-alpine-compat, and streaming HTML extensions for SSE, WebSockets, and multipart responses. A new scripting solution called hx-live offers HATEOAS-friendly reactivity inspired by Alpine.js and jQuery.
The team is not marking 4.0 as latest on NPM to avoid forcing upgrades for users relying on non-versioned CDN URLs. Version 2.x will remain the latest release while 4.0 stays marked as “next” until early 2027. An upgrade tool is available to help identify needed changes: npx [email protected] upgrade-check.
Key facts
- htmx 4.0.0 internally migrated from XMLHttpRequest to the fetch() API
- Attribute inheritance now requires explicit
:inheritedsuffix instead of being implicit by default - Event naming standardized to
htmx:phase:action[:sub-action]pattern - History support no longer caches pages in localStorage by default
- New features include morph swaps and
<hx-partial>tag - Version 2.x remains latest on NPM; 4.0 marked “next” until early 2027
- Command-line upgrade tool available to identify required changes