From 0c6f20e2b223c52195c1a44b526d33d8a963dcf4 Mon Sep 17 00:00:00 2001 From: James Barlow <332269+manwithacat@users.noreply.github.com> Date: Fri, 24 Apr 2026 13:00:30 +0100 Subject: [PATCH] docs: clarify HX-Retarget interaction with hx-swap="none" (#3446) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HX-Retarget only changes *where* the swap happens — the swap style is still determined by the source element's hx-swap (or by HX-Reswap). When the source uses hx-swap="none", retargeting alone produces a no-op because the "none" swap style applies at the new target too. Updates the HX-Retarget entries in both docs.md and reference.md to spell this out and point users at HX-Reswap. The behavior itself is intentional and consistent — only the docs were silent on this combination. The original issue reporter noticed the surprise and explicitly suggested "I would update the docs to include that setting hx-swap='none' will prevent the use of a swap via HX-Retarget." Co-Authored-By: Claude Opus 4.7 (1M context) --- www/content/docs.md | 2 +- www/content/reference.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/www/content/docs.md b/www/content/docs.md index 6889666c0..dd61757c6 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -1038,7 +1038,7 @@ htmx supports some htmx-specific response headers: * `HX-Refresh` - if set to "true" the client-side will do a full refresh of the page * [`HX-Replace-Url`](@/headers/hx-replace-url.md) - replaces the current URL in the location bar * `HX-Reswap` - allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values -* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page +* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page. Note that this only changes *where* the swap happens; the swap style is still determined by the source element's [`hx-swap`](@/attributes/hx-swap.md) (or `HX-Reswap`). If the source uses `hx-swap="none"`, you also need to send `HX-Reswap` to make the swap actually occur at the new target. * `HX-Reselect` - a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element * [`HX-Trigger`](@/headers/hx-trigger.md) - allows you to trigger client-side events * [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) - allows you to trigger client-side events after the settle step diff --git a/www/content/reference.md b/www/content/reference.md index 8810b0b24..f8275844d 100644 --- a/www/content/reference.md +++ b/www/content/reference.md @@ -116,7 +116,7 @@ All other attributes available in htmx. | `HX-Refresh` | if set to "true" the client-side will do a full refresh of the page | [`HX-Replace-Url`](@/headers/hx-replace-url.md) | replaces the current URL in the location bar | `HX-Reswap` | allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values -| `HX-Retarget` | a CSS selector that updates the target of the content update to a different element on the page +| `HX-Retarget` | a CSS selector that updates the target of the content update to a different element on the page (only changes *where* the swap happens; combine with `HX-Reswap` if the source has `hx-swap="none"`) | `HX-Reselect` | a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element | [`HX-Trigger`](@/headers/hx-trigger.md) | allows you to trigger client-side events | [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) | allows you to trigger client-side events after the settle step