Add descriptions for attribute pages (#3158)

williamjacksn · web-flow · commit 46badfe0b141 · 2025-02-07T17:07:13.000-07:00
Descriptions for attribute pages
diff --git a/www/content/attributes/hx-boost.md b/www/content/attributes/hx-boost.md
@@ -1,5 +1,9 @@
 +++
 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
diff --git a/www/content/attributes/hx-confirm.md b/www/content/attributes/hx-confirm.md
@@ -1,5 +1,9 @@
 +++
 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
diff --git a/www/content/attributes/hx-delete.md b/www/content/attributes/hx-delete.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-disable.md b/www/content/attributes/hx-disable.md
@@ -1,5 +1,6 @@
 +++
 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 
diff --git a/www/content/attributes/hx-disabled-elt.md b/www/content/attributes/hx-disabled-elt.md
@@ -1,5 +1,8 @@
 +++
 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
@@ -16,7 +19,7 @@ added to them for the duration of the request. The value of this attribute can b
   (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)
+  (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:
 
diff --git a/www/content/attributes/hx-disinherit.md b/www/content/attributes/hx-disinherit.md
@@ -1,5 +1,9 @@
 +++
 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
diff --git a/www/content/attributes/hx-encoding.md b/www/content/attributes/hx-encoding.md
@@ -1,5 +1,9 @@
 +++
 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`
diff --git a/www/content/attributes/hx-ext.md b/www/content/attributes/hx-ext.md
@@ -1,5 +1,8 @@
 +++
 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.
diff --git a/www/content/attributes/hx-get.md b/www/content/attributes/hx-get.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-headers.md b/www/content/attributes/hx-headers.md
@@ -1,5 +1,7 @@
 +++
 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.
diff --git a/www/content/attributes/hx-history-elt.md b/www/content/attributes/hx-history-elt.md
@@ -1,5 +1,8 @@
 +++
 title = "hx-history-elt"
+description = """\
+  The hx-history-elt attribute in htmx allows you to specify the element that will be used to snapshot and restore \
+  page state during navigation. In most cases we do not recommend using this element."""
 +++
 
 The `hx-history-elt` attribute allows you to specify the element that will be used to snapshot and
diff --git a/www/content/attributes/hx-history.md b/www/content/attributes/hx-history.md
@@ -1,5 +1,9 @@
 +++
 title = "hx-history"
+description = """\
+  The hx-history attribute in htmx allows you to prevent sensitive page data from being stored in the browser's \
+  localStorage cache during history navigation, ensuring that the page state is retrieved from the server instead when \
+  navigating through history."""
 +++
 
 Set the `hx-history` attribute to `false` on any element in the current document, or any html fragment loaded into the current document by htmx, to prevent sensitive data being saved to the localStorage cache when htmx takes a snapshot of the page state. 
diff --git a/www/content/attributes/hx-include.md b/www/content/attributes/hx-include.md
@@ -1,5 +1,6 @@
 +++
 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
@@ -14,7 +15,7 @@ attribute can be:
 * `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)
+  (e.g. `previous .error` will target the closest previous sibling with `error` class)
 
 Here is an example that includes a separate input value:
 
diff --git a/www/content/attributes/hx-indicator.md b/www/content/attributes/hx-indicator.md
@@ -1,5 +1,9 @@
 +++
 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
diff --git a/www/content/attributes/hx-inherit.md b/www/content/attributes/hx-inherit.md
@@ -1,5 +1,9 @@
 +++
 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
diff --git a/www/content/attributes/hx-on.md b/www/content/attributes/hx-on.md
@@ -1,5 +1,8 @@
 +++
 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 
diff --git a/www/content/attributes/hx-params.md b/www/content/attributes/hx-params.md
@@ -1,5 +1,7 @@
 +++
 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.  
diff --git a/www/content/attributes/hx-patch.md b/www/content/attributes/hx-patch.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-post.md b/www/content/attributes/hx-post.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-preserve.md b/www/content/attributes/hx-preserve.md
@@ -1,5 +1,8 @@
 +++
 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.
diff --git a/www/content/attributes/hx-prompt.md b/www/content/attributes/hx-prompt.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-push-url.md b/www/content/attributes/hx-push-url.md
@@ -1,5 +1,8 @@
 +++
 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).
diff --git a/www/content/attributes/hx-put.md b/www/content/attributes/hx-put.md
@@ -1,5 +1,8 @@
 +++
 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
diff --git a/www/content/attributes/hx-replace-url.md b/www/content/attributes/hx-replace-url.md
@@ -1,5 +1,7 @@
 +++
 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).
diff --git a/www/content/attributes/hx-request.md b/www/content/attributes/hx-request.md
@@ -1,5 +1,8 @@
 +++
 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:
diff --git a/www/content/attributes/hx-select-oob.md b/www/content/attributes/hx-select-oob.md
@@ -1,5 +1,8 @@
 +++
 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.  
diff --git a/www/content/attributes/hx-select.md b/www/content/attributes/hx-select.md
@@ -1,5 +1,6 @@
 +++
 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
diff --git a/www/content/attributes/hx-swap-oob.md b/www/content/attributes/hx-swap-oob.md
@@ -1,9 +1,13 @@
 +++
 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 piggy back updates to other element updates on a response.
+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:
 
@@ -72,7 +76,7 @@ A `<p>` can be encapsulated in `<div>` or `<span>`:
 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:
+Here is an example with an out-of-band swap of a table row being encapsulated in this way:
 
 ```html
 <div>
@@ -91,7 +95,7 @@ Note that these template tags will be removed from the final content of the page
 
 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:
+Here is an example with an out-of-band swap of svg elements being encapsulated in this way:
 
 ```html
 <div>
@@ -111,7 +115,7 @@ Note that these `template` and `svg` wrapping tags will be removed from the fina
 ## 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 a 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 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.
 
diff --git a/www/content/attributes/hx-swap.md b/www/content/attributes/hx-swap.md
@@ -1,5 +1,8 @@
 +++
 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 AJAZ 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
diff --git a/www/content/attributes/hx-sync.md b/www/content/attributes/hx-sync.md
@@ -1,5 +1,6 @@
 +++
 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.
diff --git a/www/content/attributes/hx-target.md b/www/content/attributes/hx-target.md
@@ -1,5 +1,8 @@
 +++
 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
@@ -16,7 +19,7 @@ request.  The value of this attribute can be:
   (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)
+  (e.g. `previous .error` will target the closest previous sibling with `error` class)
 
 
 Here is an example that targets a div:
diff --git a/www/content/attributes/hx-trigger.md b/www/content/attributes/hx-trigger.md
@@ -1,5 +1,10 @@
 +++
 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
@@ -69,7 +74,7 @@ is seen again before the delay completes, it is ignored, the element will trigge
       (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)
+      (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
diff --git a/www/content/attributes/hx-validate.md b/www/content/attributes/hx-validate.md
@@ -1,5 +1,8 @@
 +++
 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)
diff --git a/www/content/attributes/hx-vals.md b/www/content/attributes/hx-vals.md
@@ -1,5 +1,7 @@
 +++
 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.
diff --git a/www/content/attributes/hx-vars.md b/www/content/attributes/hx-vars.md
@@ -1,5 +1,9 @@
 +++
 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.**
