Requests and responses

Control the result with response headers

Use an HX- response header when the server knows the correct target, swap, history update, event, refresh, or redirect.

8 minute lesson

~~~

Response headers let the server refine what should happen after it knows the result.

A failed create can send its form to an error region:

HTTP/1.1 422 Unprocessable Content
HX-Retarget: #task-form
HX-Reswap: outerHTML
Content-Type: text/html

Other useful controls include:

  • HX-Push-Url and HX-Replace-Url for history
  • HX-Trigger for a named browser event
  • HX-Refresh: true for a full refresh
  • HX-Redirect for a full client redirect
  • HX-Location for an HTMX-style navigation

Use headers when the server result determines the behavior. Keep stable defaults in markup when the behavior belongs to the component regardless of outcome.

HTMX-specific response headers are not processed on an ordinary 3xx response because the browser follows the redirect before HTMX sees the original headers. Return an appropriate non-3xx response when using HX-Redirect or HX-Location.

Do not turn headers into an invisible application protocol. Inspect and document the small set each endpoint may return.

Lesson completed