Swapping with HTMX: Making Dynamic Content Changes Effortless

Today, I dove into HTMX’s hx-swap attribute, discovering how to dynamically place and update HTML in various parts of a webpage with a simple attribute. HTMX’s default behavior replaces the content within an element (similar to innerHTML), but the options go much further. Here’s a quick rundown of the different ways to use HTMX swapping, with examples for each case.

1. The Basics: innerHTML Swap

When you request data with HTMX, the returned HTML by default replaces the content within the target element. This innerHTML method is perfect for updating an existing section without affecting the layout.

<div hx-get="/example" hx-swap="innerHTML">Content will be replaced here.</div>

Imagine having a notification area, and every time you get new messages, the area simply refreshes. This is simple and clean—no layout shuffling required!

2. Complete Replacement: outerHTML

When you need a full replacement of an element, outerHTML swaps the entire element, including its tags. This is great for cases where the entire structure, not just the content, needs an update.

<div hx-get="/example" hx-swap="outerHTML">Replace this whole box</div>

This is ideal for cases like swapping out entire modals or card elements where styling and structure might change based on user interaction.

3. Positioning New Content: beforebegin, afterbegin, beforeend, afterend

Want to control precisely where new content appears? These four options allow you to inject content in and around a target.

Before the Target (beforebegin):

Adds content just before the element.

<div class="todo-item" hx-get="/new-item" hx-swap="beforebegin">
  <p>Existing To-Do Item 1</p>
</div>

Rendered result:

<div class="todo-item">
  <p>New To-Do Item from /new-item</p>
</div>
<div class="todo-item">
  <p>Existing To-Do Item 1</p>
</div>

At the Beginning Inside the Target (afterbegin):

Places content inside, at the very start.

<div class="todo-list" hx-get="/new-item" hx-swap="afterbegin">
  <div class="todo-item">
    <p>Existing To-Do Item 1</p>
  </div>
</div>

Rendered result:

<div class="todo-list">
  <div class="todo-item">
    <p>New To-Do Item from /new-item</p>
  </div>
  <div class="todo-item">
    <p>Existing To-Do Item 1</p>
  </div>
</div>

At the End Inside the Target (beforeend):

Adds content to the end of the target’s content.

<div class="todo-list" hx-get="/new-item" hx-swap="beforeend">
  <div class="todo-item">
    <p>Existing To-Do Item 1</p>
  </div>
</div>

Rendered result:

<div class="todo-list">
  <div class="todo-item">
    <p>Existing To-Do Item 1</p>
  </div>
  <div class="todo-item">
    <p>New To-Do Item from /new-item</p>
  </div>
</div>

After the Target (afterend):

Inserts content after the target element.

<div class="todo-item" hx-get="/new-item" hx-swap="afterend">
  <p>Existing To-Do Item 1</p>
</div>

Rendered result:

<div class="todo-item">
  <p>Existing To-Do Item 1</p>
</div>
<div class="todo-item">
  <p>New To-Do Item from /new-item</p>
</div>

4. Deleting Elements with delete

If you need to remove an element upon a certain action, the delete option handles this perfectly, clearing the target from the DOM entirely.

<div hx-get="/example" hx-swap="delete">Delete this element</div>

This is handy for dismissing notifications, temporary warnings, or anything that’s better removed after a user acknowledges it.

5. Keeping Things Simple: none

For those times when you’re just after a background effect or event without changing content, none allows HTMX to handle the request without appending or swapping the response HTML.

<div hx-get="/example" hx-swap="none">Trigger action but don’t update</div>

This option is great when you need to send data or fire events but don’t want the target content affected.

Swapping Magic with HX Response Headers

HTMX offers more than just swapping elements directly. With HX Response Headers, you can add behaviors like history management, client-side redirects, and custom event triggers—all without extra JavaScript. Here’s a closer look at some of these headers with examples to make each use case clear.

HX-Location - Client-Side Redirects

If you want to redirect a user to a new page after a request without reloading, HX-Location does the job. For instance, after a successful login, you might want to redirect the user to their dashboard:

HTTP/1.1 200 OK
HX-Location: /dashboard

With this header in place, HTMX will load the new URL (/dashboard) on the client side, seamlessly navigating without a full page reload.

HX-Push-Url and HX-Replace-Url - Managing Browser History

These headers allow you to update the browser’s history after a successful request, making your single-page experience feel like traditional navigation.

1. HX-Push-Url: Adds a new URL to the history stack. Imagine a to-do list where each item has its own URL:

HTTP/1.1 200 OK
HX-Push-Url: /todos/123

This will push /todos/123 into the history stack, so users can navigate back to this exact list item by using the back button.

2. HX-Replace-Url: Updates the current URL without adding a new entry to the history stack. For example, updating a filter on a product list might change the URL to reflect the current filter state:

HTTP/1.1 200 OK
HX-Replace-Url: /products?filter=new

Here, the URL updates to show /products?filter=new without cluttering the history with each filter adjustment.

HX-Trigger - Custom Events After Swaps

With HX-Trigger, you can fire custom events once a swap completes, adding interactivity without extra JavaScript. Suppose you have a notification area that updates with a new message. You could trigger an animation to highlight the update:

HTTP/1.1 200 OK
HX-Trigger: flashNotification

This would dispatch a flashNotification event on the target element, where you can handle custom animations or behaviors in CSS or JavaScript.

Out-of-Band Swaps (hx-swap-oob) - Updating Multiple Elements

Sometimes, you need to update multiple areas in response to one action. For instance, if a user’s profile information changes, you might want to update a summary section elsewhere on the page. Out-of-Band Swaps allow you to target these secondary elements directly:

<div id="user-summary" hx-swap-oob="true">Updated user info</div>

Using hx-swap-oob="true", the response content for #user-summary will be updated, even if the original action targeted a different element. This way, you can synchronize updates across the page without additional requests.

Timing and Transition Tricks

HTMX’s swap and settle options let you delay swaps and coordinate with CSS transitions. For instance, with swap:1s, you can wait one second before content swaps in, making for smooth visual effects.

<div hx-get="/example" hx-swap="innerHTML swap:1s">Wait, then swap!</div>

This trick is incredibly helpful if you want your UI changes to feel polished and responsive.