Skip to content

docs: clarify HX-Retarget interaction with hx-swap="none" (#3446)#3771

Open
manwithacat wants to merge 1 commit into
bigskysoftware:masterfrom
manwithacat:fix/docs-hx-retarget-with-swap-none
Open

docs: clarify HX-Retarget interaction with hx-swap="none" (#3446)#3771
manwithacat wants to merge 1 commit into
bigskysoftware:masterfrom
manwithacat:fix/docs-hx-retarget-with-swap-none

Conversation

@manwithacat

@manwithacat manwithacat commented Apr 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Fixes #3446.

Background

The issue reporter set hx-swap="none" on a form, then expected an HX-Retarget response header to cause a swap to happen at the new target. Tracing the code (src/htmx.js:4848–4929):

  1. responseHandling.swap is true for the 2xx response, so the swap block is entered.
  2. HX-Retarget updates responseInfo.target to the new selector.
  3. getSwapSpecification(elt, swapOverride) reads hx-swap="none" from the source element.
  4. swapWithStyle('none', ...) returns immediately — no DOM change at the new target.

This is intentional and consistent: HX-Retarget is a "where" header, not a "whether" header. The none swap style applies at the new target just as it would have at the original. The reporter even noted in their suggestion: "If this is the expected behavior, I would update the docs to include that setting hx-swap='none' will prevent the use of a swap via HX-Retarget."

The fix

This PR is exactly that doc update. Two single-line edits in the response-headers tables:

  • www/content/docs.md — adds a clarifying sentence to the HX-Retarget entry, pointing users at HX-Reswap for the "swap was 'none', but I want to swap at the new target" case.
  • www/content/reference.md — same clarification, parenthetical form to match the table style.

Docs-only, no code change. Targeting master per CONTRIBUTING.md.

What I'm not changing, and why

The behavior itself isn't a bug. Making HX-Retarget implicitly override hx-swap="none" would be a backwards-incompatible change to a header whose contract is well understood by the wider htmx ecosystem (extensions, frameworks, server libraries). Any user who genuinely wants the source's swap style overridden already has the right tool: HX-Reswap.

Checklist

  • I have read the contribution guidelines
  • I have targeted this PR against the correct branch (master for website changes, dev for
    source changes)
  • This is either a bugfix, a documentation update, or a new feature that has been explicitly
    approved via an issue
  • I ran the test suite locally (npm run test) and verified that it succeeded
@manwithacat @claude
docs: clarify HX-Retarget interaction with hx-swap="none" (bigskysoft…
0c6f20e 
…ware#3446)

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) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant

@manwithacat