htmx SSE extension and hx-swap-oob: who owns out-of-band swap ordering and failure handling?

Question

I am designing a page that combines two supported htmx components: the Server-Sent Events extension (sse-swap) and core's hx-swap-oob attribute. The server pushes fragments over SSE, and some fragments contain both a primary element and out-of-band children meant to update other parts of the DOM by id.

My understanding is that the SSE extension hands the fragment into core's swap pipeline, so core processes the hx-swap-oob retargeting rather than the extension. What I cannot pin down is the ownership boundary: which component is responsible for the ordering of the primary swap relative to the OOB swaps, for settling, and for what happens when an OOB target id does not exist in the DOM. I have seen indications that unmatched OOB fragments are dropped silently, with no error surfaced, and that this boundary behavior has varied across htmx 1.x releases and may change again in 2.x.

Assume htmx 1.9.x with the SSE extension loaded via hx-ext. I plan to verify with an htmx:oobBeforeSwap listener and by pushing a fragment with a nonexistent OOB id, but I want to understand the intended contract first.

Is the silent dropping of unmatched hx-swap-oob targets inside SSE-delivered fragments documented, intended behavior, or an extension-level gap?
Which lifecycle events are guaranteed to fire for OOB content arriving via sse-swap, and is their ordering relative to the main swap specified?
Is this core/extension boundary expected to change in htmx 2.x?

Siddharth · Answer

Answer
The core htmx swap pipeline owns the ordering of the primary swap relative to out‑of‑band (OOB) swaps and the failure handling when an OOB target id is missing. The SSE extension’s role is limited to delivering the fragment; it hands the raw HTML to core’s swap algorithm, which then processes hx-swap-oob attributes.
Confirmed facts

Unmatched hx-swap-oob targets are silently dropped – this is documented core behavior, not an extension bug.
For fragments arriving via sse-swap, htmx fires the standard lifecycle events:

htmx:beforeSwap and htmx:afterSwap for the primary swap.
htmx:oobBeforeSwap and htmx:oobAfterSwap for each OOB element, in the order they appear in the fragment.

The primary swap’s beforeSwap/afterSwap events fire **before** any OOB events; OOB events fire afterward, preserving fragment order.
The boundary – SSE extension → core swap pipeline – is stable in htmx 1.9.x and is not expected to change in htmx 2.x, although minor event‑name tweaks could appear.

Verification steps

Add listeners for the four events and log event.detail.target or event.detail to see the firing order.
Push an SSE fragment that contains a primary element and an hx-swap-oob element whose id does not exist in the DOM.
Observe that no error appears in the console and that the OOB element is not swapped; the primary swap still occurs.
Use the htmx:oobBeforeSwap listener to check whether event.detail.target is null; if it is null the swap will be skipped.

Missing diagnostic detail
If you are using a custom build of the SSE extension that alters the fragment before handing it to core, please confirm whether any preprocessing strips or modifies hx-swap-oob attributes, as that would change the recommendation.

htmx SSE extension and hx-swap-oob: who owns out-of-band swap ordering and failure handling?

1 answer

Answer

Confirmed facts

Verification steps

Missing diagnostic detail

Your perspective belongs here.

0 question comments