htmx 4.0 is under construction — migration guide

hx-status

View as Markdown Open this page as Markdown
For LLMs
llms.txt htmx overview for LLMs
llms-full.txt Complete htmx docs for LLMs

Handles responses differently by status code

The hx-status attribute overrides swap behavior based on the HTTP response status code.

Examples

<!-- Show validation errors in a specific container -->
<form hx-post="..."
      hx-status:422="target:#errors select:#validation-errors">
  ...
</form>

<!-- Suppress swap on server errors -->
<button hx-post="..." hx-status:5xx="swap:none">Save</button>

<!-- Push a custom URL on 201 Created -->
<form hx-post="..." hx-status:201="push:/items/new">...</form>

Patterns

The status code goes after the colon: hx-status:CODE="...".

Supports exact codes, single-digit wildcards (x), and range wildcards (xx):

<div hx-get="..."
     hx-status:404="select:#not-found"
     hx-status:50x="select:#bad-gateway"
     hx-status:5xx="swap:none">
  ...
</div>

Evaluated in order of specificity: exact match (404), then 2-digit wildcard (50x), then 1-digit wildcard (5xx).

Modifiers

The value takes space-separated key:value pairs.

<form hx-post="..."
      hx-status:422="swap:innerHTML target:#errors select:#validation-errors"
      hx-status:500="swap:none push:false">
  ...
</form>

swap

Swap style for this status code. See hx-swap styles for values.

<div hx-get="..." hx-status:500="swap:none"></div>

target

CSS selector for the swap target. Overrides hx-target.

<div hx-get="..." hx-status:422="target:#error-container"></div>

select

CSS selector to pick content from the response. Overrides hx-select.

<div hx-get="..." hx-status:422="select:#validation-errors"></div>

push

Push a URL to browser history. true/false, or a URL string.

<div hx-get="..." hx-status:5xx="push:false"></div>
<form hx-post="/items" hx-status:201="push:/items/new"></form>

replace

Replace the current URL in browser history. true/false, or a URL string.

<div hx-get="..." hx-status:301="replace:/new-location"></div>

transition

Use the View Transitions API for this swap. true/false.

<div hx-get="..." hx-status:200="transition:true"></div>

Notes

See Also