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