Upgrading to htmx 4

What you'll build

An upgrade plan for the contacts app, and a version of the delete-row markup that behaves the same in htmx 2 and htmx 4.

The idea

htmx 4.0 shipped on 28 August 2026. htmx 2 stays supported indefinitely, and npm keeps 2.x as latest until some point in early 2027, so you can upgrade when it suits you. The changes that affect most apps:

Steps: read the official guide, run npx [email protected] upgrade-check -- ./templates, rename hx-disable → hx-ignore then hx-disabled-elt → hx-disable, add :inherited (or set htmx.config.implicitInheritance = true temporarily), rename event listeners, and review error handling.

The code

Writing attributes on each element instead of relying on inheritance gives markup that works the same in both versions:

<table><tbody>
  <tr><td>Ada</td><td><button hx-delete="/contacts/1" hx-confirm="Delete Ada?"
      hx-target="closest tr" hx-swap="outerHTML">Delete</button></td></tr>
  <tr><td>Grace</td><td><button hx-delete="/contacts/2" hx-confirm="Delete Grace?"
      hx-target="closest tr" hx-swap="outerHTML">Delete</button></td></tr>
</tbody></table>

<!-- The pretend server: on a real site this part is your backend (Python, PHP, Node, Go...) -->
<script>
  server.delete("/contacts/:id", () => "");
</script>

In htmx 4 the inherited version needs the suffix:

<tbody hx-confirm:inherited="Delete this contact?" hx-target:inherited="closest tr" hx-swap:inherited="outerHTML">

Common mistakes

• Renaming hx-disabled-elt to hx-disable before renaming the old hx-disable to hx-ignore: the two meanings get mixed up.
• Forgetting that error responses now swap: an error page can land in a small target. Add hx-status rules or return small error fragments.
• Upgrading before your extensions (SSE, WebSockets, others) support htmx 4.
• Leaving implicitInheritance on permanently instead of finishing the migration.

Key points

• htmx 2 remains supported; upgrade deliberately.
• Inheritance, event names and error swapping are the main changes.
• Use the upgrade checker and rename attributes in the right order.

Further reading: What's new in htmx 4 · htmx 4.0.0 release · Tutorial: Upgrading to htmx 4