Targets and swaps
Choose innerHTML or outerHTML
Decide whether the target container remains or the response replaces the target element itself.
8 minute lesson
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.
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.
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.
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.
Lesson completed