Updating Multiple DOM Elements with htmx Out-of-Band Swaps

The Problem: Updating Secondary UI Elements

In a standard htmx request, the server returns HTML that replaces a single target element. Real-world interfaces, however, often require "side-effect" updates. For example, adding an item to a shopping cart should update the main product list and increment the cart counter in the navigation bar at the same time.

The solution is Out-of-Band (OOB) Swaps. This feature lets a server return multiple HTML fragments in a single response. While one fragment updates the primary target, other fragments—marked as OOB—are swapped into different parts of the page based on their IDs, regardless of where the original request originated.

How OOB Swaps Work

When htmx receives a response, it first processes the primary content for the target element. It then scans the rest of the response for elements carrying the hx-swap-oob="true" attribute. For each OOB element it finds, htmx looks for an existing element in the DOM with a matching id and replaces it.

Implementation Example: Cart Update

Consider a page with a product list and a header containing a cart count. We want to update both when a user clicks "Add to Cart".

Initial page state:

<nav>
  <div id="cart-count">Items: 0</div>
</nav>

<div id="product-list">
  <button hx-post="/add-to-cart/123" hx-target="#product-list">
    Add Item 123
  </button>
</div>

Server response:

Your backend (Node.js, Python, Go, etc.) should return the updated primary target content, followed by the OOB fragment for the cart counter, as a single HTML string:

<!-- Primary target: replaces the #product-list div -->
<div id="product-list">
  <p>Item 123 added successfully!</p>
  <button hx-post="/add-to-cart/123" hx-target="#product-list">
    Add Item 123
  </button>
</div>

<!-- OOB swap: replaces the #cart-count div anywhere on the page -->
<div id="cart-count" hx-swap-oob="true">
  Items: 1
</div>

Configuration Details

• Attribute: hx-swap-oob="true" tells htmx to ignore the primary target and search for a matching ID instead.
• Matching: The id of the OOB element in the response must exactly match the id of the element currently in the browser's DOM.
• Swap method: By default, OOB swaps perform an outerHTML replacement, meaning the entire element (including its tags) is replaced. You can specify another strategy, for example hx-swap-oob="innerHTML", if you only want to replace the element's contents.

Limitations and Common Pitfalls

OOB swaps are powerful, but they introduce specific risks if overused.

The "Missing Target" Failure

An OOB swap only works if the target element already exists in the DOM when the response is processed. If the server sends an OOB fragment for #notification-bell but that element has not been rendered yet (or was removed by a previous swap), htmx silently ignores the fragment. It will not create a new element, and no error is raised—so failures can be easy to miss.

Template Fragmentation

OOB swaps push you toward "fragment templates": the server must be able to render tiny, isolated pieces of HTML rather than full pages. Without a consistent component system, this can lead to duplicated UI logic scattered across many server-side templates, making state changes hard to track.

Payload Bloat

Every OOB fragment adds to the response size. If you find yourself updating many parts of the page on every interaction, consider whether separate targeted requests (triggered via hx-trigger with custom events) would be cleaner than one large multi-fragment response.

Verification and Diagnostics

To verify an OOB swap is working correctly:

1. Open your browser's developer tools and go to the Network tab.
2. Trigger the htmx request.
3. Inspect the Response body. Confirm the OOB element has both a valid id and the hx-swap-oob="true" attribute.
4. Switch to the Elements panel and confirm the target element was replaced without a full page reload.

If the swap does not happen, the most common causes are an ID mismatch between the response fragment and the DOM, or the target element not existing on the page at response time.