```
| Modifier | Description |
|---------------------|----------------------------------------------|
| `swap:
` | Delay before swap |
| `settle:` | Delay between swap and settle |
| `transition:true` | Use View Transitions API |
| `ignoreTitle:true` | Don't update page title from response |
| `scroll:top/bottom` | Scroll target after swap |
| `show:top/bottom` | Scroll target into viewport |
| `scrollTarget:` | Scroll this element instead of the target |
| `showTarget:` | Scroll this element into view instead of the target |
| `strip:true` | Remove outer wrapper element before swapping |
| `focusScroll:true` | Scroll to focused element |
| `swapEmpty:true` | Run the main swap even when nothing remains after OOB and partial content is removed |
| `target:` | Retarget the swap |
## Attribute Inheritance (CRITICAL htmx 4 change)
**In htmx 4, inheritance is explicit by default.** Use the `:inherited` modifier on parent elements:
```html
A
B
A
B
```
The `:append` modifier appends to inherited values:
```html
Save
```
To revert to implicit inheritance globally: set `htmx.config.implicitInheritance = true`.
## Configuration
Set via meta tag or JavaScript:
```html
`.
### Request Context
Events expose `detail.ctx` with the full request context:
```js
document.body.addEventListener('htmx:config:request', (evt) => {
let ctx = evt.detail.ctx;
// ctx.sourceElement -- element that triggered request
// ctx.target -- swap target element
// ctx.swap -- hx-swap value
// ctx.request.action -- URL
// ctx.request.method -- HTTP method
// ctx.request.headers -- headers object
// ctx.request.body -- FormData body
});
```
### Inline Event Handlers
Use `hx-on:event-name` for inline handlers:
```html
Load
```
## HTTP Headers
### Request Headers (sent by htmx)
| Header | Description |
|------------------------------|---------------------------------------------------------------------------------|
| `HX-Request` | Always `"true"` for htmx requests |
| `HX-Source` | Triggering element as `tag#id` (e.g. `button#submit`) |
| `HX-Target` | Target element as `tag#id` (e.g. `div#results`) |
| `HX-Current-URL` | Browser's current URL |
| `HX-Request-Type` | `"partial"` for targeted swaps, `"full"` when targeting body or using hx-select |
| `HX-Boosted` | `"true"` if via hx-boost |
| `HX-History-Restore-Request` | `"true"` if restoring history |
### Response Headers (server sends to htmx)
| Header | Description |
|------------------|--------------------------------------------------|
| `HX-Trigger` | Trigger client-side events (single name or JSON) |
| `HX-Push-Url` | Push URL to browser history |
| `HX-Replace-Url` | Replace current URL in history |
| `HX-Redirect` | Client-side redirect (full page) |
| `HX-Location` | Client-side redirect via AJAX (no full reload) |
| `HX-Refresh` | Full page refresh if `"true"` |
| `HX-Retarget` | Override target with CSS selector |
| `HX-Reswap` | Override swap strategy |
| `HX-Reselect` | Override hx-select |
## Status-Based Response Handling (hx-status)
Handle different HTTP status codes with different swap behavior:
```html
```
Supports wildcards: `hx-status:5xx`, `hx-status:50x`, `hx-status:404`.
Config options in the value: `swap:`, `target:`, `select:`, `push:`, `replace:`, `transition:`.
## Updating Multiple Page Regions
Three main approaches:
### 1. Expand the Target
Wrap both regions in a container and target it:
```html
```
Server returns both the table and the form.
### 2. Out-of-Band Swaps
Server response includes extra elements with `hx-swap-oob`:
```html
New row
```
Note: in htmx 4, OOB swaps happen AFTER the main content swap.
### 3. Partial Tags
New in htmx 4, a more general version of OOB swaps
```html
New message
5
```
Each `` specifies its own target and swap strategy. Preferred over OOB for explicit targeting.
### 4. Event-Driven Refresh
Server sends `HX-Trigger: newContact` header. Table listens for the event:
```html
...
```
## Morphing
`innerMorph` and `outerMorph` merge new content into the existing DOM instead of replacing it.
**Preserves:** focus, scroll position, CSS animations, event listeners, playing video, form input values.
**ID matching** is highest priority -- elements with matching IDs are updated in place.
**Warning:** morphing preserves user input values. It cannot be used to reset forms -- use `innerHTML`/`outerHTML` for
that.
**Excluding elements from morphing** -- add attributes to your server templates:
```html
...
...
```
Or set CSS selectors globally in config:
```javascript
htmx.config.morphSkip = 'custom-widget, .frozen';
htmx.config.morphSkipChildren = 'lit-component, .sortable';
```
## Other Attributes
| Attribute | Description |
|------------------|---------------------------------------------------------------------------|
| `hx-select` | CSS selector to pick part of the response |
| `hx-select-oob` | Pick out elements by ID for OOB swap |
| `hx-include` | Include additional elements' values in request |
| `hx-vals` | Add values to request. Supports `js:` prefix for dynamic values |
| `hx-headers` | Add custom headers to request |
| `hx-indicator` | Element to show during request (gets `htmx-request` class) |
| `hx-confirm` | Show confirmation dialog. Supports `js:` prefix for async confirmation |
| `hx-sync` | Synchronize requests between elements |
| `hx-boost` | Progressive enhancement for links and forms |
| `hx-config` | Per-element Fetch config (`timeout`, `credentials`, `cache`, etc.). Cannot override `mode` |
| `hx-preserve` | Keep element unchanged across swaps |
| `hx-ignore` | Disable htmx processing for element and children |
| `hx-disable` | Disable specified elements during requests |
| `hx-preload` | Preload content on trigger events |
| `hx-pending` | Show pending content during request |
| `hx-push-url` | Push URL to browser history |
| `hx-replace-url` | Replace URL in browser history |
| `hx-encoding` | Change encoding (e.g. `multipart/form-data` for file uploads) |
| `hx-validate` | Validate form elements before request |
| `hx-action` | Request URL, when the method comes from `hx-method` |
| `hx-method` | HTTP method, paired with `hx-action` |
| `hx-status:XXX` | Change target, swap or history handling for one status code |
| `hx-history-elt` | Element to restore on history navigation, instead of `body` |
| `hx-morph-skip` | Freeze this element during a morph swap |
| `hx-morph-skip-children` | Update attributes but freeze children during a morph swap |
## Parameters
- Non-GET/DELETE requests automatically include enclosing form values
- GET and DELETE do NOT include enclosing form data. Use `hx-include="closest form"` if needed
- Use `hx-vals="key:value"` for static values. `hx-vals` takes HCON, which also accepts JSON
- Use `hx-vals='js:{"key": computeValue()}'` for dynamic values
- `hx-headers` and `hx-config` take HCON too
## JavaScript API
```js
htmx.version // Version string, read-only
htmx.ajax("GET", "/data", {target: "#result"}) // Programmatic request, returns Promise
htmx.on("htmx:after:swap", (evt) => {}) // Event listener
htmx.onLoad((elt) => {}) // Callback for new content
htmx.process(element) // Initialize htmx on dynamic content
htmx.initialize() // Set up history and process document.body
htmx.find("closest .container") // Extended CSS selector query
htmx.findAll(".items") // Find all matching
htmx.trigger(elt, "myEvent", {detail: ...}) // Fire custom event
htmx.swap(ctx) // Manual swap
htmx.timeout(1000) // Promise that resolves after a delay
htmx.parseInterval("2s") // Parse a time interval to ms
htmx.registerExtension("name", hooks) // Register an extension
```
The `hx-live` extension adds an `htmx.live` namespace: `take()`, `toggle()`, `attr()`, `q()` (alias `$`),
`debounce()`, `refresh()`, `forEvent()` and `nextFrame()`.
## Common Patterns
### Active Search
```html
Searching...
```
### Lazy Loading
```html
Loading...
```
### Infinite Scroll
```html
```
### Click to Load More
```html
Load More
```
### Edit in Place
```html
```
Server returns an edit form. Form submits via hx-post and returns the display view.
### Tabs
```html
Tab 1
Tab 2
...
```
### Form Validation
```html
```
Server returns 422 with error HTML, target becomes the element with the errors id, or 200 with success HTML target is
the element with the id `result`.
### Loading Indicators
```html
Load
```
The `htmx-indicator` class hides the element by default (opacity: 0). When a request is in flight, `htmx-request` class
is added, making indicators visible.
To avoid flashing the spinner on fast requests, add a `transition-delay` (the second time value) to the indicator's CSS:
```css
.htmx-request .htmx-indicator { transition: opacity 200ms ease-in 200ms; }
```
If the request finishes before the delay elapses, the spinner never appears
### Disabling Elements During Request
```html
```
## Extensions
Extensions are loaded by including the script file. They apply page-wide automatically:
```html
```
To restrict which extensions can load, use the `extensions` config as a whitelist. The whitelist takes the
registration name, which is not always the file name:
```html
` tags** over `hx-swap-oob` for multi-region updates (more explicit)
1. **GET and DELETE don't include form data** -- use `hx-include="closest form"` if needed
1. When showing patterns, include both the HTML and describe what the server endpoint should return
1. There are many useful extensions, for example `hx-sse.js` for Server-Sent Events and `hx-preload.js` for
faster navigation. Suggest them if they make sense.