htmx 4 attribute audit (issue #7)¶

Audit of every hx-* attribute used in shared_calendar/templates/ on branch migrate-to-htmx4 (commit 193e1fc) against htmx 4.0.0.

Date: 2026-09-20. No repo convention existed for research notes, so this lives in docs/research/.

Sources (all primary)¶

• [S1] htmx 4 docs, What's New in htmx 4 — https://four.htmx.org/docs/whats-new-in-htmx-4
• [S2] htmx 4 attribute reference index — https://four.htmx.org/reference/attributes/
• [S3] hx-swap reference — https://four.htmx.org/attributes/hx-swap/
• [S4] hx-vals reference — https://four.htmx.org/attributes/hx-vals/
• [S5] hx-swap-oob reference — https://four.htmx.org/attributes/hx-swap-oob/
• [S6] hx-boost reference — https://four.htmx.org/attributes/hx-boost/
• [S7] hx-trigger reference — https://four.htmx.org/attributes/hx-trigger/
• [S8] hx-sse extension docs — https://four.htmx.org/extensions/sse/
• [S9] htmx 4.0.0 source, htmx.org@4/dist/htmx.js (unpkg), line numbers below
• [S10] hx-sse extension source, htmx.org@4/dist/ext/hx-sse.js (unpkg)

Nothing here is from memory; every claim is either quoted from the htmx 4 docs or read out of the shipped 4.0.0 source.

What is actually in use¶

Swept with git grep -o -E 'hx-[a-z-]+(:[a-z]+)?=' migrate-to-htmx4 -- shared_calendar/templates:

Distinct value patterns:

• hx-swap: innerHTML (16) and innerHTML transition:true (14).
• hx-target: #dialog-container (16), #wishlist-list (2). No this/closest/ extended selectors, no selectors containing spaces or commas.
• hx-get/hx-post: plain {% url %} values; one carries a query string (…?kind={{ value }}).
• hx-push-url: a URL path (not true).
• hx-vals: js:{kind: new URLSearchParams(location.search).get("kind") || "all"} (items/wishlist/wishlist_page.html).
• hx-swap-oob: outerHTML:.filter-chips (items/wishlist/partials/_kind_filter.html).
• hx-boost: false on the skip-link; hx-boost:inherited="true" on <body>.
• hx-trigger: update from:body, on the same two elements that carry hx-sse:connect.

Verdict per attribute¶

Finding: the SSE element does double duty and deadlocks¶

items/wishlist/wishlist_page.html and items/calendar/events_page.html both put, on one element:

<div id="wishlist-list"
     hx-sse:connect="/items/stream/"
     hx-trigger="update from:body"
     hx-get="{% url 'wishlist_list_partial' %}"
     hx-vals='js:{…}'
     hx-swap="innerHTML">

Per [S8] and [S10 L330-339], hx-trigger on an hx-sse:connect element is the trigger for opening the stream (default load). Overriding it with update from:body means the connection is only opened once an update event has already been seen — and the only source of update events is the stream itself. The stream therefore never connects.

The docs' own pattern keeps the two jobs on separate elements: the connecting element takes the default load trigger, and a separate element listens for the named event — "A named event can also trigger another htmx request: <div hx-get="/status" hx-trigger="progress from:body"></div>" [S8].

from:body itself is fine: named events are dispatched on the request source element (htmx.trigger(element, detail.message.event, …) [S10 L287]) and bubble — "The event bubbles from the request source" [S8].

Secondary effect: hx-vals on the connecting element is applied to the connection GET ("The connection uses: hx-headers and hx-vals for the GET request" [S8]), which is not what the kind filter value is for.

This overlaps with issue #6's SSE claims; flagged here because it is a hx-trigger semantics change, not just an extension question.

Also relevant (not an attribute, but it changes what the attributes do)¶

• 4xx/5xx now swap by default. Only 204 and 304 are excluded — noSwap: [204, 304] [S9 L202], "Previously, 4xx and 5xx responses didn't swap content. Now they do" [S1]. So the repo's pattern of re-rendering a sheet partial with status=400 swaps natively, and the deleted htmx:beforeSwap forcing handler is genuinely redundant. Per-status control is now hx-status:422="…" [S1][S9 L2252-2267].
• HX-Trigger response header is still handled natively (#handleTriggerHeader [S9 L621, L859]), so the mutating views' 204 + HX-Trigger: closeDialog contract is intact and the deleted JS listener is redundant too.
• 60s default request timeout (defaultTimeout: 60000 [S9 L196]) — previously no timeout. Relevant to long-lived SSE requests; worth watching, though the sse extension manages its own connection lifecycle.

Concrete edits this repo needs¶

1. shared_calendar/templates/items/wishlist/wishlist_page.html and shared_calendar/templates/items/calendar/events_page.html — split the SSE connection from the refresh. Keep hx-sse:connect on its own element with the default load trigger, and leave hx-get + hx-trigger="update from:body" + hx-vals on the list element. e.g.

<div hx-sse:connect="/items/stream/"></div>
<div id="wishlist-list"
     hx-get="{% url 'wishlist_list_partial' %}"
     hx-trigger="update from:body"
     hx-vals='js:{kind: …}'
     hx-swap="innerHTML">…</div>

1. Nothing else. hx-get, hx-post, hx-target, hx-swap (both value patterns, including transition:true), hx-push-url, hx-vals with js:, hx-swap-oob with outerHTML:.filter-chips, hx-boost:inherited="true" and the skip-link's hx-boost="false" are all correct as written on migrate-to-htmx4.

2. Optional / hygiene, not required by htmx 4:

3. Run npx htmx.org@4.0.0 upgrade-check -- . as a second opinion; the htmx docs ship it as the official sweep tool.
4. CLAUDE.md still documents the 4xx swap-forcing workaround and names htmx-ext-sse; both are now wrong (see map #5's docs item).

Could not determine¶

• Whether the calendar/wishlist SSE elements, once split, should share one connecting element in base.html or keep one per page — a design question, not a docs question.
• Whether defaultTimeout: 60000 applies to the sse extension's streaming request in practice; the extension's own reconnect config suggests not, but neither the docs nor a quick read of the source settles it. Needs a runtime check.