Update to htmx 4

Given the overall timings this looks like something we should try to get into 12.0.0

I'm going to update the HTMX object with changes for 4.x. I'm leaving the rebase for @nod_ as the javascript files are branching from an earlier version of those files and I don't want to try to interpret his work.

Reposting a question from Slack for wider discussion:

The default attribute format in htmx 4 is hx- although there apparently is a config that can be set to allow data-hx- We previously decided when working on the POC to go with the second, normative, approach.  The default hx- definitely stands out more when reading the code.  Shall we revisit this?

Adding to #3449808: [12.x] [meta] Requirements for tagging 12.0.0-beta1 after discussions in Slack where HTMX 4 should be stable shortly before we release Drupal 12.

Rebased the feature branch onto the current head of main. htmx-assets.js should be re-checked to verify that I preserved the refactor but brought in appropriately the bug fixes in that file since the feature branch was forked.

Refactored the Htmx class to account for the two new attribute modifiers :inherited and :append

AI Note: I refactored the first htmx attribute building method and then tasked my JetBrains AI agent to repeat the pattern for the remaining methods.

I can't get the yarn.lock to update without adding dev dependencies.

The backend tests now pass. JS tests are failing - I very likely missed something rebasing the JS on changes in main.

All tests passing - waiting for updated releases of htmx 4

Once there's a beta or rc of htmx 4 we could update to that in core on the expectation we'll be able to update again to stable prior to our own stable release.

@catch This MR is currently on 4.0.0-beta2. Michael has improvements coming in the next tag that include restoring data-hx- equally supported as hx- so I'm waiting for the next tag and will update accordingly.

We received an pre-release of beta3 from the HTMX team. I copy/pasted the code into this branch and returned our markup strategy to data-hx- syntax. All tests still pass.

The branch is conflicted with main. I'm going to rebase and resolve and then mark this issue for an initial review.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

I'll update this branch again when the new htmx release is tagged.

Beta3 is released with new features that need to be accounted for in our code.

From Drupal Slack:

This release should be considered RC 1. We don't expect any significant changes on the way to Golden Master in mid-to-late summer.

Rebased and resolving conflicts in asset aggregation tests.

Three un-related tests are failing. If someone who has permission (I no longer can?!) can re-run the failing tests that would be super: https://git.drupalcode.org/project/drupal/-/merge_requests/13668/pipelines

All tests now passing
CR created

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

The only failing test is php 8.6 which is allowed

PHP 8.6 should have been resolved upstream recently with #3588024: PHP 8.6 - Functions mb_regex_encoding() and mb_ereg() are deprecated. You may need to rebase.

Thanks @godotislate! Rebased onto HEAD of main.

Now all tests pass including php 8.6

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

The bot reset this issue due to issues about ckeditor 5 files, but they are not part of this MR.

Bot silenced.

Added some review questions.

Responded to all the comments. I resolved those that were simple feedback. I gave my opinion on those asking about how we should handle our methods that prepare attributes or headers that are now unsupported. I left those open for possible further discussion.

I also commented on the question about Document.parseHTMLUnsafe. Input on that question from more experienced Javascript devs is very welcome!

All tests still passing.

Discussed with @fathershawn and @Michael West in the HTMX meeting in Slack. There are some backward incompatible changes here, and because of name clashes and some large architectural changes it's not trivial to provide full forward/backward compatibility. Given that HTMX adoption is still low I think best-effort is okay here for the Drupal 12 cycle; I added a release note snippet so we can inform end users, and if we can get Rector rules into core (or somewhere else) to help automate custom code upgrades that would be amazing.

Based on both comments on the MR and the discussion referenced in #48, I'm resolving the open comments.

Refactoring for changes in hx-on. CR adjusted.

Back to NR - all tests passing.

Haven't done it but may want to drop no-needs-review-bot as there MR needs rebase.

I ignored the changes in assets as assuming there's nothing custom there.

The CR https://www.drupal.org/node/3583674 is great! Wonder though since there's breaking changes if more code example could help? Overkill maybe?

1 question on the MR but really it's a good MR, I really like that you comment on a lot of the changes. I'd say like 99% there from what I can tell.

Resolved merge conflict and updated htmx to the new RC (beta5)

Nightwatch toolbarApiTest fails - I don't have permission to re-run tests but I don't see how that would be related.

That test passes locally. Uploaded a zipped Nightwatch report.

Started a new pipeline and indeed seems random. All threads appear to be addressed.

Am removing no-needs-review-bot since moving to RTBC.

The Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

Weird I'll put the tag back but guess it depends when a core committer gets to it if it'll be kicked back for a reroll.

