## Get Started ### [Installation](https://four.htmx.org/docs/get-started/installation) import { Code } from 'astro:components'; import integrity from '../../../data/integrity.json'; htmx is a single JavaScript file with no dependencies. No build step is required to use it. #### CDN Add this in your `` tag:
`} />

##### Unminified

`} />

##### ES Module

`} />

##### ES Module (unminified)

`} />

#### Download

Instead of using a CDN, consider [self-hosting in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn).

1. Download htmx.min.js
2. Save it to your project (e.g., `/js/htmx.min.js`)
3. Add this in your `` tag:

```html

```

##### Other formats

Download: htmx.js (unminified)

Download: htmx.esm.min.js (ES module)

Download: htmx.esm.js (ES module, unminified)

#### npm

```sh
npm install htmx.org@4.0.0-beta4
```

```javascript
import 'htmx.org';
```

##### Named import

```javascript
import htmx from 'htmx.org';

// Now you can use htmx.ajax(), htmx.find(), etc.
```

#### htmax

The `htmax.js` file bundles htmx with the most popular extensions in a single file:

* [SSE](https://four.htmx.org/extensions/hx-sse)
* [WebSockets](https://four.htmx.org/extensions/hx-ws)
* [preload](https://four.htmx.org/extensions/hx-preload)
* [browser-indicator](https://four.htmx.org/extensions/hx-browser-indicator)
* [download](https://four.htmx.org/extensions/hx-download)
* [optimistic](https://four.htmx.org/extensions/hx-optimistic)
* [targets](https://four.htmx.org/extensions/hx-targets)
* [live](https://four.htmx.org/extensions/hx-live).

The extensions are automatically available, you can just use their attributes directly (e.g. `hx-sse:connect`, `hx-ws:connect`).

```html

```

### [Migration](https://four.htmx.org/docs/get-started/migration)

#### Quick Start

There are two major behavioral changes between htmx 2.x and 4.x:

* In htmx 2.0 attribute inheritance is *implicit* by default while in 4.0 it is explicit by default
* In htmx 2.0, `400` and `500` response codes are not swapped by default, whereas in htmx 4.0 these requests will be
  swapped

Add these two config lines to restore htmx 2.x behavior:

```html



```

[`implicitInheritance`](https://four.htmx.org/reference/config/htmx-config-implicitInheritance) restores htmx 2's implicit attribute
inheritance. [`noSwap`](https://four.htmx.org/reference/config/htmx-config-noSwap) prevents swapping error responses.

Or load the [`htmx-2-compat`](https://four.htmx.org/extensions/htmx-2-compat) extension, which restores implicit inheritance, old event
names, and previous error-swapping defaults:

```html



```

Most htmx 2 apps should work with either approach. Then migrate incrementally using this guide.

#### Upgrade Checker

htmx 4 ships with a command-line tool scans your templates and JS files for htmx 2 code that needs updating. It checks 
for removed attributes, old event names, inheritance patterns, extension changes, etc.

```bash
npx htmx.org@next upgrade-check -- ./path/to/project/root

npx htmx.org@next upgrade-check --ext .vue ./path/to/project/root
```

By default, the tool scans `.html`, `.php`, `.js`, `.ts`, `.jinja`, `.jinja2`, `.j2`, `.erb`, and `.hbs` files.

Output is `file:line` format, clickable in most editors. You can add additional file types with the `--ext` option.

The tool requires Python 3.

#### What Changed

##### `fetch()` replaces `XMLHttpRequest`

All requests use the native [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This cannot be
reverted.

##### Explicit inheritance

Add [`:inherited`](https://four.htmx.org/docs/features/attribute-inheritance) to any attribute that should inherit down the DOM tree.

```html


    




    

```

Works on any attribute: [`hx-boost`](https://four.htmx.org/reference/attributes/hx-boost)`:inherited`, [
`hx-target`](https://four.htmx.org/reference/attributes/hx-target)`:inherited`, [`hx-confirm`](https://four.htmx.org/reference/attributes/hx-confirm)`:inherited`,
etc.

Use `:append` to add to an inherited value instead of replacing it:

```html


    
    ...

```

Revert: [`htmx.config.implicitInheritance`](https://four.htmx.org/reference/config/htmx-config-implicitInheritance) `= true`

##### Error responses swap

htmx 4 swaps all HTTP responses. Only [`204`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/204)
and [`304`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/304) do not swap.

htmx 2 did not swap `4xx` and `5xx` responses. In htmx 4, if your server returns HTML with a `422` or `500`, that HTML
gets swapped into the target. Design your error responses to work as swap content, or use [
`hx-status`](https://four.htmx.org/reference/attributes/hx-status) to control per-code behavior.

Revert: [`htmx.config.noSwap`](https://four.htmx.org/reference/config/htmx-config-noSwap) `= [204, 304, '4xx', '5xx']`

##### [`hx-delete`](https://four.htmx.org/reference/attributes/hx-delete) excludes form data

Like [`hx-get`](https://four.htmx.org/reference/attributes/hx-get), [`hx-delete`](https://four.htmx.org/reference/attributes/hx-delete) no longer includes the
enclosing form's inputs.

Fix: add [`hx-include`](https://four.htmx.org/reference/attributes/hx-include)`="closest form"` where needed.

##### No history cache

History no longer caches pages in [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
When navigating back, htmx re-fetches the page and swaps it into ``, or into the `[hx-history-elt]` element if
one is present — the same behavior as htmx 2.

Use [`htmx.config.history`](https://four.htmx.org/reference/config/htmx-config-history) `= "reload"` for a full page reload instead. Use
`htmx.config.history = false` to disable.

##### OOB swap order

In htmx 2, out-of-band ([`hx-swap-oob`](https://four.htmx.org/reference/attributes/hx-swap-oob)) elements swapped **before** the main
content.

In htmx 4, the main content swaps first. OOB and [``](https://four.htmx.org/docs/core-concepts/multi-target-updates#partials-hx-partial) elements swap after (in document order).

This matters if an OOB swap creates or modifies DOM that the main swap depends on. If your app relies on that ordering,
restructure so each swap is independent.

##### `hx-trigger` `queue` modifier removed

The `queue` modifier on [`hx-trigger`](https://four.htmx.org/reference/attributes/hx-trigger) (e.g. `hx-trigger="click queue:all"`) no longer
works. Request queuing is now controlled exclusively by [`hx-sync`](https://four.htmx.org/reference/attributes/hx-sync).

```html

...


...
```

##### 60-second timeout

htmx 2 had no timeout (`0`). htmx 4 sets [`defaultTimeout`](https://four.htmx.org/reference/config/htmx-config-defaultTimeout) to `60000`.

Revert: `htmx.config.defaultTimeout = 0`

##### Extension loading

Include extension scripts directly. No attribute needed:

```html



```

Restrict which extensions can load:

```html


```

Extension authors use `htmx.registerExtension(name, methodMap)` to register.

See [Extensions documentation](https://four.htmx.org/docs/features/extensions) for details.

#### Renames and Removals

##### Rename `hx-disable`

Do this **before** upgrading. The name `hx-disable` has been reassigned:

- In htmx 2, `hx-disable` meant "skip htmx processing on this element"
- In htmx 4, that role is [`hx-ignore`](https://four.htmx.org/reference/attributes/hx-ignore)
- The name `hx-disable` now does what `hx-disabled-elt` used to do (disable form elements during requests)

Rename in this order to avoid conflicts:

1. Rename `hx-disable` to [`hx-ignore`](https://four.htmx.org/reference/attributes/hx-ignore)
2. Rename `hx-disabled-elt` to [`hx-disable`](https://four.htmx.org/reference/attributes/hx-disable)

##### Removed attributes

| Removed          | Use instead                                                                                       |
|------------------|---------------------------------------------------------------------------------------------------|
| `hx-vars`        | [`hx-vals`](https://four.htmx.org/reference/attributes/hx-vals) with `js:` prefix                                      |
| `hx-params`      | [`htmx:config:request`](https://four.htmx.org/reference/events/htmx-config-request) event                              |
| `hx-prompt`      | [`hx-confirm`](https://four.htmx.org/reference/attributes/hx-confirm) with `js:` prefix                                |
| `hx-ext`         | [Include extension script directly](https://four.htmx.org/docs/features/extensions)                            |
| `hx-disinherit`  | Not needed (inheritance is explicit)                                                              |
| `hx-inherit`     | Not needed (inheritance is explicit)                                                              |
| `hx-request`     | [`hx-config`](https://four.htmx.org/reference/attributes/hx-config)                                                    |
| `hx-history`     | Removed (no [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)) |

##### Renamed events

All events follow a new pattern: `htmx:phase:action[:sub-action]`

Most error events are consolidated to [`htmx:error`](https://four.htmx.org/reference/events/htmx-error). HTTP error responses have a dedicated [`htmx:response:error`](https://four.htmx.org/reference/events/htmx-response-error) event.

| htmx 2.x                    | htmx 4.x                                                                          |
|-----------------------------|-----------------------------------------------------------------------------------|
| `htmx:afterOnLoad`          | [`htmx:after:init`](https://four.htmx.org/reference/events/htmx-after-init)                            |
| `htmx:afterProcessNode`     | [`htmx:after:init`](https://four.htmx.org/reference/events/htmx-after-init)                            |
| `htmx:afterRequest`         | [`htmx:after:request`](https://four.htmx.org/reference/events/htmx-after-request)                      |
| `htmx:afterSettle`          | [`htmx:after:swap`](https://four.htmx.org/reference/events/htmx-after-swap)                            |
| `htmx:afterSwap`            | [`htmx:after:swap`](https://four.htmx.org/reference/events/htmx-after-swap)                            |
| `htmx:beforeCleanupElement` | [`htmx:before:cleanup`](https://four.htmx.org/reference/events/htmx-before-cleanup)                    |
| `htmx:beforeHistorySave`    | [`htmx:before:history:update`](https://four.htmx.org/reference/events/htmx-before-history-update)      |
| `htmx:beforeOnLoad`         | [`htmx:before:init`](https://four.htmx.org/reference/events/htmx-before-init)                          |
| `htmx:beforeProcessNode`    | [`htmx:before:process`](https://four.htmx.org/reference/events/htmx-before-process)                    |
| `htmx:beforeRequest`        | [`htmx:before:request`](https://four.htmx.org/reference/events/htmx-before-request)                    |
| `htmx:beforeSwap`           | [`htmx:before:swap`](https://four.htmx.org/reference/events/htmx-before-swap)                          |
| `htmx:configRequest`        | [`htmx:config:request`](https://four.htmx.org/reference/events/htmx-config-request)                    |
| `htmx:historyCacheMiss`     | [`htmx:before:history:restore`](https://four.htmx.org/reference/events/htmx-before-restore-history)    |
| `htmx:historyRestore`       | [`htmx:before:history:restore`](https://four.htmx.org/reference/events/htmx-before-restore-history)    |
| `htmx:load`                 | [`htmx:after:init`](https://four.htmx.org/reference/events/htmx-after-init)                            |
| `htmx:oobAfterSwap`         | [`htmx:after:swap`](https://four.htmx.org/reference/events/htmx-after-swap)                            |
| `htmx:oobBeforeSwap`        | [`htmx:before:swap`](https://four.htmx.org/reference/events/htmx-before-swap)                          |
| `htmx:pushedIntoHistory`    | [`htmx:after:history:push`](https://four.htmx.org/reference/events/htmx-after-push-into-history)       |
| `htmx:replacedInHistory`    | [`htmx:after:history:replace`](https://four.htmx.org/reference/events/htmx-after-replace-into-history) |
| `htmx:responseError`        | [`htmx:response:error`](https://four.htmx.org/reference/events/htmx-response-error)                    |
| `htmx:sendError`            | [`htmx:error`](https://four.htmx.org/reference/events/htmx-error)                                      |
| `htmx:swapError`            | [`htmx:error`](https://four.htmx.org/reference/events/htmx-error)                                      |
| `htmx:targetError`          | [`htmx:error`](https://four.htmx.org/reference/events/htmx-error)                                      |
| `htmx:timeout`              | [`htmx:error`](https://four.htmx.org/reference/events/htmx-error)                                      |

##### Removed events

Validation events are removed. Use native browser form validation:

- `htmx:validation:validate`
- `htmx:validation:failed`
- `htmx:validation:halted`

XHR events are removed (htmx uses `fetch()` now):

| Removed              | Use instead                                                      |
|----------------------|------------------------------------------------------------------|
| `htmx:xhr:loadstart` | No replacement                                                   |
| `htmx:xhr:loadend`   | [`htmx:finally:request`](https://four.htmx.org/reference/events/htmx-finally-request) |
| `htmx:xhr:progress`  | No replacement                                                   |
| `htmx:xhr:abort`     | [`htmx:error`](https://four.htmx.org/reference/events/htmx-error)                     |

##### Config changes

**Renamed:**

| htmx 2.x                 | htmx 4.x                                                                   |
|--------------------------|----------------------------------------------------------------------------|
| `defaultSwapStyle`       | [`defaultSwap`](https://four.htmx.org/reference/config/htmx-config-defaultSwap)                 |
| `globalViewTransitions`  | [`transitions`](https://four.htmx.org/reference/config/htmx-config-transitions)                 |
| `historyEnabled`         | [`history`](https://four.htmx.org/reference/config/htmx-config-history)                         |
| `includeIndicatorStyles` | [`includeIndicatorCSS`](https://four.htmx.org/reference/config/htmx-config-includeIndicatorCSS) |
| `timeout`                | [`defaultTimeout`](https://four.htmx.org/reference/config/htmx-config-defaultTimeout)           |

**Changed defaults:**

| Config                                                                   | htmx 2           | htmx 4               |
|--------------------------------------------------------------------------|------------------|----------------------|
| [`defaultTimeout`](https://four.htmx.org/reference/config/htmx-config-defaultTimeout)         | `0` (no timeout) | `60000` (60 seconds) |
| [`defaultSettleDelay`](https://four.htmx.org/reference/config/htmx-config-defaultSettleDelay) | `20`             | `1`                  |

**Removed:**

`addedClass`, `allowEval`, `allowNestedOobSwaps`, `allowScriptTags`, `attributesToSettle`, `defaultSwapDelay`,
`disableSelector` (use [`hx-ignore`](https://four.htmx.org/reference/attributes/hx-ignore)), `getCacheBusterParam`, `historyCacheSize`,
`ignoreTitle` (still works per-swap via [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap)`="... ignoreTitle:true"`),
`inlineStyleNonce` (removed — indicator CSS now uses [Constructable Stylesheets](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet) and does not require a nonce),
`methodsThatUseUrlParams`, `refreshOnHistoryMiss`, `responseHandling` (use [
`hx-status`](https://four.htmx.org/reference/attributes/hx-status) and [`noSwap`](https://four.htmx.org/reference/config/htmx-config-noSwap)), `scrollBehavior`,
`scrollIntoViewOnBoost`, `selfRequestsOnly` (use [`htmx.config.mode`](https://four.htmx.org/reference/config/htmx-config-mode)),
`settlingClass`, `swappingClass`, `triggerSpecsCache`, `useTemplateFragments`, `withCredentials` (use [
`hx-config`](https://four.htmx.org/reference/attributes/hx-config)), `wsBinaryType`, `wsReconnectDelay`

The `htmx-swapping`, `htmx-settling`, and `htmx-added` CSS classes are still applied during swaps. The config keys to
customize their names have been removed.

##### Request headers

| htmx 2.x          | htmx 4.x                                                | Notes                                                                  |
|-------------------|---------------------------------------------------------|------------------------------------------------------------------------|
| `HX-Trigger`      | [`HX-Source`](https://four.htmx.org/reference/headers/HX-Source)             | Format changed to `tagName#id` (e.g. `button#submit`)                  |
| `HX-Target`       | [`HX-Target`](https://four.htmx.org/reference/headers/HX-Target)             | Format changed to `tagName#id`                                         |
| `HX-Trigger-Name` | removed                                                 | Use [`HX-Source`](https://four.htmx.org/reference/headers/HX-Source)                        |
| `HX-Prompt`       | removed                                                 | Use [`hx-confirm`](https://four.htmx.org/reference/attributes/hx-confirm) with `js:` prefix |
| *(new)*           | [`HX-Request-Type`](https://four.htmx.org/reference/headers/HX-Request-Type) | `"full"` or `"partial"`                                                |
| *(new)*           | [`Accept`](https://four.htmx.org/reference/headers/Accept)                   | Now explicitly `text/html`                                             |

##### Response headers

Removed:

- `HX-Trigger-After-Swap`
- `HX-Trigger-After-Settle`

Use [`HX-Trigger`](https://four.htmx.org/reference/headers/HX-Trigger) or JavaScript instead.

Unchanged: [`HX-Trigger`](https://four.htmx.org/reference/headers/HX-Trigger), [`HX-Location`](https://four.htmx.org/reference/headers/HX-Location), [
`HX-Push-Url`](https://four.htmx.org/reference/headers/HX-Push-Url), [`HX-Redirect`](https://four.htmx.org/reference/headers/HX-Redirect), [
`HX-Refresh`](https://four.htmx.org/reference/headers/HX-Refresh), [`HX-Replace-Url`](https://four.htmx.org/reference/headers/HX-Replace-Url), [
`HX-Retarget`](https://four.htmx.org/reference/headers/HX-Retarget), [`HX-Reswap`](https://four.htmx.org/reference/headers/HX-Reswap), [`HX-Reselect`](https://four.htmx.org/reference/headers/HX-Reselect).

##### JavaScript API changes

**Removed methods.** Use native JavaScript:

| htmx 2.x             | Use instead                                                            |
|----------------------|------------------------------------------------------------------------|
| `htmx.addClass()`    | `element.classList.add()`                                              |
| `htmx.removeClass()` | `element.classList.remove()`                                           |
| `htmx.toggleClass()` | `element.classList.toggle()`                                           |
| `htmx.closest()`     | `element.closest()`                                                    |
| `htmx.remove()`      | `element.remove()`                                                     |
| `htmx.off()`         | `removeEventListener()` (`htmx.on()` returns the callback)             |
| `htmx.location()`    | `htmx.ajax()`                                                          |

**Renamed:** `htmx.defineExtension()` is now `htmx.registerExtension()`.

**Still available:** `htmx.ajax()`, `htmx.config`, `htmx.find()`, `htmx.findAll()`, `htmx.on()`,
`htmx.onLoad()`, `htmx.parseInterval()`, `htmx.process()`, `htmx.swap()`, `htmx.trigger()`.

**Removed:** `htmx.logAll()`, `htmx.logNone()`, and the pluggable `htmx.logger`. htmx now logs directly via
`console.error` / `console.warn` / `console.log`. Set `htmx.config.logAll = true` to surface event-level
output. Observability tools (Sentry, DataDog RUM, LogRocket, etc.) capture `console.*` automatically.

Note: `htmx.onLoad()` now listens on [`htmx:after:process`](https://four.htmx.org/reference/events/htmx-after-process), not [
`htmx:after:init`](https://four.htmx.org/reference/events/htmx-after-init).

#### What's New

##### Attributes

| Attribute                                          | Purpose                                                               |
|----------------------------------------------------|-----------------------------------------------------------------------|
| [`hx-action`](https://four.htmx.org/reference/attributes/hx-action)     | Specify URL (use with [`hx-method`](https://four.htmx.org/reference/attributes/hx-method)) |
| [`hx-method`](https://four.htmx.org/reference/attributes/hx-method)     | Specify HTTP method                                                   |
| [`hx-config`](https://four.htmx.org/reference/attributes/hx-config)     | Per-element request config (JSON or `key:value` syntax)               |
| [`hx-ignore`](https://four.htmx.org/reference/attributes/hx-ignore)     | Disable htmx processing (was `hx-disable`)                            |
| [`hx-validate`](https://four.htmx.org/reference/attributes/hx-validate) | Control form validation behavior                                      |

##### [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) scroll modifiers

The `show` and `scroll` modifiers no longer support the combined `selector:position` syntax. Use separate keys instead:

```html






```

##### [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) styles

```html

...
...
...
...
```

- `innerMorph` / `outerMorph`: morph swaps using the idiomorph algorithm. Better for preserving state in complex UIs.
- `textContent`: set the target's text content (no HTML parsing).
- `delete`: remove the target element entirely.

New aliases for existing swap styles (both old and new names work):

| New       | Equivalent to |
|-----------|---------------|
| `before`  | `beforebegin` |
| `after`   | `afterend`    |
| `prepend` | `afterbegin`  |
| `append`  | `beforeend`   |

##### [Status code swaps](https://four.htmx.org/reference/attributes/hx-status)

Set different swap behavior per HTTP status code:

```html


    

```

Available config keys: `swap:`, `target:`, `select:`, `push:`, `replace:`, `transition:`.

Supports exact codes (`404`), single-digit wildcards (`50x`), and range wildcards (`5xx`). Evaluated in order of
specificity.

##### ``

Target multiple elements from one response. An alternative to [`hx-swap-oob`](https://four.htmx.org/reference/attributes/hx-swap-oob) for when you need explicit control over targeting and swap strategy:

```html

    New message



    5

```

Each `` specifies its own [`hx-target`](https://four.htmx.org/reference/attributes/hx-target) and [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) strategy. See [Multi-Target Updates](https://four.htmx.org/docs/core-concepts/multi-target-updates) for full documentation.

##### View transitions

[View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) support is available but
disabled by default.

Enable: [`htmx.config.transitions`](https://four.htmx.org/reference/config/htmx-config-transitions) `= true`

##### JSX compatibility

Frameworks that don't support `:` in attribute names can use [
`metaCharacter`](https://four.htmx.org/reference/config/htmx-config-metaCharacter) to replace it:

```js
htmx.config.metaCharacter = "-";
// hx-ws-connect instead of hx-ws:connect
// hx-confirm-inherited instead of hx-confirm:inherited
```

##### JavaScript methods

- `htmx.timeout(time)`: returns a promise that resolves after a delay (number ms, or interval string `'500ms'`/`'1s'`/`'5m'`)

`htmx.takeClass` is **removed** from core. Equivalent functionality is exposed by the `hx-live` extension on the `htmx.live` namespace:

```js
htmx.live.take(target, className, source)   // strip class from `source`, add to `target`
htmx.live.forEvent(...args)                 // race events/timeouts
htmx.live.nextFrame()                       // promise that resolves on next animation frame
htmx.live.q(selector)                       // jQuery-like proxy rooted at documentElement
htmx.live.debounce(ms[, fn])                // global debounce
htmx.live.refresh()                         // recompute every live expression
```

Inside `hx-live`/`hx-on` expression scope these are available unprefixed (`take`, `forEvent`, `nextFrame`, `q`, `debounce`, `toggle`) with the current element used as the implicit context — see the [`hx-live` extension docs](https://four.htmx.org/extensions/hx-live).

##### Auto-logged events

Internally-dispatched events route to the console as follows:

- If `detail.error` is set on the event, output goes to `console.error` (the Error instance is inlined first when applicable, so DevTools renders the stack). This covers request failures, hx-on handler exceptions, and other thrown paths. Apps that listen for `htmx:error` get the same data via the event.
- If `detail.warn` is set, output goes to `console.warn`.
- Otherwise, the event is logged at `console.log` (silent by default; set `htmx.config.logAll = true` to surface).

This restores the htmx 2.x convention: if you want an internal failure path to show up in the console, fire an event with `detail.error` (or `detail.warn`); no per-site `console.error` needed.

##### Request context

All events provide a consistent `ctx` object with request/response information.

##### Events

| Event                                                                        | Fires                                             |
|------------------------------------------------------------------------------|---------------------------------------------------|
| [`htmx:after:cleanup`](https://four.htmx.org/reference/events/htmx-after-cleanup)                 | After element cleanup                             |
| [`htmx:after:history:update`](https://four.htmx.org/reference/events/htmx-after-history-update)   | After history update                              |
| [`htmx:after:process`](https://four.htmx.org/reference/events/htmx-after-process)                 | After element processing                          |
| [`htmx:before:response`](https://four.htmx.org/reference/events/htmx-before-response)             | Before response body is read (cancellable)        |
| [`htmx:before:settle`](https://four.htmx.org/reference/events/htmx-before-settle)                 | Before settle phase                               |
| [`htmx:after:settle`](https://four.htmx.org/reference/events/htmx-after-settle)                   | After settle phase                                |
| [`htmx:before:viewTransition`](https://four.htmx.org/reference/events/htmx-before-viewTransition) | Before a view transition starts (cancellable)     |
| [`htmx:after:viewTransition`](https://four.htmx.org/reference/events/htmx-after-viewTransition)   | After a view transition completes                 |
| [`htmx:finally:request`](https://four.htmx.org/reference/events/htmx-finally-request)             | Always fires after a request (success or failure) |

##### Config keys

| Config                                                                 | Default         | Purpose                                                       |
|------------------------------------------------------------------------|-----------------|---------------------------------------------------------------|
| [`extensions`](https://four.htmx.org/reference/config/htmx-config-extensions)               | `''`            | Comma-separated list of allowed extension names               |
| [`mode`](https://four.htmx.org/reference/config/htmx-config-mode)                           | `'same-origin'` | Fetch mode (replaces `selfRequestsOnly`)                      |
| [`inlineScriptNonce`](https://four.htmx.org/reference/config/htmx-config-inlineScriptNonce) | `''`            | Nonce for inline scripts                                      |
| [`metaCharacter`](https://four.htmx.org/reference/config/htmx-config-metaCharacter)         | `':'`           | Separator character in attribute/event names                  |
| [`morphIgnore`](https://four.htmx.org/reference/config/htmx-config-morphIgnore)             | `''`            | CSS selector for elements to ignore during morph              |
| [`morphScanLimit`](https://four.htmx.org/reference/config/htmx-config-morphScanLimit)       |                 | Max elements to scan during morph matching                    |
| [`morphSkip`](https://four.htmx.org/reference/config/htmx-config-morphSkip)                 | `''`            | CSS selector for elements to skip during morph                |
| [`morphSkipChildren`](https://four.htmx.org/reference/config/htmx-config-morphSkipChildren) | `''`            | CSS selector for elements whose children to skip during morph |

##### Core extensions

htmx 4 ships with 9 core extensions. The SSE and WebSocket extensions have been significantly rewritten. See their upgrade guides for details.

| Extension                                                 | Description                                                                          |
|-----------------------------------------------------------|--------------------------------------------------------------------------------------|
| [`alpine-compat`](https://four.htmx.org/extensions/hx-alpine-compat)         | Alpine.js compatibility: initializes Alpine on fragments before swap                 |
| [`browser-indicator`](https://four.htmx.org/extensions/hx-browser-indicator) | Shows the browser's native loading indicator during requests                         |
| [`head-support`](https://four.htmx.org/extensions/hx-head)           | Merges head tag information (styles, etc.) in htmx requests                          |
| [`htmx-2-compat`](https://four.htmx.org/extensions/htmx-2-compat)         | Restores implicit inheritance, old event names, and previous error-swapping defaults |
| [`optimistic`](https://four.htmx.org/extensions/hx-optimistic)               | Shows expected content from a template before the server responds                    |
| [`preload`](https://four.htmx.org/extensions/hx-preload)                     | Triggers requests early (on mouseover/mousedown) for near-instant page loads ([upgrade guide](https://four.htmx.org/extensions/hx-preload#upgrading-from-htmx-2x)) |
| [`sse`](https://four.htmx.org/extensions/hx-sse)                             | Server-Sent Events streaming support ([upgrade guide](https://four.htmx.org/extensions/hx-sse#upgrading-from-htmx-2x)) |
| [`upsert`](https://four.htmx.org/extensions/hx-upsert)                       | Updates existing elements by ID and inserts new ones, preserving unmatched elements  |
| [`ws`](https://four.htmx.org/extensions/hx-ws)                               | Bi-directional WebSocket communication ([upgrade guide](https://four.htmx.org/extensions/hx-ws#upgrading-from-htmx-2x)) |

#### Checklist

1. Optionally, add config options or load [`htmx-2-compat`](https://four.htmx.org/extensions/htmx-2-compat) for backward compatibility
2. Run the [upgrade checker](#upgrade-checker) to get a full list of issues
3. Rename `hx-disable` to [`hx-ignore`](https://four.htmx.org/reference/attributes/hx-ignore), then `hx-disabled-elt` to [
   `hx-disable`](https://four.htmx.org/reference/attributes/hx-disable)
4. Replace removed attributes with alternatives
5. Find/replace event names in JavaScript and `hx-on` attributes
6. Replace removed API methods with native JS
7. Update extensions
8. Rename changed config keys
9. Test error handling (4xx/5xx now swap by default)
10. Test attribute inheritance
11. Test history navigation

#### Migration Notes

Individual documentation pages include migration notes where features changed.

Look for these:


Changes in htmx 4.0



#### Get Help

- [GitHub Discussions](https://github.com/bigskysoftware/htmx/discussions)
- [Discord](https://htmx.org/discord)
- [Patterns](https://four.htmx.org/patterns)


#### Migrating Your Own Extensions



If you maintain a custom extension written for htmx 2.x, the extension API has changed substantially. The catalog of bundled extensions ([/extensions](https://four.htmx.org/extensions)) has already been ported. This section is for porting your own.

##### Quick Start

htmx 4 replaces the callback-based extension API with event-based hooks. Extensions register handlers for lifecycle events instead of implementing callback methods.

The simplest migration: rename `defineExtension` to `registerExtension` and map your callbacks to hooks.

```javascript
// htmx 2.x
htmx.defineExtension('my-ext', {
    onEvent: function(name, evt) {
        if (name === 'htmx:beforeRequest') { /* ... */ }
    }
});

// htmx 4
htmx.registerExtension('my-ext', {
    htmx_before_request: (elt, detail) => { /* ... */ }
});
```

##### What Changed

###### No `hx-ext` attribute

Extensions load by including the script. No attribute needed:

```html


```

Restrict which extensions can load:

```html

```

###### Event hooks replace callbacks

Instead of a single `onEvent` callback that switches on event names, each event gets its own hook method. Hook names use underscores where events use colons:

| htmx 2.x event | htmx 4 hook |
|---|---|
| `htmx:configRequest` | `htmx_config_request` |
| `htmx:beforeRequest` | `htmx_before_request` |
| `htmx:afterRequest` | `htmx_after_request` |
| `htmx:beforeSwap` | `htmx_before_swap` |
| `htmx:afterSwap` | `htmx_after_swap` |

All hooks receive `(elt, detail)`. Return `false` to cancel.

###### `handle_swap` is special

Unlike other hooks, `handle_swap` is called directly with positional parameters (no `htmx_` prefix, no detail object):

```javascript
handle_swap: (swapStyle, target, fragment, swapSpec) => {
    if (swapStyle === 'my-swap') {
        target.appendChild(fragment);
        return true;
    }
    return false;
}
```

###### Detail object replaces event properties

All hooks receive `detail.ctx` with full request/response context:

- `detail.ctx.request.body` (FormData in `htmx_config_request`)
- `detail.ctx.request.headers`
- `detail.ctx.response.status`
- `detail.ctx.text` (response body, modifiable in `htmx_after_request`)
- `detail.ctx.target`

###### OOB swap stripping

OOB swaps automatically strip the wrapper element for non-outer swap styles. Name custom swap styles starting with "outer" (e.g., `outerMorph`) to preserve the wrapper.

##### Callback Migration Map

###### `init`

```javascript
// htmx 2.x
init: function(api) {
    return null;
}

// htmx 4
init: (internalAPI) => {
    api = internalAPI;
}
```

Store the `internalAPI` reference for use in other hooks. No return value needed.

###### `getSelectors`

Removed. Use `htmx_after_init` to check for attributes:

```javascript
// htmx 2.x
getSelectors: function() {
    return ['[my-custom-attr]'];
},
onEvent: function(name, evt) {
    if (name === 'htmx:afterProcessNode') {
        initializeCustomBehavior(evt.target);
    }
}

// htmx 4
htmx_after_init: (elt) => {
    if (api.attributeValue(elt, 'my-custom-attr')) {
        initializeCustomBehavior(elt);
    }
}
```

###### `onEvent`

Replace with individual hooks:

```javascript
// htmx 2.x
onEvent: function(name, evt) {
    if (name === 'htmx:beforeSwap' && evt.detail.xhr.status !== 200) {
        var target = getRespCodeTarget(evt.detail.requestConfig.elt, evt.detail.xhr.status);
        if (target) {
            evt.detail.shouldSwap = true;
            evt.detail.target = target;
        }
    }
}

// htmx 4
htmx_before_swap: (elt, detail) => {
    if (detail.ctx.response.status !== 200) {
        var target = getRespCodeTarget(elt, detail.ctx.response.status);
        if (target) {
            detail.ctx.target = target;
        }
    }
}
```

###### `transformResponse`

Removed. Modify `detail.ctx.text` in `htmx_after_request`:

```javascript
// htmx 2.x
transformResponse: function(text, xhr, elt) {
    var tpl = htmx.closest(elt, '[mustache-template]');
    if (tpl) {
        var data = JSON.parse(text);
        var template = htmx.find('#' + tpl.getAttribute('mustache-template'));
        return Mustache.render(template.innerHTML, data);
    }
    return text;
}

// htmx 4
htmx_after_request: (elt, detail) => {
    var tpl = elt.closest('[mustache-template]');
    if (tpl) {
        var data = JSON.parse(detail.ctx.text);
        var template = document.querySelector('#' + tpl.getAttribute('mustache-template'));
        detail.ctx.text = Mustache.render(template.innerHTML, data);
    }
}
```

Event flow: response received, `ctx.text` set, `htmx:after:request` fires, `ctx.text` consumed into fragment, `htmx:before:swap`.

###### `encodeParameters`

Removed. Modify `detail.ctx.request.body` in `htmx_config_request`:

```javascript
// htmx 2.x
onEvent: function(name, evt) {
    if (name === 'htmx:configRequest') {
        evt.detail.headers['Content-Type'] = 'application/json';
    }
},
encodeParameters: function(xhr, parameters, elt) {
    var object = {};
    parameters.forEach(function(value, key) {
        if (Object.hasOwn(object, key)) {
            if (!Array.isArray(object[key])) object[key] = [object[key]];
            object[key].push(value);
        } else {
            object[key] = value;
        }
    });
    return JSON.stringify(object);
}

// htmx 4
htmx_config_request: (elt, detail) => {
    detail.ctx.request.headers['Content-Type'] = 'application/json';
    var object = {};
    detail.ctx.request.body.forEach(function(value, key) {
        if (Object.hasOwn(object, key)) {
            if (!Array.isArray(object[key])) object[key] = [object[key]];
            object[key].push(value);
        } else {
            object[key] = value;
        }
    });
    detail.ctx.request.body = JSON.stringify(object);
}
```

`ctx.request.body` is FormData in `htmx_config_request`. It can be replaced with any value (string, JSON, URLSearchParams). For GET/DELETE, body becomes query parameters. For POST/PUT/PATCH, body becomes URLSearchParams (unless multipart).

###### `isInlineSwap` and `handleSwap`

Both replaced by `handle_swap`:

```javascript
// htmx 2.x
isInlineSwap: function(swapStyle) {
    return swapStyle === 'morphdom';
},
handleSwap: function(swapStyle, target, fragment) {
    if (swapStyle === 'morphdom') {
        morphdom(target, fragment.firstElementChild || fragment.firstChild);
        return [target];
    }
}

// htmx 4
handle_swap: (swapStyle, target, fragment) => {
    if (swapStyle === 'morphdom') {
        morphdom(target, fragment.firstElementChild || fragment.firstChild);
        return true;
    }
    return false;
}
```

Return truthy if handled, falsy otherwise. Can return an array of elements for settle tracking.

##### Removed Callbacks

| htmx 2.x callback | htmx 4 replacement |
|---|---|
| `getSelectors()` | `htmx_after_init` hook |
| `onEvent(name, evt)` | Individual `htmx_*` hooks |
| `transformResponse(text, xhr, elt)` | `htmx_after_request` hook (modify `detail.ctx.text`) |
| `encodeParameters(xhr, params, elt)` | `htmx_config_request` hook (modify `detail.ctx.request.body`) |
| `isInlineSwap(swapStyle)` | `handle_swap` or name swap style with "outer" prefix |
| `handleSwap(style, target, frag, info)` | `handle_swap(style, target, frag, spec)` |

##### Checklist

1. Rename `defineExtension` to `registerExtension`
2. Replace `onEvent` with individual `htmx_*` hooks
3. Replace `transformResponse` with `htmx_after_request`
4. Replace `encodeParameters` with `htmx_config_request`
5. Merge `isInlineSwap` and `handleSwap` into `handle_swap`
6. Replace `getSelectors` with `htmx_after_init`
7. Remove `hx-ext` attributes from HTML
8. Update event names (colons to underscores in hook names)
9. Test custom swap styles with OOB swaps

## Core Concepts

### [Mental Model](https://four.htmx.org/docs/core-concepts/mental-model)



htmx extends HTML's built-in concept of [hypermedia controls](https://dl.acm.org/doi/fullHtml/10.1145/3648188.3675127).

To understand htmx, you should first understand what these are.

#### HTML's Native Controls

HTML has two major elements that issue HTTP requests in response to user actions: `` (anchors, aka "links") and
``.

##### The Anchor Tag

```html
Blog
```

When a user click this link a browser will issue an HTTP `GET` request to `/blog`. It will then load the HTML response
into the browser's window.

##### The Form Tag

```html


    Email: 
    

```

When a user submits this form (by, say, clicking on the "Submit" button) a browser will issue an HTTP `POST` request to
`/register`. Again, it will load the HTML response to this request into the browser window.

These two hypermedia controls demonstrate the core idea behind them: in response to a user action a
request is made and new content is loaded into the client.

#### Transclusion

Both of these HTML elements support a (relatively little-known and unused)
[`target`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/target) attribute.

By using this attribute you can place the response in, for example, an iframe rather than replacing the entire
content in the window:

```html


    Email: 
    


    <!-- Response appears here -->

```

This is [transclusion](https://en.wikipedia.org/wiki/Transclusion), where one HTML document is included inside of
another.

#### How htmx Extends This Idea

htmx generalizes these concepts. Any element can issue any type of HTTP request to any URL. Any event can trigger the
request. And the response HTML can be placed anywhere in the DOM.

```html



```

These htmx attributes (which start with `hx-`) tell a browser:

> When a user clicks this button, issue a POST request to `/clicked`. Use the response to replace the element with id
`output`.

Like anchor and form tags, htmx expects _HTML responses_ from the server.

This is in contrast with many front-end libraries and frameworks today which instead expect JSON and
use client-side templating to transform that JSON into HTML on the client.

#### htmx's Philosophy

Because htmx works in terms of HTML it follows the [original web programming model](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). 
It uses [Hypertext As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS) (HATEOAS).

The server controls what the user sees by sending HTML.  Users select actions from that HTML and the server responds with
more HTML (i.e. hypertext). 

Thus, the hypermedia itself drives the application.

### [Hypermedia Controls](https://four.htmx.org/docs/core-concepts/hypermedia-controls)

htmx extends HTML with attributes that control how requests are made and how responses update the page.

#### Making Requests

Add [`hx-get`](https://four.htmx.org/reference/attributes/hx-get) to an element. It makes an AJAX request when clicked.

**Your HTML:**
```html

```

**What the server returns:**
```html
You have 3 new messages
```

**What the user sees:**
```html

```

The response replaced the button's content. No JavaScript required.

##### How It Works

| Step                  | What Happens                     |
|-----------------------|----------------------------------|
| 1. User clicks button | htmx intercepts the click        |
| 2. htmx makes request | Sends GET request to `/messages` |
| 3. Server responds    | Returns HTML (not JSON)          |
| 4. htmx updates page  | Swaps HTML into the button       |

##### HTTP Methods

Use different attributes for different operations:

```html





```

Each attribute combines the URL and HTTP method.

##### Common Patterns

**Load data on click:**
```html

```

**Submit a form:**
```html

    
    

```

Form submits via AJAX instead of full page reload.

**Delete an item:**
```html

```

##### What Gets Sent

htmx sends standard HTTP requests:

**Request to server:**
```
GET /messages HTTP/1.1
HX-Request: true
HX-Target: button
```

htmx adds custom headers so your server knows it's an htmx request.

**Server response:**
```html
HTTP/1.1 200 OK
Content-Type: text/html

You have 3 new messages
```

Just HTML. No JSON parsing needed.

#### Triggers

By default, requests are triggered by the "natural" event of an element:

* `input`, `textarea` & `select` are triggered on the `change` event
* `form` is triggered on the `submit` event
* everything else is triggered by the `click` event

If you want different behavior you can use the [`hx-trigger`](https://four.htmx.org/reference/attributes/hx-trigger)
attribute to specify which event will cause the request.

Here is a `div` that posts to `/mouse_entered` when a mouse enters it:

```html

    Mouse Trap

```

##### Trigger Modifiers

A trigger can also have additional modifiers that change its behavior. For example, if you want a request to only
happen once, you can use the `once` modifier for the trigger:

```html

    Mouse Trap

```

Other modifiers you can use for triggers are (parsed as [HCON](https://four.htmx.org/docs/core-concepts/hcon#hx-trigger-modifiers)):

* `changed` - only issue a request if the value of the element has changed
* `delay:` - wait the given amount of time (e.g. `1s`) before
  issuing the request. If the event triggers again, the countdown is reset.
* `throttle:` - wait the given amount of time (e.g. `1s`) before
  issuing the request. Unlike `delay` if a new event occurs before the time limit is hit the event will be discarded,
  so the request will trigger at the end of the time period.
* `from:` - listen for the event on a different element. This can be used for things like keyboard
  shortcuts. Note that this CSS selector is not re-evaluated if the page changes.

Multiple triggers can be specified in the [`hx-trigger`](https://four.htmx.org/reference/attributes/hx-trigger) attribute, separated by commas.

You can use these features to implement many common UX patterns, such as [Active Search](https://four.htmx.org/patterns/forms/active-search):

```html


```

This input will issue a request 500 milliseconds after an input event occurs, or the `enter` key is pressed and inserts
the results into the `div` with the id `search-results`.

##### Trigger Filters

In the example above, you may have noticed the square brackets after the event name. This is called a "trigger filter".

Trigger filters allow you to place a filtering javascript expression after the event name that will prevent the trigger
if the filter does not return true.

Here is an example that triggers only on a Shift-Click of the element

```html

    Shift Click Me

```

Properties like `shiftKey` will be resolved against the triggering event first, then against the global scope.

The `this` symbol will be set to the current element.

##### Special Events

htmx provides a few special events for use in [`hx-trigger`](https://four.htmx.org/reference/attributes/hx-trigger):

* `load` - fires once when the element is first loaded
* `revealed` - fires once when an element first scrolls into the viewport
* `intersect` - fires once when an element first intersects the viewport. This supports two additional options:
    * `root:` - a CSS selector of the root element for intersection
    * `threshold:` - a floating point number between 0.0 and 1.0, indicating what amount of intersection to fire
      the event on

You can also use custom events to trigger requests.

##### Polling

Polling is a simple technique where a web page periodically issues a request to the server to see if any updates have
occurred. It is not very highly respected in many web development circles, but it is simple, can be relatively
resource-light because it does not maintain a constant network connection, and it tolerates network failures well

In htmx you can implement polling via the `every` syntax in the [`hx-trigger`](https://four.htmx.org/reference/attributes/hx-trigger) attribute:

```html

```

This tells htmx:

> Every 2 seconds, issue a GET to /news and load the response into the div

##### Load Polling

Another technique that can be used to achieve polling in htmx is "load polling", where an element specifies
a `load` trigger along with a delay, and replaces itself with the response:

```html


```

If the `/messages` end point keeps returning a div set up this way, it will keep "polling" back to the URL every
second.

Load polling can be useful in situations where a poll has an end point at which point the polling terminates, such as
when you are showing the user a [progress bar](https://four.htmx.org/patterns/loading/progress-bar).

##### Request Indicators

When an AJAX request is issued it is often good to let the user know that something is happening since the browser
will not give them any feedback. You can accomplish this in htmx by using `htmx-indicator` class.

The `htmx-indicator` class is defined so that the opacity of any element with this class is `0` by default, making it
invisible but present in the DOM.

When htmx issues a request, it will put a `htmx-request` class onto an element (either the requesting element or
another element, if specified). The `htmx-request` class will cause a child element with the `htmx-indicator` class
on it to transition to an opacity of `1`, showing the indicator.

```html

```

Here we have a button. When it is clicked the `htmx-request` class will be added to it, which will reveal the spinner
gif element.

The `htmx-indicator` class uses opacity to hide and show the progress indicator but if you would prefer another
mechanism you can create your own CSS transition like so:

```css
.htmx-indicator {
    display: none;
}

.htmx-request .htmx-indicator {
    display: inline;
}

.htmx-request.htmx-indicator {
    display: inline;
}
```

If you want the `htmx-request` class added to a different element, you can use
the [`hx-indicator`](https://four.htmx.org/reference/attributes/hx-indicator)
attribute with a CSS selector to do so:

```html

    
    

```

Here we call out the indicator explicitly by id.

Note that we could have placed the class on the parent `div` as well and had the same effect.

You can also add the [`disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled) to
elements for the duration of a request by using the [`hx-disable`](https://four.htmx.org/reference/attributes/hx-disable) attribute.

#### Targets

By default, responses replace the element that made the request.

Change this with [`hx-target`](https://four.htmx.org/reference/attributes/hx-target).

```html



    

```

The button makes the request.

The response loads into `#results`.

The button stays unchanged.

##### Extended Selectors

Use [extended selectors](https://four.htmx.org/docs/features/extended-selectors) to target elements flexibly.

Beyond standard CSS selectors, you can use:

* [`this`](https://four.htmx.org/docs/features/extended-selectors#this) - target the element itself
* [`closest `](https://four.htmx.org/docs/features/extended-selectors#closest-selector) - find the nearest ancestor
* [`find `](https://four.htmx.org/docs/features/extended-selectors#find-selector) - find the first child
* [`next`](https://four.htmx.org/docs/features/extended-selectors#next) - target the next sibling
* [`next `](https://four.htmx.org/docs/features/extended-selectors#next-selector) - find next sibling matching ``
* [`previous`](https://four.htmx.org/docs/features/extended-selectors#previous) - target the previous sibling
* [`previous `](https://four.htmx.org/docs/features/extended-selectors#previous-selector) - find previous sibling matching ``
* And more...

See the full [extended selectors guide](https://four.htmx.org/docs/features/extended-selectors) for all options and examples.

This keeps your HTML cleaner without requiring `id` attributes everywhere.

#### Swaps

htmx offers many different ways to swap the HTML returned into the DOM. By default, the content replaces the
[innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) of the target element, which is called
an `innerHTML` swap.

This is similar to how the `target` attribute on links and forms works, placing the retrieved document within an iframe.

You can modify this by using the [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) attribute with any of the following values:

| Name                        | Description                                                                                                                               |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `innerHTML`                 | the default, puts the content inside the target element                                                                                   |
| `outerHTML`                 | replaces the entire target element with the returned content                                                                              |
| `beforebegin` (or `before`) | prepends the content before the target in the target's parent element                                                                     |
| `afterbegin` (or `prepend`) | prepends the content before the first child inside the target                                                                             |
| `beforeend` (or `append`)   | appends the content after the last child inside the target                                                                                |
| `afterend` (or `after`)     | appends the content after the target in the target's parent element                                                                       |
| `delete`                    | deletes the target element regardless of the response                                                                                     |
| `none`                      | does not append content from response ([Out of Band Swaps](#oob_swaps) and [Response Headers](#response-headers) will still be processed) |
| `innerMorph`                | morphs the children of the target element, preserving as much of the existing DOM as possible                                             |
| `outerMorph`                | morphs the target element itself, preserving as much of the existing DOM as possible                                                      |
| `textContent`               | Set the target's text content (no HTML parsing)                                                                                           |

##### Morph Swaps

htmx includes built-in `innerMorph` and `outerMorph` swaps that merge new content into the existing DOM rather than
simply replacing it. They often do a better job preserving things like focus, video state, etc. by mutating existing
nodes in-place during the swap operation, at the cost of more CPU.

Consider this HTML:

```html

    Title
    


```

If the response content for this looks like this:

```html

    
    Title

```

Then htmx will "morph" the existing content to the new structure. Note that the `h1` element has moved below the
video. With the `outerHTML` swap this will cause the video to stop playing and reset. However, the morphing algorithm
uses ID elements to intelligently mutate the DOM and preserve the existing video element, keeping the video playing
smoothly.

Note that a similar effect can be achieved with the [`hx-preserve`](https://four.htmx.org/reference/attributes/hx-preserve) attribute, discussed below.

###### Excluding Elements from Morphing

Exclude specific elements from morphing using config options:

- [`htmx.config.morphSkip`](https://four.htmx.org/reference/config/htmx-config-morphskip) - Completely skip morphing specific elements (they stay frozen)
- [`htmx.config.morphSkipChildren`](https://four.htmx.org/reference/config/htmx-config-morphskipchildren) - Update element attributes but preserve children

Useful for third-party widgets, custom web components, or active animations.

##### View Transitions

The [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
gives developers a way to create an animated transition between different DOM states.

htmx supports view transitions via:
- Setting `htmx.config.transitions` to `true` globally
- Per-swap via `hx-swap` `transition` property: `hx-swap="outerHTML transition:true"`
- For boosted elements: [`hx-boost`](https://four.htmx.org/reference/attributes/hx-boost)`="transition:true"`

##### Swap Options

The [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) attribute also supports options for tuning the swapping behavior of htmx. For
example, by default htmx will swap in the title of a title tag found anywhere in the new content. You can turn this
behavior off by setting the `ignoreTitle` modifier to true:

```html

```

The modifiers available on `hx-swap` are (parsed as [HCON](https://four.htmx.org/docs/core-concepts/hcon#hx-swap-modifiers)):

| Option       | Description                                                                                          |
|--------------|------------------------------------------------------------------------------------------------------|
| swap         | A time interval (e.g., 100ms, 1s) to delay the swap operation                                        |
| transition   | true or false, whether to use the view transition API for this swap                                  |
| ignoreTitle  | If set to true, any title found in the new content will be ignored and not update the document title |
| strip        | true or false, whether to strip the outer element when swapping (unwrap the content)                 |
| focus-scroll | true or false, whether to scroll focused elements into view                                          |
| scroll       | top or bottom, will scroll the target element to its top or bottom                                   |
| show         | top or bottom, will scroll the target element's top or bottom into view                              |
| target       | A selector to retarget the swap to a different element                                               |

All swap modifiers appear after the swap style is specified, and are colon-separated.

See the [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) documentation for more details on these options.

#### Parameters

By default, an element that causes a request will include its `value` if it has one. If the element is a form it
will include the values of all inputs within it.

As with HTML forms, the `name` attribute of the input is used as the parameter name in the request that htmx sends.

Additionally, if the element causes a non-`GET` request, the values of all the inputs of the associated form will be
included (typically this is the nearest enclosing form, but could be different if e.g. `
```

```html

    
    





```

In this example:

- Successful responses (2xx) swap into `#result` (default behavior)
- `422` responses swap into `#validation-errors`
- `500` responses swap into `#server-error`
- `503` responses don't swap at all

##### Request Headers

htmx includes headers in the requests it makes:

| Header                       | Description                                                                                          |
|------------------------------|------------------------------------------------------------------------------------------------------|
| [`HX-Boosted`](https://four.htmx.org/reference/headers/HX-Boosted)                 | indicates that the request is via an element using [`hx-boost`](https://four.htmx.org/reference/attributes/hx-boost)                  |
| [`HX-Current-URL`](https://four.htmx.org/reference/headers/HX-Current-URL)             | the current URL of the browser                                                                       |
| [`HX-Request`](https://four.htmx.org/reference/headers/HX-Request)                 | always "true"                                                                                        |
| [`HX-Request-Type`](https://four.htmx.org/reference/headers/HX-Request-Type)            | `"partial"` for targeted swaps, `"full"` for body-level or `hx-select` requests                      |
| [`HX-Source`](https://four.htmx.org/reference/headers/HX-Source)                  | the source element in `tag#id` format (e.g. `button#submit`)                                         |
| [`HX-Target`](https://four.htmx.org/reference/headers/HX-Target)                  | the target element in `tag#id` format (e.g. `div#results`)                                           |

##### Response Headers

htmx supports htmx-specific response headers:

| Header                                           | Description                                                                                                                                                                        |
|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`HX-Location`](https://four.htmx.org/reference/headers/HX-Location)            | allows you to do a client-side redirect that does not do a full page reload                                                                                                        |
| [`HX-Push-Url`](https://four.htmx.org/reference/headers/HX-Push-Url)            | pushes a new url into the history stack                                                                                                                                            |
| [`HX-Redirect`](https://four.htmx.org/reference/headers/HX-Redirect)            | can be used to do a client-side redirect to a new location                                                                                                                         |
| [`HX-Refresh`](https://four.htmx.org/reference/headers/HX-Refresh)                                     | if set to "true" the client-side will do a full refresh of the page                                                                                                                |
| [`HX-Replace-Url`](https://four.htmx.org/reference/headers/HX-Replace-Url)      | replaces the current URL in the location bar                                                                                                                                       |
| [`HX-Reswap`](https://four.htmx.org/reference/headers/HX-Reswap)                                      | allows you to specify how the response will be swapped. See [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) for possible values                                                                     |
| [`HX-Retarget`](https://four.htmx.org/reference/headers/HX-Retarget)                                    | a CSS selector that updates the target of the content update to a different element on the page                                                                                    |
| [`HX-Reselect`](https://four.htmx.org/reference/headers/HX-Reselect)                                    | a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](https://four.htmx.org/reference/attributes/hx-select) on the triggering element |
| [`HX-Trigger`](https://four.htmx.org/reference/headers/HX-Trigger)              | allows you to trigger client-side events                                                                                                                                           |

For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](https://four.htmx.org/reference/headers/HX-Trigger).

Submitting a form via htmx has the benefit of no longer needing
the [Post/Redirect/Get Pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get).
After successfully processing a POST request on the server, you don't need to return
a [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). You can directly return the new HTML fragment.

Also, the response headers above are not provided to htmx for processing with 3xx Redirect response codes
like [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). Instead, the browser will intercept the redirection
internally and return the headers and response from the redirected URL. Where possible use alternative response codes
like `200` to allow returning of these response headers.

### [Client-Side Scripting](https://four.htmx.org/docs/core-concepts/client-scripting)


Changes in htmx 4.0

htmx 4.0 changed event names significantly when compared with htmx 2.0, making them much more standardized.

See the full event mapping in the [Changes in htmx 4.0](https://four.htmx.org/docs/get-started/migration) document.

**Note:** All events now provide a consistent `ctx` object with request/response information.



While htmx encourages a hypermedia approach to building web applications, it offers many options for client scripting.
Scripting is included in the REST-ful description of web architecture,
see: [Code-On-Demand](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7). As much as is
feasible, we recommend a [hypermedia-friendly](https://four.htmx.org/essays/hypermedia-friendly-scripting) approach to scripting in your web
application:

* [Respect HATEOAS](https://four.htmx.org/essays/hypermedia-friendly-scripting#prime_directive)
* [Use events to communicate between components](https://four.htmx.org/essays/hypermedia-friendly-scripting#events)
* [Use islands to isolate non-hypermedia components from the rest of your application](https://four.htmx.org/essays/hypermedia-friendly-scripting#islands)
* [Consider inline scripting](https://four.htmx.org/essays/hypermedia-friendly-scripting#inline)

The primary integration point between htmx and scripting solutions is the events that htmx sends and can respond to.

We have an entire chapter entitled ["Client-Side Scripting"](https://hypermedia.systems/client-side-scripting/) in [our
book](https://hypermedia.systems) that looks at how scripting can be integrated into your htmx-based application.

#### Events

Htmx has an extensive events mechanism, which doubles as the logging system.

If you want to register for a given htmx event you can use

```javascript
document.body.addEventListener('htmx:after:init', function (evt) {
    myJavascriptLib.init(evt.detail.elt);
});
```

or, if you would prefer, you can use the following htmx helper:

```javascript
htmx.on("htmx:after:init", function (evt) {
    myJavascriptLib.init(evt.detail.elt);
});
```

The `htmx:after:process` event is fired every time an element is processed by htmx, and is effectively the equivalent
to the normal `load` event.

##### Initialize A 3rd Party Library With Events

Using the `htmx:after:process` event to initialize content is so common that htmx provides a helper function:

```javascript
htmx.onLoad(function (target) {
    myJavascriptLib.init(target);
});
```

This does the same thing as the first example, but is a little cleaner.

##### Configure a Request With Events

You can handle the [`htmx:config:request`](https://four.htmx.org/reference/events/htmx-config-request) event in order to modify an AJAX request
before it is issued:

```javascript
document.body.addEventListener('htmx:config:request', function (evt) {
    evt.detail.ctx.request.parameters['auth_token'] = getAuthToken(); // add a new parameter into the request
    evt.detail.ctx.request.headers['Authentication-Token'] = getAuthToken(); // add a new header into the request
});
```

Here we add a parameter and header to the request before it is sent.

#### The `hx-on:*` Attributes

HTML allows the embedding of inline scripts via the [
`onevent` properties](https://developer.mozilla.org/en-US/docs/Web/Events/Event_handlers#using_onevent_properties),
such as `onClick`:

```html

```

This feature allows scripting logic to be co-located with the HTML elements the logic applies to, giving good
[Locality of Behaviour (LoB)](https://four.htmx.org/essays/locality-of-behaviour).

Unfortunately, HTML only allows `on*` attributes for a fixed
number of [specific DOM events](https://www.w3schools.com/tags/ref_eventattributes.asp) (e.g. `onclick`) and
doesn't provide a generalized mechanism for responding to arbitrary events on elements.

In order to address this shortcoming, htmx offers [`hx-on:*`](https://four.htmx.org/reference/attributes/hx-on) attributes.

These attributes allow you to respond to any event in a manner that preserves the LoB of the standard `on*` properties,
and provide some nice quality of life improvements over the standard javascript API.

If you want to respond to the `click` event using an `hx-on` attribute, we would write this:

```html

```

So, the string `hx-on`, followed by a colon (or a dash), then by the name of the event.

##### The Scripting API

htmx provides some top level helper methods in `hx-on` handlers that make async scripting more enjoyable:

| function    | description                                                                                                                          |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `find()`    | allows you to find content relative to the current element (e.g. `find('next div')` will find the next div after the current element |
| `findAll()` | allows you to find multiple elements relative to the current element                                                                 |
| `timeout()` | allows you to wait for a given amount of time (e.g. `await timeout(100)` before continuing                                           |

##### Scripting Examples

Here is an example that adds a parameter to an htmx request


```

Here the `example` parameter is added to the `POST` request before it is issued, with the value 'Hello Scripting!'.

Another use case is to [reset user input](https://four.htmx.org/patterns/forms/reset-on-submit) on successful requests using the [`htmx:after:swap`](https://four.htmx.org/reference/events/htmx-after-swap)
event:

```html

```

## 3rd Party Javascript

Htmx integrates well with third party libraries.

If the library fires events on the DOM, you can use those events to trigger requests from htmx.

A good example of this is the [SortableJS demo](https://four.htmx.org/patterns/records/drag-to-reorder):

```html

    Updating...
    Item 1
    Item 2
    Item 3

```

With Sortable, as with most javascript libraries, you need to initialize content at some point.

In htmx, the cleanest way to do this is using the `htmx.onLoad()` method to register a callback.

This callback will be called whenever htmx inserts new content into the DOM, allowing you to initialize
any widgets in the new content.

```js
htmx.onLoad((content) => {
    var sortables = content.querySelectorAll(".sortable");
    for (var i = 0; i < sortables.length; i++) {
        var sortable = sortables[i];
        new Sortable(sortable, {
            animation: 150,
            ghostClass: 'blue-background-class'
        });
    }
})
```

This will ensure that as new content is added to the DOM by htmx, sortable elements are properly initialized.

## See Also

- [`hx-on`](https://four.htmx.org/reference/attributes/hx-on) (attribute)
- [Hypermedia-Friendly Scripting](https://four.htmx.org/essays/hypermedia-friendly-scripting) (essay)
- [Locality of Behaviour](https://four.htmx.org/essays/locality-of-behaviour) (essay)

### [Multi-Target Updates](https://four.htmx.org/docs/core-concepts/multi-target-updates)

#### The Problem

htmx requests normally update one target element. Sometimes you need to update multiple parts of the page at once.

For example: After submitting a form, you want to update both the form itself and a notification counter.

#### The Solution

htmx provides two ways to update multiple targets from a single response:

1. **Out-of-Band Swaps** - Match elements by their `id` attribute
2. **Partial Tags** - Explicitly specify where content goes

Choose the method that fits your needs.

#### Out-of-Band Swaps

Use out-of-band swaps when you want to match elements by their `id`.

Add [`hx-swap-oob`](https://four.htmx.org/reference/attributes/hx-swap-oob)`="true"` to any element in your response. htmx will find the element with the same `id` in your page and swap it.

**Server response:**

```html

    Form submitted successfully!



    

```

**Result:**
- The `div#message` updates wherever it exists in your page
- The form updates in its normal target location

##### Customize the Swap

Specify a different swap style:

```html

    New notification

```

This appends the content to `div#notifications` instead of replacing it.

##### Target a Different Element

Override the `id` matching by specifying a custom target:

```html

    Processing...

```

This swaps the content into the element matching `#status`, regardless of the element's own `id`.

##### When to Use Out-of-Band Swaps

Use out-of-band swaps when:
- Elements have consistent, unique `id` attributes
- You want simple, ID-based updates
- You're updating notification areas, counters, or status indicators

#### Partials (``)

Use partials when you need explicit control over targeting.

Wrap content in `` tags. Specify where it goes with [`hx-target`](https://four.htmx.org/reference/attributes/hx-target).

**Server response:**

```html

    New message content



    5



    

```

**Result:**
- First partial's content appends to `#messages`
- Second partial's content replaces contents of `#notifications`
- Form updates in its normal target location

##### Attributes

Each `` accepts:

- [`hx-target`](https://four.htmx.org/reference/attributes/hx-target) - CSS selector for where to place content
- `id` - Shorthand alternative to `hx-target`. Targets the element with that ID (e.g. `` targets `#messages`)
- [`hx-swap`](https://four.htmx.org/reference/attributes/hx-swap) - Optional. Swap style (defaults to `innerHTML`)

Either `hx-target` or `id` is required. If both are present, `hx-target` takes precedence.


Alternative syntax for template languages that strip unknown tags

You can use the equivalent `