12 |
13 | ## LSP
14 |
15 | Right now this is very much so a work in progress and currently provides basic autocomplete for _most_ HTMX attributes. We have reached a point where I could use help! If you want to fill in documentation or help with autocompletes please open an issue/pr!
16 |
17 | ## Integration
18 |
19 | ### Neovim
20 |
21 | `htmx-lsp` can be installed via Mason. And can be configured with `lspconfig`
22 |
23 | ```lua
24 | local lspconfig = require('lspconfig')
25 | -- ...
26 | lspconfig.htmx.setup{}
27 | ```
28 |
29 | Another option is to use [lsp-debug-tools](https://github.com/ThePrimeagen/lsp-debug-tools.nvim)
30 |
31 | ### VSCode
32 |
33 | No published extension yet, but there is a development extension in the [`clients/vscode`](client/vscode/README.md) folder (with setup instructions)
34 |
35 | ## Development
36 |
37 | ### General
38 |
39 | As of right now the general goal is just to provide completion for any `-`
40 | character received without even looking at the context.
41 |
42 | After that, would be to perform some code actions that make sense and allow for
43 | amazing utility around htmx.
44 |
45 | ```console
46 | htmx-lsp -f /path/to/file --level [OFF | TRACE | DEBUG | INFO | WARN | ERROR]
47 | ```
48 |
49 | ### Build
50 |
51 | ```console
52 | cargo build
53 |
54 | # OR auto-build on file save, requires `cargo-watch`
55 | cargo install cargo-watch
56 | cargo watch -x build
57 | ```
58 |
59 | ## Contributors
60 |
61 |
14 | These links will issue an ajax GET request to the respective URLs and replace the body’s inner content with it.
15 |
16 | Here is an example of a boosted form:
17 |
18 |
22 | This form will issue an ajax POST to the given URL and replace the body’s inner content with it.
23 |
24 | Notes
25 | hx-boost is inherited and can be placed on a parent element
26 | Only links that are to the same domain and that are not local anchors will be boosted
27 | All requests are done via AJAX, so keep that in mind when doing things like redirects
28 | To find out if the request results from a boosted anchor or form, look for HX-Boosted in the request header
29 | Selectively disable boost on child elements with hx-boost="false"
30 |
31 | [HTMX Reference](https://htmx.org/attributes/hx-boost/)
32 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-confirm.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | Here is an example:
4 |
5 |
8 |
9 | Notes
10 |
11 | hx-confirm is inherited and can be placed on a parent element
12 |
13 | [HTMX Reference](https://htmx.org/attributes/hx-confirm/)
14 |
15 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-delete.md:
--------------------------------------------------------------------------------
1 | hx-delete
2 |
3 | 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:
4 |
5 |
8 | This example will cause the button to issue a DELETE to /account and swap the returned HTML into the innerHTML of the body.
9 |
10 | Notes
11 | hx-delete is not inherited
12 | You can control the target of the swap using the hx-target attribute
13 | You can control the swap strategy by using the hx-swap attribute
14 | You can control what event triggers the request with the hx-trigger attribute
15 | You can control the data submitted with the request in various ways, documented here: Parameters
16 | 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
17 |
18 | [HTMX Reference](https://htmx.org/attributes/hx-delete/)
19 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-disable.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | The value of the tag is ignored, and it cannot be reversed by any content beneath it.
4 | Notes
5 |
6 | hx-disable is inherited
7 |
8 | [HTMX Reference](https://htmx.org/attributes/hx-disable/)
9 |
10 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-disabled-elt.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | The value of this attribute is a CSS query selector of the element or elements to apply the class to, or the keyword 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), or the keyword this.
4 |
5 | Here is an example with a button that will disable itself during a request:
6 |
7 |
10 |
11 | When a request is in flight, this will cause the button to be marked with the disabled attribute, which will prevent further clicks from occurring.
12 |
13 | Notes
14 |
15 | hx-disable-elt is inherited and can be placed on a parent element
16 |
17 | [HTMX reference](https://htmx.org/attributes/hx-disabled-elt/)
18 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-encoding.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | The value of this attribute should be multipart/form-data.
4 |
5 | The hx-encoding tag may be placed on parent elements.
6 | Notes
7 |
8 | hx-encoding is inherited and can be placed on a parent element
9 |
10 | [HTMX Reference](https://htmx.org/attributes/hx-encoding/)
11 |
12 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-ext.md:
--------------------------------------------------------------------------------
1 | reference an extension
2 |
3 | Tip: To use multiple extensions on one element, seperate them with a comma:
4 |
5 |
6 | by default, extensions are applied to the DOM node where it is invoked, along with all child elements inside of that parent node. If you need to disable an extension somewhere within the DOM tree, you can use the ignore: keyword to stop it from being used.
7 |
8 |
9 | [HTMX Reference](https://htmx.org/attributes/hx-ext/)
10 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-get.md:
--------------------------------------------------------------------------------
1 | hx-get
2 |
3 | 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:
4 |
5 |
Get Some HTML
6 | This example will cause the div to issue a GET to /example and swap the returned HTML into the innerHTML of the div.
7 |
8 | Notes
9 | hx-get is not inherited
10 | By default hx-get does not include any parameters. You can use the hx-params attribute to change this
11 | You can control the target of the swap using the hx-target attribute
12 | You can control the swap strategy by using the hx-swap attribute
13 | You can control what event triggers the request with the hx-trigger attribute
14 | You can control the data submitted with the request in various ways, documented here: Parameters
15 |
16 |
17 | [HTMX Reference](https://htmx.org/attributes/hx-get/)
18 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-headers.md:
--------------------------------------------------------------------------------
1 | The hx-headers attribute allows you to add to the headers that will be submitted with an AJAX request.
2 |
3 | By default, the value of this attribute is a list of name-expression values in JSON (JavaScript Object Notation) format.
4 |
5 | If you wish for hx-headers to evaluate the values given, you can prefix the values with javascript: or js:.
6 |
7 |
Get Some HTML, Including A Custom Header in the Request
8 |
9 | Security Considerations
10 |
11 | By default, the value of hx-headers must be valid 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) vulnerability.
12 |
13 | Notes
14 |
15 | hx-headers is inherited and can be placed on a parent element.
16 | A child declaration of a header overrides a parent declaration.
17 |
18 |
19 | [HTMX Reference](https://htmx.org/attributes/hx-headers/)
20 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-history-elt.md:
--------------------------------------------------------------------------------
1 | The hx-history-elt attribute allows you to specify the element that will be used to snapshot and restore page state during navigation. By default, the body tag is used. This is typically good enough for most setups, but you may want to narrow it down to a child element. Just make sure that the element is always visible in your application, or htmx will not be able to restore history navigation properly.
2 |
3 | Here is an example:
4 |
5 |
6 |
7 |
8 | ...
9 |
10 |
11 |
12 |
13 | Notes
14 |
15 | hx-history-elt is not inherited
16 | In most cases we don’t recommend narrowing the history snapshot
17 |
18 |
19 | [HTMX Reference](https://htmx.org/attributes/hx-history-elt/)
20 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-history.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | History navigation will work as expected, but on restoration the URL will be requested from the server instead of the history cache.
4 |
5 | Here is an example:
6 |
7 |
8 |
9 |
10 | ...
11 |
12 |
13 |
14 |
15 | Notes
16 |
17 | hx-history="false" can be present anywhere in the document to embargo the current page state from the history cache (i.e. even outside the element specified for the history snapshot hx-history-elt).
18 |
19 |
20 | [HTMX Reference](https://htmx.org/attributes/hx-history/)
21 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-include.md:
--------------------------------------------------------------------------------
1 | hx-include
2 |
3 | The hx-include attribute allows you to include additional element values in an AJAX request. The value of this attribute is a CSS query selector of the element or elements to include in the query.
4 |
5 | Here is an example that includes a separate input value:
6 |
7 |
8 |
11 | Enter email:
12 |
13 | 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.
14 |
15 | Note that if you include a non-input element, all input elements enclosed in that element will be included.
16 |
17 | Notes
18 | hx-include is inherited and can be placed on a parent element
19 |
20 | [HTMX Reference](https://htmx.org/attributes/hx-include/)
21 |
22 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-indicator.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | The value of this attribute is a CSS query selector of the element or elements to apply the class to, or the keyword 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);
4 |
5 | Here is an example with a spinner adjacent to the button:
6 |
7 |
8 |
11 |
12 |
13 |
14 | 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:
15 |
16 | .htmx-indicator{
17 | opacity:0;
18 | transition: opacity 500ms ease-in;
19 | }
20 | .htmx-request .htmx-indicator{
21 | opacity:1
22 | }
23 | .htmx-request.htmx-indicator{
24 | opacity:1
25 | }
26 |
27 | 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):
28 |
29 | .my-indicator{
30 | display:none;
31 | }
32 | .htmx-request .my-indicator{
33 | display:inline;
34 | }
35 | .htmx-request.my-indicator{
36 | display:inline;
37 | }
38 |
39 | 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.
40 |
41 | 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:
42 |
43 |
47 |
48 | Notes
49 |
50 | hx-indicator is inherited and can be placed on a parent element
51 | In the absence of an explicit indicator, the htmx-request class will be added to the element triggering the request
52 | 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. The easiest way is to add this the of your HTML:
53 |
54 |
55 |
56 |
57 | [HTMX Reference](https://htmx.org/attributes/hx-indicator/)
58 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-on.md:
--------------------------------------------------------------------------------
1 | The hx-on attribute allows you to embed scripts inline to respond to events directly on an element; similar to the onevent properties found in HTML, such as onClick.
2 |
3 | hx-on improves upon onevent by enabling the handling of any event for enhanced Locality of Behaviour (LoB). This also enables you to handle any htmx event.
4 |
5 | There are two forms of this attribute, one in which you specify the event as part of the attribute name after a colon (hx-on:click, for example), and a deprecated form that uses the hx-on attribute directly. The latter should only be used if IE11 support is required.
6 | hx-on:* (recommended)
7 |
8 | The event name follows a colon : in the attribute, and the attribute value is the script to be executed:
9 |
10 |
Click
11 |
12 | All htmx events can be captured, too! Make sure to use the kebab-case event name, because DOM attributes do not preserve casing. For instance, hx-on::beforeRequest will not work: use hx-on::before-request instead.
13 |
14 | To make writing these a little easier, you can use the shorthand double-colon hx-on:: for htmx events, and omit the “htmx” part:
15 |
16 |
17 |
20 |
21 |
24 |
25 | Adding multiple handlers is easy, you just specify additional attributes:
26 |
27 |
32 |
33 | Symbols
34 |
35 | Like onevent, two symbols are made available to event handler scripts:
36 |
37 | this - The element on which the hx-on attribute is defined
38 | event - The event that triggered the handler
39 |
40 | Notes
41 |
42 | hx-on is not inherited, however due to event bubbling, hx-on attributes on parent elements will typically be triggered by events on child elements
43 | 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.
44 |
45 | [HTMX Reference](https://htmx.org/attributes/hx-on/)
46 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-params.md:
--------------------------------------------------------------------------------
1 | The hx-params attribute allows you to filter the parameters that will be submitted with an AJAX request.
2 |
3 | The possible values of this attribute are:
4 |
5 | * - Include all parameters (default)
6 | none - Include no parameters
7 | not - Include all except the comma separated list of parameter names
8 | - Include all the comma separated list of parameter names
9 |
10 |
Get Some HTML, Including Params
11 |
12 | 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.
13 | Notes
14 |
15 | hx-params is inherited and can be placed on a parent element
16 |
17 |
18 | [HTMX Reference](https://htmx.org/attributes/hx-params/)
19 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-patch.md:
--------------------------------------------------------------------------------
1 | hx-patch
2 |
3 | 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:
4 |
5 |
8 | This example will cause the button to issue a PATCH to /account and swap the returned HTML into the innerHTML of the body.
9 |
10 | Notes
11 | hx-patch is not inherited
12 | You can control the target of the swap using the hx-target attribute
13 | You can control the swap strategy by using the hx-swap attribute
14 | You can control what event triggers the request with the hx-trigger attribute
15 | You can control the data submitted with the request in various ways, documented here: Parameters
16 |
17 | [HTMX Reference](https://htmx.org/attributes/hx-patch/)
18 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-post.md:
--------------------------------------------------------------------------------
1 | hx-post
2 |
3 | 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:
4 |
5 |
8 | This example will cause the button to issue a POST to /account/enable and swap the returned HTML into the innerHTML of the body.
9 |
10 | Notes
11 | hx-post is not inherited
12 | You can control the target of the swap using the hx-target attribute
13 | You can control the swap strategy by using the hx-swap attribute
14 | You can control what event triggers the request with the hx-trigger attribute
15 | You can control the data submitted with the request in various ways, documented here: Parameters
16 |
17 | [HTMX Reference](https://htmx.org/attributes/hx-post/)
18 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-preserve.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | Note that some elements cannot unfortunately be preserved properly, such as (focus and caret position are lost), iframes or certain types of videos. To tackle some of these cases we recommend the morphdom extension, which does a more elaborate DOM reconciliation.
4 | Notes
5 |
6 | hx-preserve is not inherited
7 |
8 |
9 | [HTMX Reference](https://htmx.org/attributes/hx-preserve/)
10 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-prompt.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | Here is an example:
4 |
5 |
8 |
9 | Notes
10 |
11 | hx-prompt is inherited and can be placed on a parent element
12 |
13 |
14 | [HTMX Reference](https://htmx.org/attributes/hx-prompt/)
15 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-push-url.md:
--------------------------------------------------------------------------------
1 | hx-push-url
2 |
3 | The hx-push-url attribute 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. htmx snapshots the current DOM and saves it into its history cache, and restores from this cache on navigation.
4 |
5 | The possible values of this attribute are:
6 |
7 | true, which pushes the fetched URL into history.
8 | false, which disables pushing the fetched URL if it would otherwise be pushed due to inheritance or hx-boost.
9 | A URL to be pushed into the location bar. This may be relative or absolute, as per history.pushState().
10 |
11 | Here is an example:
12 |
13 |
14 | Go to My Account
15 |
16 |
17 | This will cause htmx to snapshot the current DOM to localStorage and push the URL `/account’ into the browser location bar.
18 |
19 | Another example:
20 |
21 |
22 | Go to My Account
23 |
24 |
25 | This will push the URL `/account/home’ into the location history.
26 | Notes
27 |
28 | hx-push-url is inherited and can be placed on a parent element
29 | The HX-Push-Url response header has similar behavior and can override this attribute.
30 | The hx-history-elt attribute allows changing which element is saved in the history cache.
31 |
32 | [HTMX Reference](https://htmx.org/attributes/hx-push-url/)
33 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-put.md:
--------------------------------------------------------------------------------
1 | hx-put
2 |
3 | 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:
4 |
5 |
8 | This example will cause the button to issue a PUT to /account and swap the returned HTML into the innerHTML of the body.
9 |
10 | Notes
11 | hx-put is not inherited
12 | You can control the target of the swap using the hx-target attribute
13 | You can control the swap strategy by using the hx-swap attribute
14 | You can control what event triggers the request with the hx-trigger attribute
15 | You can control the data submitted with the request in various ways, documented here: Parameters
16 |
17 | [HTMX Reference](https://htmx.org/attributes/hx-put/)
18 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-replace-url.md:
--------------------------------------------------------------------------------
1 | The hx-replace-url attribute allows you to replace the current url of the browser location history.
2 |
3 | The possible values of this attribute are:
4 |
5 | true, which replaces the fetched URL in the browser navigation bar.
6 | false, which disables replacing the fetched URL if it would otherwise be replaced due to inheritance.
7 | A URL to be replaced into the location bar. This may be relative or absolute, as per history.replaceState().
8 |
9 | Here is an example:
10 |
11 |
12 | Go to My Account
13 |
14 |
15 | This will cause htmx to snapshot the current DOM to localStorage and replace the URL `/account’ in the browser location bar.
16 |
17 | Another example:
18 |
19 |
20 | Go to My Account
21 |
22 |
23 | This will replace the URL `/account/home’ in the browser location bar.
24 | Notes
25 |
26 | hx-replace-url is inherited and can be placed on a parent element
27 | The HX-Replace-Url response header has similar behavior and can override this attribute.
28 | The hx-history-elt attribute allows changing which element is saved in the history cache.
29 | The hx-push-url attribute is a similar and more commonly used attribute, which creates a new history entry rather than replacing the current one.
30 |
31 |
32 | [HTMX Reference](https://htmx.org/attributes/hx-replace-url/)
33 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-request.md:
--------------------------------------------------------------------------------
1 | The hx-request attribute allows you to configure various aspects of the request via the following attributes:
2 |
3 | timeout - the timeout for the request, in milliseconds
4 | credentials - if the request will send credentials
5 | noHeaders - strips all headers from the request
6 |
7 | These attributes are set using a JSON-like syntax:
8 |
9 |
10 | ...
11 |
12 |
13 | You may make the values dynamically evaluated by adding the javascript: or js: prefix:
14 |
15 |
16 | ...
17 |
18 |
19 | Notes
20 |
21 | hx-request is merge-inherited and can be placed on a parent element
22 |
23 |
24 | [HTMX Reference](https://htmx.org/attributes/hx-request/)
25 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-select-oob.md:
--------------------------------------------------------------------------------
1 | The hx-select-oob attribute allows you to select content from a response to be swapped in via an out-of-band swap.
2 | 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.
3 |
4 | Here is an example that selects a subset of the response content:
5 |
6 |
7 |
8 |
14 |
15 |
16 | 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.
17 |
18 | Each value in the comma separated list of values can specify any valid hx-swap strategy by separating the selector and the swap strategy with a :.
19 |
20 | For example, to prepend the alert content instead of replacing it:
21 |
22 |
23 |
24 |
30 |
31 |
32 | Notes
33 |
34 | hx-select-oob is inherited and can be placed on a parent element
35 |
36 | [HTMX Reference](https://htmx.org/attributes/hx-select-oob/)
37 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-select.md:
--------------------------------------------------------------------------------
1 | hx-select
2 |
3 | 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.
4 |
5 | Here is an example that selects a subset of the response content:
6 |
7 |
8 |
11 |
12 |
13 | 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.
14 | Notes
15 |
16 | hx-select is inherited and can be placed on a parent element
17 |
18 |
19 |
20 | [HTMX Reference](https://htmx.org/attributes/hx-select/)
21 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-swap-oob.md:
--------------------------------------------------------------------------------
1 | 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.
2 |
3 | Consider the following response HTML:
4 |
5 |
6 | ...
7 |
8 |
9 | Saved!
10 |
11 |
12 | 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.
13 |
14 | The value of the hx-swap-oob can be:
15 |
16 | true
17 | any valid hx-swap value
18 | any valid hx-swap value, followed by a colon, followed by a CSS selector
19 |
20 | If the value is true or outerHTML (which are equivalent) the element will be swapped inline.
21 |
22 | If a swap value is given, that swap strategy will be used.
23 |
24 | 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.
25 | Notes
26 |
27 | hx-swap-oob is not inherited
28 | Out of band elements must be in the top level of the response, and not children of the top level elements.
29 |
30 | [HTMX Reference](https://htmx.org/attributes/hx-swap-oob/)
31 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-swap.md:
--------------------------------------------------------------------------------
1 | hx-swap
2 |
3 | The hx-swap attribute allows you to specify how the response will be swapped in relative to the target of an AJAX request.
4 |
5 | The possible values of this attribute are:
6 |
7 | innerHTML - The default, replace the inner html of the target element
8 | outerHTML - Replace the entire target element with the response
9 | beforebegin - Insert the response before the target element
10 | afterbegin - Insert the response before the first child of the target element
11 | beforeend - Insert the response after the last child of the target element
12 | afterend - Insert the response after the target element
13 | delete - Deletes the target element regardless of the response
14 | none- Does not append content from response (out of band items will still be processed).
15 | These options are based on standard DOM naming and the Element.insertAdjacentHTML specification.
16 |
17 | So in this code:
18 |
19 |
Get Some HTML & Append It
20 | The div will issue a request to /example and append the returned content after the div
21 |
22 | Modifiers
23 | The hx-swap attributes supports modifiers for changing the behavior of the swap. They are outlined below.
24 |
25 | Transition: transition
26 | If you want to use the new View Transitions 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.
27 |
28 | Timing: swap & settle
29 | You can modify the amount of time that htmx will wait after receiving a response to swap the content by including a swap modifier:
30 |
31 |
32 |
Get Some HTML & Append It
33 | Similarly, you can modify the time between the swap and the settle logic by including a settle modifier:
34 |
35 |
36 |
Get Some HTML & Append It
37 | These attributes can be used to synchronize htmx with the timing of CSS transition effects.
38 |
39 | Scrolling: scroll & show
40 | 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:
41 |
42 |
43 |
46 | Get Some HTML & Append It & Scroll To Bottom
47 |
48 |
50 |
53 | Get Some Content
54 |
55 | 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:
56 |
57 |
59 |
61 | Get Some Content
62 |
63 | You may also use window:top and window:bottom to scroll to the top and bottom of the current window.
64 |
65 |
67 |
69 | Get Some Content
70 |
71 | Focus scroll
72 | 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.
73 |
74 |
76 | 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.
77 |
78 |
80 | Notes
81 | hx-swap is inherited and can be placed on a parent element
82 | The default value of this attribute is innerHTML
83 | Due to DOM limitations, it’s not possible to use the outerHTML method on the element. htmx will change outerHTML on to use innerHTML.
84 | The default swap delay is 0ms
85 | The default settle delay is 20ms
86 |
87 | [HTMX Reference](https://htmx.org/attributes/hx-swap/)
88 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-sync.md:
--------------------------------------------------------------------------------
1 | The hx-sync attribute allows you to synchronize AJAX requests between multiple elements.
2 |
3 | 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:
4 |
5 | drop - drop (ignore) this request if an existing request is in flight (the default)
6 | 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
7 | replace - abort the current request, if any, and replace it with this request
8 | queue - place this request in the request queue associated with the given element
9 |
10 | The queue modifier can take an additional argument indicating exactly how to queue:
11 |
12 | queue first - queue the first request to show up while a request is in flight
13 | queue last - queue the last request to show up while a request is in flight
14 | queue all - queue all requests that show up while a request is in flight
15 |
16 | Notes
17 |
18 | hx-sync is inherited and can be placed on a parent element
19 |
20 | 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.
21 |
22 |
29 |
30 | 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.
31 |
32 |
40 |
41 | 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.
42 |
43 |
47 |
48 | 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.
49 |
50 |
55 |
56 |
57 | [HTMX Reference](https://htmx.org/attributes/hx-sync/)
58 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-target.md:
--------------------------------------------------------------------------------
1 | hx-target
2 |
3 | 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:
4 |
5 | A CSS query selector of the element to target.
6 | this which indicates that the element that the hx-target attribute is on is the target.
7 | closest which will find the closest ancestor element or itself, that matches the given CSS selector (e.g. closest tr will target the closest table row to the element).
8 | find which will find the first child descendant element that matches the given CSS selector.
9 | next 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)
10 | previous 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)
11 | Here is an example that targets a div:
12 |
13 |
14 |
15 |
18 |
19 | The response from the /register url will be appended to the div with the id response-div.
20 |
21 | This example uses hx-target="this" to make a link that updates itself when clicked:
22 |
23 | New link
24 | Notes
25 | hx-target is inherited and can be placed on a parent element
26 |
27 | [HTMX Reference](https://htmx.org/attributes/hx-target/)
28 |
--------------------------------------------------------------------------------
/lsp/src/htmx/attributes/hx-trigger.md:
--------------------------------------------------------------------------------
1 | hx-trigger
2 |
3 | The hx-trigger attribute allows you to specify what triggers an AJAX request. A trigger value can be one of the following:
4 |
5 | An event name (e.g. “click” or “my-custom-event”) followed by an event filter and a set of event modifiers
6 | A polling definition of the form every
7 | A comma-separated list of such events
8 | Standard Events
9 | A standard event, such as click can be specified as the trigger like so:
10 |
11 |
Click Me
12 | Standard Event Filters
13 | 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.
14 |
15 |
Control Click Me
16 | This event will trigger if a click event is triggered with the event.ctrlKey property set to true.
17 |
18 | Conditions can also refer to global functions or state
19 |
20 |
Control Click Me
21 | And can also be combined using the standard javascript syntax
22 |
23 |
Control-Shift Click Me
24 | 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
25 |
26 | Standard Event Modifiers
27 | Standard events can also have modifiers that change how they behave. The modifiers are:
28 |
29 | once - the event will only trigger once (e.g. the first click)
30 | changed - the event will only change 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.
31 | delay: - a delay will occur before an event triggers a request. If the event is seen again it will reset the delay.
32 | throttle: - 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.
33 | from: - 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)
34 | A standard CSS selector resolves to all elements matching that selector. Thus, from:input would listen on every input on the page.
35 | The extended CSS selector here allows for the following non-standard CSS values:
36 | document - listen for events on the document
37 | window - listen for events on the window
38 | closest - finds the closest ancestor element or itself, matching the given css selector
39 | find - finds the closest child matching the given css selector
40 | target: - 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
41 | consume - if this option is included the event will not trigger any other htmx requests on parents (or on elements listening on parents)
42 | queue: - determines how events are queued if an event occurs while a request for another event is in flight. Options are:
43 | first - queue the first event
44 | last - queue the last event (default)
45 | all - queue all events (issue a request for each event)
46 | none - do not queue new events
47 | Here is an example of a search box that searches on keyup, but only if the search value has changed and the user hasn’t typed anything new for 1 second:
48 |
49 |
52 | The response from the /search url will be appended to the div with the id search-results.
53 |
54 | Non-standard Events
55 | There are some additional non-standard events that htmx supports:
56 |
57 | load - triggered on load (useful for lazy-loading something)
58 | 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.
59 | intersect - fires once when an element first intersects the viewport. This supports two additional options:
60 | root: - a CSS selector of the root element for intersection
61 | threshold: - a floating point number between 0.0 and 1.0, indicating what amount of intersection to fire the event on
62 | Triggering via the HX-Trigger header
63 | If you’re trying to fire an event from HX-Trigger response header, you will likely want to use the from:body modifier. E.g. if you send a header like this HX-Trigger: my-custom-event with a response, an element would likely need to look like this:
64 |
65 |
3 | 
4 | 
6 | 
7 | 
12 |