Ything-RepoMirrors/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2026-01-25 05:06:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs updates

Browse Source
This commit is contained in:
Carson Gross
2025-12-06 11:01:23 -07:00
parent 78b5e2b865
commit c5f6e88ffd
4 changed files with 63 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
www/content/api.md
View File

@@ -330,7 +330,7 @@ Note that using a [meta tag](@/docs.md#configuring-htmx) is the preferred mechan
* `logAll` - boolean: if true, htmx will log all events for debugging (default: `false`)
* `prefix` - string: custom prefix for htmx attributes (default: `""`)
* `transitions` - boolean: whether to use view transitions when swapping (default: `true`)
* `transitions` - boolean: whether to use view transitions when swapping (default: `false`)
* `history` - boolean: whether to enable history support (default: `true`)
* `historyReload` - boolean: if true, do full reload on history navigation (default: `false`)
* `mode` - string: the fetch mode for AJAX requests (default: `'same-origin'`)
@@ -342,7 +342,7 @@ Note that using a [meta tag](@/docs.md#configuring-htmx) is the preferred mechan
* `inlineScriptNonce` - string: nonce to add to inline scripts (default: `''`)
* `inlineStyleNonce` - string: nonce to add to inline styles (default: `''`)
* `extensions` - string: comma-separated list of extensions to load (default: `''`)
* `streams` - object: SSE stream configuration with properties:
* `sse` - object: SSE/streaming configuration properties:
* `reconnect` - boolean: whether to reconnect on disconnect (default: `false`)
* `reconnectMaxAttempts` - number (default: `10`)
* `reconnectDelay` - number in ms (default: `500`)
@@ -353,6 +353,7 @@ Note that using a [meta tag](@/docs.md#configuring-htmx) is the preferred mechan
* `noSwap` - array: HTTP status codes that should not trigger a swap (default: `[204, 304]`)
* `implicitInheritance` - boolean: inherit attributes automatically without `:inherited` (default: `false`)
* `metaCharacter` - string: custom character for attribute modifiers instead of `:` (default: `undefined`)
* `version` - string: the version of the current htmx library
##### Example

43
www/content/attributes/hx-swap.md
View File

@@ -41,7 +41,23 @@ The `hx-swap` attributes supports modifiers for changing the behavior of the swa
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`.
setting the `htmx.config.transitions` config setting to `true`.
Note that the default view transition is a cross-fade effect that takes
[250 milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using) to complete. During a view
transition, the application will not allow user interactions and, thus, can make the web application feel unresponsive.
We strongly recommend a much lower transition time, in the sub-50ms range. Here is how you would update the default
view transition to take only 20 milliseconds:
```css
::view-transition-group(*) {
animation-duration: 20ms;
}
```
This affords a much better user experience when using view transitions in most cases.
#### Timing: `swap` & `settle`
@@ -116,31 +132,6 @@ You may also use `window:top` and `window:bottom` to scroll to the top and botto
</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
* The default value of this attribute is `innerHTML`

51
www/content/docs.md
View File

@@ -559,8 +559,32 @@ Note that a similar effect can be achieved with the `hx-preserve` attribute, dis
The [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
gives developers a way to create an animated transition between different DOM states.
<!-- TODO - is this going to be true? -->
By default, htmx uses the viewTransition() API when swapping in content.
htmx supports view transitions in a few different ways:
* You can enable them globally by setting the `htmx.config.viewTransitions` property to `true`
* You can enable them on a per-swap basis via the `hx-swap` `transition` property:
```html
<button hx-post="/like" hx-swap="outerHTML transition:true">Like</button>
```
* You can enable them for all boosted elements via the `hx-boost` attribute
```html
<main hx-boost="transition:true"> ...
```
Note that the default view transition is a cross-fade effect that takes
[250 milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using) to complete. During a view
transition, the application will not allow user interactions and, thus, can make the web application feel unresponsive.
We strongly recommend a much lower transition time, in the sub-50ms range. Here is how you would update the default
view transition to take only 20 milliseconds:
```css
::view-transition-group(*) {
animation-duration: 20ms;
}
```
This affords a much better user experience when using view transitions in most cases.
#### Swap Options
@@ -574,16 +598,16 @@ behavior off by setting the `ignoreTitle` modifier to true:
The modifiers available on `hx-swap` are:
| Option | Description |
|--------------|------------------------------------------------------------------------------------------------------|
| swap | A time interval (e.g., 100ms, 1s) to delay the swap operation |
| transition | true or false, whether to use the view transition API for this swap |
| ignoreTitle | If set to true, any title found in the new content will be ignored and not update the document title |
| strip | true or false, whether to strip the outer element when swapping (unwrap the content) |
| focus-scroll | true or false, whether to scroll focused elements into view |
| scroll | top or bottom, will scroll the target element to its top or bottom |
| show | top or bottom, will scroll the target element's top or bottom into view |
| target | A selector to retarget the swap to a different element |
| Option | Description |
|----------------|------------------------------------------------------------------------------------------------------|
| `swap` | A time interval (e.g., 100ms, 1s) to delay the swap operation |
| `transition` | true or false, whether to use the view transition API for this swap |
| `ignoreTitle` | If set to true, any title found in the new content will be ignored and not update the document title |
| `strip` | true or false, whether to strip the outer element when swapping (unwrap the content) |
| `focus-scroll` | true or false, whether to scroll focused elements into view |
| `scroll` | top or bottom, will scroll the target element to its top or bottom |
| `show` | top or bottom, will scroll the target element's top or bottom into view |
| `target` | A selector to retarget the swap to a different element |
All swap modifiers appear after the swap style is specified, and are colon-separated.
@@ -761,6 +785,9 @@ included (typically this is the nearest enclosing form, but could be different i
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 add values programmatically to the request, you can use the [hx-vals](@/attributes/hx-vals.md) attribute
with either static JSON or JavaScript to dynamically compute values.
Finally, if you want to programmatically modify the parameters, you can use the [htmx:config:request](@/events.md#)
event.

6
www/content/reference.md
View File

@@ -52,6 +52,7 @@ All other attributes available in htmx.
| [`hx-replace-url`](@/attributes/hx-replace-url.md) | replace the URL in the browser location bar |
| [`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-vals`](@/attributes/hx-vals.md) | add values dynamically to the parameters that will be submitted with the request |
</div>
@@ -184,7 +185,7 @@ listed below:
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `htmx.config.logAll` | defaults to `false`, if set to `true` htmx will log all events to the console for debugging |
| `htmx.config.prefix` | defaults to `""` (empty string), allows you to use a custom prefix for htmx attributes (e.g., `"data-hx-"` to use `data-hx-get` instead of `hx-get`) |
| `htmx.config.transitions` | defaults to `true`, whether to use view transitions when swapping content (if browser supports it) |
| `htmx.config.transitions` | defaults to `false`, whether to use view transitions when swapping content (if browser supports it) |
| `htmx.config.history` | defaults to `true`, whether to enable history support (push/replace URL) |
| `htmx.config.historyReload` | defaults to `false`, if set to `true` htmx will do a full page reload on history navigation instead of an AJAX request |
| `htmx.config.mode` | defaults to `'same-origin'`, the fetch mode for AJAX requests. Can be `'cors'`, `'no-cors'`, or `'same-origin'` |
@@ -196,11 +197,12 @@ listed below:
| `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.extensions` | defaults to `''`, a comma-separated list of extension names to load (e.g., `'preload,optimistic'`) |
| `htmx.config.streams` | configuration for Server-Sent Events (SSE) streams. An object with the following properties: `reconnect` (default: `false`), `reconnectMaxAttempts` (default: `10`), `reconnectDelay` (default: `500`ms), `reconnectMaxDelay` (default: `60000`ms), `reconnectJitter` (default: `0.3`), `pauseInBackground` (default: `false`) |
| `htmx.config.sse` | configuration for Server-Sent Events (SSE) streams. An object with the following properties: `reconnect` (default: `false`), `reconnectMaxAttempts` (default: `10`), `reconnectDelay` (default: `500`ms), `reconnectMaxDelay` (default: `60000`ms), `reconnectJitter` (default: `0.3`), `pauseInBackground` (default: `false`) |
| `htmx.config.morphIgnore` | defaults to `["data-htmx-powered"]`, array of attribute names to ignore when morphing elements |
| `htmx.config.noSwap` | defaults to `[204, 304]`, array of HTTP status codes that should not trigger a swap |
| `htmx.config.implicitInheritance` | defaults to `false`, if set to `true` attributes will be inherited from parent elements automatically without requiring the `:inherited` modifier |
| `htmx.config.metaCharacter` | defaults to `undefined`, allows you to use a custom character instead of `:` for attribute modifiers (e.g., `-` to use `hx-get-inherited` instead of `hx-get:inherited`) |
| `htmx.config.version` | the version of the current htmx library |
</div>