Test testInstallProfileConfigOverwrite failed and seems unrelated.

Added some review feedback. Some items in the review were spotted by Claude Code.

I updated the clientside and serverside code around getting the triggering element name based on feedback. An unrelated test is failing: Drupal\Tests\settings_tray\FunctionalJavascript\SettingsTrayBlockFormTest. I don't have permission to re-run tests.

Verified the observation from @longwave at https://git.drupalcode.org/project/drupal/-/merge_requests/13668#note_13...
Added a test to check for the presence of the _wrapper_format query parameter, which does in fact fail.

Added a fix for wrapper format - test passing locally.

core/tests/Drupal/FunctionalJavascriptTests/Core/Htmx/HtmxDynamicFormTest.php failed but passes locally.

All tests passing again

All threads resolved. All tests passing.

htmx 4-beta6 is out. There is this new section (or at least new to me!) in the migration guide: https://four.htmx.org/docs#whats-new We need to re-check that all are accounted for in our code.

These are new and need added methods in the Htmx factory class.

hx-action

Specify URL, with optional hx-method. Supports progressive enhancement via native action/method fallback

hx-method

Specify HTTP method (overrides native method and formmethod)

hx-config

Per-element request config (JSON or key:value syntax)

Fixed up the branch and updated HTMX 4 to beta-6. The CR needs some updating and we need another deprecation child issue

All tests now passing.

We missed hx-status - need to add a method for that.

Added with test - tests passing

Updated the CR.

I think we could update to an HTMX beta in main asap, that way once we hit Drupal 12's beta/rc we're updating to more stable releases than introducing a big change late in the cycle. This is on the basis that HTMX 4 is likely to be at an rc or stable release in December when we actually release 12.0.0 which I'm not sure what the timeline is looking like at the moment. But I'd rather go ahead here than be locked into HTMX 3 until 2030.

@catch I agree. Further, my discussions with HTMX maintainers give me confidence that stable release will land before we are out of D12-beta.

Also, a bit of HTMX humor: We would be stuck on 2.0 as there is not and never will be a 3.0.

OK, I said there would never be a version three of htmx.

But, technically, I never said anything about a version four…

Carson Gross

So where is this work?

1. Tests pass (good)
2. So we're ready for a full critical review, yea?

Here are some comments / things I've found:

