Update Multiple DOM Elements from One htmx Response with Out-of-Band Swaps

The problem: one action, several stale regions

When a user saves a form, the primary content area is not the only part of the page that becomes stale. A notification badge, a sidebar count, or a status message may all need to reflect the new state. A normal htmx request replaces one target element. If you fire separate requests for each region, you multiply latency and risk partial failures. htmx solves this with out-of-band (OOB) swaps: the server returns the primary fragment plus additional elements marked with hx-swap-oob, and htmx updates every matching element in the same response cycle.

Desired outcome

After a single user action, the browser updates a primary target element and one or more secondary elements elsewhere in the DOM without a full page reload. The secondary updates are driven entirely by the server response, so the client markup stays declarative and the server remains the source of truth for UI state.

Prerequisites

• htmx loaded on the page (a recent stable release; hx-swap-oob has been a core feature for several major versions).
• A server endpoint that returns partial HTML fragments, not a full HTML document.
• Unique id attributes for every element you intend to update. OOB matching is strictly by ID.
• Basic familiarity with htmx attributes such as hx-post and hx-target.

Focused procedure

1. Define the primary trigger

Start with the element that initiates the request. It targets the main content region as usual.

<button hx-post="/items/42/update"
        hx-target="#main-content">
  Save changes
</button>

Place this in your application's HTML templates. No special permissions are required beyond normal page rendering.

2. Shape the server response

The endpoint must return a fragment for the primary target plus one or more OOB elements. htmx processes the primary swap first, then applies OOB swaps after it completes.

<div id="main-content">
  <h2>Item 42 updated</h2>
  <p>The record was saved.</p>
</div>

<span id="notification-badge" hx-swap-oob="true">3</span>

<div id="alert-region" hx-swap-oob="outerHTML">
  <div class="alert alert-success">Changes saved.</div>
</div>

Implement this in your server route or controller. The response Content-Type should be text/html so htmx treats the payload as swappable content.

3. Choose the OOB swap method

The value of hx-swap-oob controls how the matching element is updated:

Value	Behavior	Typical use
true or innerHTML	Replaces the inner content of the matched element	Updating a badge count or text label
outerHTML	Replaces the matched element itself, including its tag	Changing an element's classes or structure
delete	Removes the matched element from the DOM	Dismissing a temporary row or notice

If you omit the value, htmx defaults to innerHTML.

4. Remove obsolete elements

To delete an element, return a fragment with hx-swap-oob="delete". The content inside is ignored.

<div id="stale-notice" hx-swap-oob="delete"></div>

Expected checks

After triggering the request, verify the behavior:

1. Network payload. Open your browser's DevTools Network tab, select the request, and inspect the Response. You should see multiple top-level elements: the primary fragment and at least one element carrying hx-swap-oob.
2. Primary swap. Confirm the element referenced by hx-target (for example, #main-content) contains the new server-rendered content.
3. OOB swap. In the DevTools console, run:

   document.getElementById('notification-badge').textContent

   Expected result: the string "3" (or whatever value the server returned). Run this in the browser console after the request completes; no special permissions are needed.
4. No reload. The page should not perform a full navigation. Only the targeted regions change.

To inspect the raw response before wiring it to htmx, run the following in your terminal (requires network access to the server):

curl -X POST https://example.com/items/42/update \
  -H "Content-Type: application/json" \
  -d '{"status":"saved"}'

Expected check: the output is an HTML fragment containing hx-swap-oob, not a full <html> document. Risk: if the endpoint returns a complete page, htmx may not locate the intended fragments.

Recovery options and limitations

• OOB element did not update. Check that the id in the response exactly matches the id in the live DOM. IDs are case-sensitive. Also confirm the server did not return a full HTML page; if it did, htmx may extract the wrong fragment or fail silently.
• Unpredictable updates. Duplicate IDs in the DOM break OOB matching. htmx will update one of the matching elements, but which one is not guaranteed. Audit your templates for duplicate IDs before relying on OOB.
• Layout jumps. If an OOB swap changes an element's height or width, surrounding content may shift. Mitigate this with CSS transitions, reserved space, or by swapping only text content when possible.
• Ordering. OOB swaps run after the primary target swap. If your OOB element depends on the primary swap having completed, that ordering is guaranteed; when multiple OOB elements are present, they are applied in the order they appear in the response.
• Rollback. OOB swaps change DOM state but do not alter server data. To revert a UI change, issue another request that returns the previous state, or reload the page. There is no automatic client-side undo.

Version assumptions and verification

This guide assumes a recent stable htmx release where hx-swap-oob is part of the core distribution. Because htmx continues to evolve, verify against the version bundled in your project by checking the htmx script tag or the htmx.version property in the browser console. If you are using an older or customized build, confirm that OOB processing is enabled before deploying dependent UI patterns.