iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
htmx 4.0.0 was released on August 28, 2026, but it is not the package published under npm’s latest tag: htmx 2.x remains latest, while htmx 4 is tagged next. That is a release-distribution choice, not a sign that htmx 4 is unreleased. The project says it is holding back the tag to avoid unexpectedly upgrading sites that use non-versioned CDN URLs. For teams considering an upgrade, the main compatibility risks are attribute inheritance, HTTP error-response swapping, history restoration, and renamed or removed events.
Why htmx 4 is not the npm latest version
The htmx project released version 4.0.0 on August 28, 2026, but intends to keep htmx 2.x on npm’s latest tag and htmx 4 on next until some point in early 2027. The stated reason is to avoid unintentionally upgrading websites whose non-versioned CDN URLs resolve to the latest release. A tag determines which version some installation references select; it does not determine whether a numbered release exists. See the official htmx 4.0.0 release announcement and the project’s release framing.
If you are adopting htmx 4, specify the version explicitly rather than relying on an unversioned reference or a moving package tag. The htmx 4 documentation provides versioned installation examples and migration guidance.
What can break when upgrading from htmx 2
The project identifies three major behavioral changes. They can alter behavior even when the markup still loads, so treat this as an application migration rather than a simple file replacement.
Attribute inheritance is explicit by default
In htmx 2, many attributes implicitly applied to descendants. In htmx 4, inheritance is explicit by default. If a parent element is meant to pass an attribute to its children, update it to the explicit :inherited form. Use :append where the intended behavior is to extend an inherited value rather than replace it. The migration documentation also describes htmx.config.implicitInheritance as a compatibility setting for restoring the older default while you stage changes.
Review templates for parent-level attributes whose effects depend on descendant elements. A page can still render while requests, targets, or other inherited behavior silently differ from what the htmx 2 markup intended. The htmx 4 change catalog lists the attribute changes.
HTTP 4xx and 5xx responses swap by default
htmx 4 changes the default handling of HTTP 400 and 500 responses: their response content can be swapped, unlike the htmx 2 default. This affects what users see when the server returns an error, and whether error HTML is inserted into the page. Inspect server-generated 4xx and 5xx responses and verify that their content is appropriate for the swap behavior you intend.
The migration documentation describes htmx.config.noSwap for restoring the old no-swap behavior for status codes such as 204, 304, 4xx, and 5xx. Configure this deliberately rather than assuming all error responses should be suppressed or displayed.
History restoration fetches the page again
htmx 2 restored history from a snapshot in localStorage. In htmx 4, restoring a history entry re-fetches the page from the server and swaps it into the body or configured history element. The project says this avoids restoring DOM mutations made by third-party libraries without restoring those libraries’ JavaScript state.
This changes the assumptions behind browser back and forward navigation: restoration now depends on a server request and the response returned for that history entry. Test navigation with your server’s authentication, caching, and rendering behavior, as well as any third-party code that modifies the DOM. If local restoration is needed, the hx-history-cache extension provides a cache based on sessionStorage.
Event names and event coverage change
Event names are standardized into a htmx:phase:action[:sub-action] pattern. For example, htmx:beforeRequest becomes htmx:before:request, htmx:afterRequest becomes htmx:after:request, and htmx:configRequest becomes htmx:config:request.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The change is broader than renaming those examples: most error events collapse into htmx:error, HTTP response errors use htmx:response:error, htmx:xhr:* events are removed, and validation events give way to native browser form validation. Search JavaScript listeners and hx-on attributes for old event names and verify that each handler still runs at the point your application expects.
XHR-specific code needs review
htmx 4 switches its request implementation from XMLHttpRequest to the native fetch() API. The project says this should be transparent for most users, but the internal change cannot be reverted. Review code that reads XHR-specific properties, listens for XHR events, or otherwise depends on XHR mechanics; those hooks are not a safe assumption in htmx 4.
What is new in htmx 4
New attributes and extensions
The official change catalog lists new attributes including hx-action, hx-method, hx-query, hx-config, hx-ignore, and hx-validate. It also lists extensions including hx-multipart, hx-live, hx-targets, hx-ptag, hx-csp, hx-download, hx-prompt, and hx-history-cache. The SSE and WebSocket extensions have been significantly rewritten, so applications using them should check their markup and behavior against the updated documentation.
The release announcement describes hx-live as a front-end scripting solution inspired by Alpine.js, jQuery, and hyperscript. These additions are options to evaluate against your existing application needs, not a requirement to adopt as part of the major-version upgrade.
Recommended Free Tools
Updated show and scroll syntax
The combined selector:position form for the show and scroll modifiers in hx-swap is no longer supported. Use separate modifiers instead; for example, show:top showTarget:#other or scroll:bottom scrollTarget:#other. Check existing swap declarations that combine a selector and position and revise them to the separate form.
Best Value
A practical htmx 2-to-4 migration sequence
- Pin the version. Update package or CDN references to name the htmx 4 version you intend to deploy. Do not assume that an unversioned URL or npm’s
latesttag selects htmx 4. - Run the upgrade checker. Use the checker linked from the release announcement against templates and JavaScript. It can flag some obsolete attributes, event names, and APIs; review findings rather than treating the scan as proof that the application is compatible.
- Audit inherited attributes. Identify parent-level attributes intended to affect descendants. Make inheritance explicit with
:inherited, use:appendwhen values should extend, or sethtmx.config.implicitInheritanceas a deliberate compatibility measure during staging. - Exercise error responses. Test representative 4xx and 5xx server responses in the browser. Confirm whether their HTML should be swapped, and configure
htmx.config.noSwapif the old no-swap behavior is required for the relevant status codes. - Test history navigation. Use browser back and forward through pages that htmx updates. Confirm that server re-fetches return the right content and that third-party DOM changes or JavaScript state do not leave the restored page inconsistent. Consider
hx-history-cacheonly if local restoration is a desired behavior. - Update event handlers. Search application JavaScript and
hx-onmarkup for renamed events, removed XHR events, and validation hooks. Test request setup, completion, errors, and native form validation after updating listeners. - Review extensions and swap syntax. Compare every extension your application uses with the htmx 4 change catalog, paying particular attention to SSE, WebSockets, and combined
show/scrollmodifiers.
Run these checks in a staging environment with the same templates, server responses, browser navigation paths, and extensions as production. The upgrade checker covers only some obsolete patterns; it cannot establish that application-specific behavior is correct.
How to decide whether to upgrade now
The next tag should not be read as a claim that htmx 4.0.0 is unreleased: the project has released it, while retaining htmx 2.x as npm latest to reduce surprise for sites using non-versioned CDN references. Teams that need htmx 4 can pin it and test the changes above. Teams whose applications depend on implicit inheritance, XHR-specific hooks, old error-response handling, or local history snapshots should account for those dependencies before switching their production version.
The official references are the htmx 4 change catalog, migration documentation, and release announcement.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