1. FormBuilder still reads the removed HX-Trigger request header:

   $hx_trigger = $current_request_headers->get('hx-trigger');
   $target_is_form = str_ends_with($hx_target ?? '', '-form');
   if (!$target_is_form || ($target_is_form && $hx_target !== $hx_trigger)) {
   

   htmx 2 sent that header — `'HX-Trigger': getRawAttribute(elt, 'id')`. htmx 4 does not. In the newly vendored file the request headers are set at lines 450–476 and are `HX-Request`, `HX-Source`, `HX-Current-URL`, plus `HX-Target` and `HX-Request-Type` conditionally. `HX-Trigger` is gone.

   So `$hx_trigger` is always `NULL`, `$hx_target !== $hx_trigger` is always true, and the condition can no longer be false. The out-of-band `form_build_id` swap is now added unconditionally, including in the whole-form-swap case the code deliberately intends to skip, where the build identifier already arrives in the main swap.

   This merge request already handles the same rename correctly in `HtmxRequestInfoTrait::getHtmxSource()`, so `FormBuilder` looks simply to have been missed. The comment block at `FormBuilder.php:782` referencing "Headers `HX-Target` and `HX-Trigger`" needs the same update.

2. `core/misc/htmx/htmx-assets.js:14` — `api` is declared and assigned at line 68 from `internalAPI`, but never read. Leftover from the refactor; ESLint flags it as unused.

Thank you! Nice finds!! I'll give it a tune up and put it back to NR.

1. Addressed the feedback in #79
2. Rebased onto current main

Test failures seem unrelated to this MR.

CKEditor5AllowedTagsTest and EntityReferenceWidgetTest are likely random. OpenTelemetryPerformanceTest might be a legitimate failure that needs adjustment in the performance numbers. We've updated the process to do that: https://www.drupal.org/node/3618676

Thank you for the performance link - only noticed the first two tests so I'll get the metric updated for the third

EntityReferenceWidgetTest is failing, but it is also failing locally on main?

Found and reverted an unintended change. All tests passing.

Two issues are still present on the current head:

• core/misc/htmx/htmx-assets.js:57 still returns doc.documentElement.outerHTML, so every response reaches htmx as a full document.
• The processTarget === null fallback in htmx_after_swap is unchanged.

Green tests are expected here rather than reassuring. Nothing in the suite exercises hx-swap="outerHTML", and inner-style swaps are unaffected because htmx.js:1354 sets strip for them and compensates by accident. Measured in Chrome against 4.0.0-beta6, clicking a control with hx-swap="outerHTML":

current head:  <div><div id="tgt">NEW</div></div>   target lost its id, content nested
returning doc.body.innerHTML instead:
               <div id="tgt">NEW</div>                correct replacement

The cause is #makeFragment at htmx.js:1079 keying off the first tag. It sees html, so fragment.firstElementChild.tagName === 'BODY' and htmx.js:1352 silently upgrades outerHTML to outerSync, which copies attributes from the body wrapper onto the target and wipes the target's own attributes.

Fixing that alone exposes the second item. With the one-line change applied, a real outerHTML swap detaches ctx.target, so ctx.target.parentElement is null, the fallback passes the detached node to htmx.trigger(), and htmx.js:1572 redirects the event to document. Drupal.attachBehaviors then receives document instead of the swapped content:

outerHTML   ctx.target connected: false   parentElement: null      attachBehaviors: document
innerHTML   ctx.target connected: true    parentElement: #parent   attachBehaviors: <div#parent>

These need handling together, since fixing the first turns the second from masked into live. Also worth checking out-of-band swaps, as htmx.js:1111 defaults them to outerHTML.

Happy to supply a FunctionalJavascript test that fails on the current head and passes with the change, if that is the most useful next step.

TL:DR The issue with partials and full documents was an upstream bug. The HTMX team is amazing and @latent has already fixed it and @1cg has committed it: outerHTML swap with body fragment corrupts non-body targets

I'll summarize my understanding of the issue after a Slack discussion with @latent and reading their issue and fix:

We always return a typical HTML document. Even our minimal response includes a <body> tag. Strictly speaking, a body element is required but it does not have to be a <body> tag. HTMX 4 had been written to expect a <body> tag to not be present on an outerHtml swap unless a <body> tag swap was in play. The linked issue fixes this and has more detail but before body attributes were bleeding into targets on on an outerHtml swap.

The second issue gets at the attaching and detaching of drupalBehaviors. My understanding is that our system expects to call Drupal.detachBehaviors on elements about to be removed and Drupal.attachBehaviors.

In v.4 the htmx:before:swap event detail contains a task queue stored as an array. This is built in Htmx.swap and my LLM has correctly summarized the structure as:

Each task includes:

• type: main, partial, or oob
• fragment: the DocumentFragment to insert
• target: the resolved target element
• swapSpec: parsed swap settings
• sourceElement: the request-originating element
• transition: applicable transition state

There are some swap strategies that do not modify their target elements: the various before & after strategies, textContent, none. For the remaining elements, the target is modified and we should pass the target to detach by modifying our existing processor to loop the tasks and check the strategy (See extension events):

Current MR

    htmx_before_swap(elt, { ctx }) {
      // Detach Drupal behaviors from target before swap.
      htmx.trigger(ctx.target, 'htmx:drupal:unload');
    },

Concerning attachment, I think our existing logic could work as now the modified element is inserted our modified without behaviors and going up a level if available should be the right attachment context.

Current MR

    htmx_after_swap(elt, { ctx }) {
      // Attach Drupal behaviors to new content.
      let processTarget = ctx.target.parentElement;
      // Some HTMX swaps put the incoming element before or after ctx.target.
      // We normally target the parent element so that we process the added
      // elements. When there is no parent element or ctx.target is the body,
      // we target the element itself.
      if (ctx.target === document.body || processTarget === null) {
        processTarget = ctx.target;
      }
      htmx.trigger(processTarget, 'htmx:drupal:load');
    },

Those who are monitoring this issue with deeper experience in core and/or JavaScript please comment about what I may be missing here?

I further wonder if we should move our attachBehaviors to the htmx:after:settle event?

From #htmx in Slack

Good morning everyone, happy to announce htmx 4 has been released:
https://four.htmx.org/announcements/2026-08-28-htmx-4.0.0-is-released

- Carson Gross

An additional HTMX attribute is available: hx-query that supports a new HTTP verb QUERY proposed by the IETF: RFC 10008: The HTTP QUERY Method

Adding this to \Drupal\Core\Htmx\Htmx

All tests passing!!

I examined the existing Ajax API and how it deals with behaviors. In that context every operation has an identified wrapper element which becomes the context for any querySelector methods. So I've improved our process of finding the nearest ancestor using newly available data coming from HTMX 4. The default context is document, which is the default context for attach and detach, and is used if there is no parent.

I also improved the Nightwatch tests to verify every swap method works with behaviors attach/detach.

Just increasing priority.

From my perspective, only one tiny thing left, that we can handle in a follow-up

One gap: nothing asserts the invariant that rewrite establishes. I grepped the
branch and found no test covering behavior attach scope.

I have two FunctionalJavascript tests that cover it:

testOuterHtmlSwapDoesNotAttachToDocument
testOutOfBandSwapAttachesBehaviors

They pass against the current head, and both fail if behaviorTarget() is made
to return a detached parent, so they discriminate rather than pass vacuously.
They need a small recorder added to the test_htmx behavior and two routes on
HtmxTestAttachmentsController.

Happy to push them to the merge request, or open a follow-up if you would
rather not expand scope now. No objection to RTBC either way.

I created the follow-up issue #3620247: Add test coverage for Drupal behavior attachment scope after HTMX swaps

There is a merge conflict. Excited to land this ASAP though; I think this has been through enough rounds of review here and any minor edge cases can be handled in followups.

Merge conflict resolved - All required tests passing.

While I still think this work is ready to go, I have some quips about the change record. Mostly additions / extra things to call out:

1. Our own custom events changed shape, and htmx.org will not tell anyone. The Events section points at the upstream migration guide, but htmx:drupal:load and htmx:drupal:unload are ours, and their payload changed from detail.elt to target. Any contrib listener written as:

   htmx.on('htmx:drupal:load', ({ detail }) => {
     doThing(detail.elt);
   });

   now receives undefined and fails silently. This deserves a before/after block, it is the one change in the set that produces no error at authoring time and no upstream documentation.

2. The extension registration API changed, not just hx-ext. The table says "include extension script directly", but htmx.defineExtension() is gone in favour of htmx.registerExtension(name, extension), and the extension shape is now a flat object whose keys are hook names (htmx_config_request, htmx_before_swap, htmx_before_response, and so on). Anyone who shipped an htmx 2 extension needs the new shape, not just a different way to load it. Change notices usually help devs transition from the old state to the new. We should think about what kind of guidance is actually needed here

3. Morph is available and it will silently break once(). Morph is not a breaking change, so it is reasonably out of scope — but people will read "htmx 4" and reach for innerMorph/outerMorph. Morph synchronises attributes, and an attribute on the existing node that is absent from the response markup gets removed. The server never emits data-drupal-once, so a surviving element keeps every bound listener while losing its processed marker, and the next attachBehaviors double-binds. The only protected prefix today is config.morphIgnore = ["data-htmx-powered"]. Worth a warning plus a pointer at morphIgnore or the htmx:before:morph:attr hook until core protects it centrally.

4. There is now a 60 second default request timeout. defaultTimeout: 60000, previously unlimited. Any module issuing long running htmx requests starts failing at one minute with no code change on its side.

5. No builder method for hx-morph-skip or hx-morph-skip-children. Both are new htmx 4 attributes, and the Htmx class has no corresponding methods. Since the convention is that hx-* attributes never appear raw in Twig, there is currently no supported way to fence a region from morphing. We might want to make some kind of mention to morph in the change notice.

6. History behaviour changed by default. The table notes that hx-history was removed with an extension provided, but not that the default itself changed: htmx 4 no longer caches the DOM, so back navigation re-fetches from the server. That is a behavioural change for anyone relying on restore-from-cache, and it interacts with form build identifiers and cross-site request forgery tokens in ways worth a sentence.

Thanks @cosmicdreams for a close reading of the change record. I definitely do not want to hold up the commit, and I do want the CR to be as helpful as possible.

#1) I'm not sure what to say about this and with the caveat that I'm better in PHP than JS, before and after we pass an instance of Element to the htmx.trigger method

#2) Added encouragement for custom JS developers to go read the htmx change doc.

#3) If Drupal devs have properly coded once.remove() in their detach methods, our code will detach and re-attach before and after morphing swaps.

#4 & #6) I've added an unordered list of all the breaking changes listed in the upstream change guide so that if someone has made use of those features in their custom code, they know to look at the upstream doc.

#5) Good catch! As @longwave notes in #99 I created a follow-up: #3620407: Add missing HTMX 4 morph attributes

Added some small feedback points, following both a manual review and a review by Claude Fable 5.1.

@longwave I left one thread open for further thoughts from you and addressed all the other feedback.

I agree, after the license fix. Looks good.

Random test failure: Tests.navigationDisplaceTest

Nice work here everyone, I am so happy that we will get this into the Drupal 12 release.

Committed and pushed 2aa5aede43f to main. Thanks!

Also published the change record.