Targets and swaps
Choose innerHTML or outerHTML
Decide whether the target container remains or the response replaces the target element itself.
hx-swap controls how the response meets the target. The two swaps you will use most are innerHTML and outerHTML.
innerHTML keeps the target element and replaces its children:
<ul id="task-list" hx-get="/tasks" hx-swap="innerHTML">
<!-- the response should contain list items -->
</ul>This is the default. Attributes and identity on #task-list remain in place. The list container stays wired for the next refresh.
outerHTML replaces the target itself:
<article id="task-42"
hx-get="/tasks/42/edit"
hx-swap="outerHTML">
...
</article>The response must include a complete valid replacement <article>, including any ID and HTMX attributes needed for later interactions. Returning only its children would remove the component boundary and break the next click.
HTML parsing context matters. A <tr> response belongs inside a table structure, and browsers may move or discard invalid standalone elements. Use <template> wrapping where the out-of-band rules require it, and inspect the resulting DOM. I always check the Elements panel after an outerHTML swap on table rows.
HTMX cannot replace <body> with outerHTML; it falls back to innerHTML. For page-level navigation, use boosted links or a stable child target instead of depending on body replacement semantics.
Choose innerHTML when the container should survive. Choose outerHTML when the whole component, attributes included, is part of the state change, such as swapping a read-only card for an edit form.
Other swap values such as delete and none cover cases where the response body should not become HTML at all. innerHTML and outerHTML remain the pair you will reach for on most screens.
Try this on your own project: perform one swap of each type and confirm whether the original target node still exists afterward.
Lesson completed