3 min read htmx 4.0

htmx 4.0 ships, but npm is keeping new installs on 2.x

Pinning htmx 4.0 changes what happens to error responses, what hx-disable means, and how long requests wait before timing out.
News banner reading “htmx 4.0 ships, but npm keeps new installs on 2.x,” beside the htmx logo and an npm dist-tags panel showing latest at 2.0.10 and next at 4.0.0 until early 2027.

The htmx team released htmx 4.0 on August 28. It is stable and available now, though npm still serves htmx 2.0.10 under the latest tag. Version 4.0.0 is tagged next, where the maintainers expect it to remain until early 2027.

The delay protects sites that load htmx through an unversioned CDN URL. Moving latest immediately could change their runtime without a package-lock update or a planned deployment. Teams that want version 4 can pin it in their package manager or use the release's versioned CDN path:

<script src="https://unpkg.com/htmx.org@4.0.0/dist/htmx.min.js"></script>

The project describes three headline changes: explicit attribute inheritance, renamed events, and the removal of the localStorage history cache. Its complete htmx 4 change catalog is longer. Error responses, timeouts, extension loading and several existing attributes also behave differently.

Check error responses, hx-disable and inheritance first

htmx 4 swaps every HTTP response into the target except 204 and 304. Version 2 did not swap 4xx or 5xx responses. A server-rendered 422 validation fragment may now work without extra response handling, but a full HTML error page returned with 500 can also land inside a component.

Applications can define behavior per status code with the new hx-status attribute. To retain the old default while migrating, set:

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

The hx-disable change is easier to miss because the name still exists. In version 2, hx-disable told htmx not to process an element. That role moves to hx-ignore. In version 4, hx-disable takes over the old hx-disabled-elt job of disabling elements during a request. The official guide says to rename old hx-disable uses before converting hx-disabled-elt, otherwise valid markup can silently acquire the wrong behavior.

Attribute inheritance is the largest stated migration item. Parent attributes no longer flow to descendants unless they carry an :inherited suffix. A shared hx-confirm, for example, becomes hx-confirm:inherited. Teams can temporarily restore the version 2 behavior with htmx.config.implicitInheritance = true.

The smaller defaults can still break a request

Version 4 introduces a 60-second default timeout. Version 2 waited indefinitely. Applications with legitimate long-running requests can restore the old setting with htmx.config.defaultTimeout = 0, or choose a more suitable limit.

There are several other checks worth making:

  • hx-delete no longer includes inputs from its enclosing form. Add hx-include="closest form" where the request needs them.
  • Main content now swaps before out-of-band content. OOB swaps and <hx-partial> elements follow in document order.
  • hx-ext has been removed. Extensions load by including their scripts directly.
  • Event names now use forms such as htmx:before:request and htmx:after:swap; XHR-specific events are gone after the internal move to fetch().
  • Attributes including hx-vars, hx-params, hx-prompt, hx-request and hx-history have been removed or replaced.

Back navigation also returns to the server. Instead of restoring a page snapshot from localStorage, htmx fetches the page and swaps it into <body>, or into [hx-history-elt] when that element exists. The hx-history-cache extension is available for applications that still want local snapshots in sessionStorage.

htmx ships an official checker for the mechanical part of the migration:

npx htmx.org@4.0.0 upgrade-check -- ./templates

It scans .html, .php, .js, .ts, .jinja, .jinja2, .j2, .erb and .hbs by default. Additional formats can be supplied with --ext. The tool flags inherited attributes, renamed attributes, removed APIs and old event names. Runtime behavior such as response swapping and OOB order still needs application tests.

Compatibility switches leave room to move gradually

Teams do not have to convert every version 2 convention on the first pass. The htmx-2-compat extension restores version 2 defaults and event names on htmx 4, while the individual config settings let applications keep selected old behaviors during a staged migration. The project has also committed to supporting htmx 2 indefinitely.

Version 4 also adds built-in morph swaps with innerMorph and outerMorph, per-status-code swap rules, the <hx-partial> element for targeting several parts of a page from one response, and optional View Transitions support. New extensions cover streaming, history caching and the hx-live scripting model.

The npm tag gives teams time, not proof of compatibility. Pin 4.0, run the checker, then test error pages, inherited attributes, long requests, extensions and navigation against the application itself.

Published by:

Rajeev R Sharma

Member discussion