Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 28 ยท HTMX Basics

Targets and Swap Strategies

Control where HTMX puts server HTML: hx-target selectors, every hx-swap strategy, swap modifiers, hx-select and out-of-band updates with hx-swap-oob.

By default HTMX takes the HTML a server returns and puts it inside the element that made the request. That is a fine start, but real pages need more control. A button in a table row should update the row, not itself. A "load more" link should add items to the end of a list. Saving a form should also refresh a counter in the page header.

Two attributes give you that control: hx-target decides which element receives the response, and hx-swap decides how the response is put there. A third idea, out-of-band swaps, lets one response update several places at once. You already know how to send a request from Your First HTMX Request and Verbs, Triggers and Parameters; this lesson is about where the answer lands.

Every example below includes a few lines of mock server, as explained in Setting Up. In your own project, delete that block and let your backend answer the same URLs.

Choosing the target with hx-target

hx-target takes a CSS selector. hx-target="#result" swaps into the element with the id result. Besides plain selectors, HTMX understands a few relative forms that are very handy inside repeated markup, where ids would clash:

Value Meaning
this The element that has the attribute (also the default target)
closest <selector> The nearest ancestor (or the element itself) that matches
find <selector> The first matching descendant of the element
next <selector> The next matching element later in the document
previous <selector> The closest matching element earlier in the document

Relative targets keep your markup free of ids. A row can say hx-target="closest tr" and the same HTML works for a thousand rows.

Relative targets

The first card's button targets next .out, the following element with that class. The second replaces the entire card, because closest .card is the card itself. In the third card the click handler sits on the card, so the target is found inside it with find.

Choosing the swap with hx-swap

The default strategy is innerHTML: the target's children are replaced. hx-swap selects another one. The values are the building blocks of every HTMX interface, so learn them as a set.

Replace strategies

innerHTML Replace the children of the target. The default.
outerHTML Replace the target element itself.
textContent Insert the response as plain text, no parsing.

Use outerHTML when the response contains the element's own tag.

1 / 3

Try the main ones on a small list. Each button asks the server for a new list item, and only the swap strategy differs.

Swap strategies on a list

Press "beforeend" a few times and new items appear at the bottom; "afterbegin" puts them on top. "outerHTML" swaps the first li itself, so the replacement carries its own class. "delete" removes the last item without looking at the response, and "none" does nothing visible at all. If you delete every item, the next li:last-child target no longer exists and HTMX logs a htmx:targetError event in the console instead of swapping.

Use outerHTML when the server returns a complete element (a table row, a card) and innerHTML when it returns only the contents. Mixing them up is the most common swap bug: you get a card nested inside a card.

Swap modifiers

After the strategy name you can add modifiers separated by spaces. They fine-tune timing and scrolling:

Modifier Effect
swap:1s Wait before swapping. During the wait the target has the class htmx-swapping, ideal for fade-out CSS
settle:1s Time between swapping and the end of the "settling" phase (default 20ms)
scroll:top or scroll:bottom Scroll the target to its top or bottom after the swap
show:top or show:bottom Scroll the page so the target's top or bottom is visible
transition:true Use the browser's View Transitions API when available
ignoreTitle:true Do not update document.title from a <title> in the response

A classic use is a chat or log box that should stay scrolled to the newest line:

Scroll a log to the bottom

Add six or seven lines with the first button and the box stays pinned to the newest one. With the second button the new lines pile up out of view. The "Clear" button waits 300 ms before swapping, and the CSS rule for .htmx-swapping fades the old content out in the meantime. The loading states lesson goes deeper into those state classes.

Picking part of the response with hx-select

Sometimes the server returns a whole page, but you want only one piece. hx-select takes a CSS selector that is applied to the response, and only matching elements are swapped in. It is a quick way to reuse existing full-page routes while you migrate an old site, though a dedicated fragment route is usually cleaner and lighter on the wire.

HTML
<a href="/articles?page=2"
   hx-get="/articles?page=2"
   hx-select="#article-list"
   hx-target="#article-list"
   hx-swap="outerHTML">Next page</a>

If the selector matches nothing in the response, nothing is swapped.

Out-of-band swaps

An ordinary response goes to one target. An out-of-band (OOB) swap is a piece of the response that goes somewhere else. Mark an element in the response with hx-swap-oob and HTMX pulls it out and swaps it into the element in the current page that has the same id. The rest of the response is swapped normally.

The value true means "replace by outerHTML". You can also give a strategy and a selector, such as hx-swap-oob="beforeend:#toast-area".

Use OOB swaps whenever one action changes several unrelated parts of the page: a shopping cart badge in the header, a flash message, a counter next to a list.

sequenceDiagram
    participant B as Browser
    participant S as Server
    B->>S: POST /add
    S-->>B: li fragment + span id=count hx-swap-oob
    B->>B: li goes to the normal target
    B->>B: span replaces #count elsewhere

One response, two destinations: the main target and an out-of-band element.

Update a list and a counter at once

The normal target (#cart) only receives the <li>. The span and the div carry hx-swap-oob, so HTMX removes them from the response and swaps them into the header badge and the note area. For hx-swap-oob="innerHTML" on the note, only its contents are replaced, so the div itself stays in place.

OOB elements are matched by id. If the page has no element with that id, the OOB part is silently dropped. Also remember that a hx-swap="none" request still processes OOB parts, which makes none a handy choice for buttons that only update counters.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A delete button inside a table row should replace its own row with the server's response. Which pair of attributes fits best?

    closest tr finds the row containing the button, and outerHTML replaces the row element itself (an empty response removes it).
  2. 2. What is the default swap strategy when you do not write hx-swap?

    HTMX replaces the children of the target (innerHTML) unless you choose a different strategy.
  3. 3. A response contains a normal fragment and a span with id="count" and hx-swap-oob="true". What happens to the span?

    Out-of-band elements are lifted out of the response and swapped into the matching id in the current document.
  4. 4. What does hx-swap="beforeend scroll:bottom" do?

    beforeend appends inside the target, and the scroll:bottom modifier scrolls the target to its bottom after the swap.
  5. 5. Which attribute lets you keep only part of a full-page response?

    hx-select applies a CSS selector to the response and swaps only the matching elements.

Summary

  • hx-target picks the receiving element: a selector, this, or a relative form such as closest, find, next and previous.
  • hx-swap picks the strategy: innerHTML (default), outerHTML, textContent, beforebegin, afterbegin, beforeend, afterend, delete and none.
  • Modifiers such as swap:, settle:, scroll:, show: and transition:true adjust timing and scrolling.
  • hx-select keeps only the matching part of the response.
  • hx-swap-oob lets one response update other elements by id, even with hx-swap="none".

Continue with Forms, Validation and Submissions.