itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-27 04:50:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Extension docs: npm, bundler, min/unmin and SRI hash instructions (#3127)

Browse Source 
* Extensions docs: add npm/bundler installation guide and up versions numbers for links

* Revert extensions._index.md table change

* Update docs.md extension installation and integration instruction

* Move extension installation and enabling to new sections in docs.md

* Update extension installation guidelines

* Update idiomorph installation guidelines

* Minor consistency edits

* Make the need for hx-ext clearer

* Fix typos and note for community repos not hosted outside this repo
This commit is contained in:
Mariss Tubelis 2025-02-14 22:37:21 +01:00 committed by GitHub
parent 0f9c4202ba
commit 90a91a60e0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 227 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
www/content/docs.md
View File

@ -1120,30 +1120,11 @@ htmx provides an [extensions](/extensions) mechanism that allows you to customiz
Extensions [are defined in javascript](/extensions/building) and then enabled via
the [`hx-ext`](@/attributes/hx-ext.md) attribute.
Here is how you would install the [idiomorph](/extensions/idiomorph) extension, which allows you to use the
[Idiomorph](https://github.com/bigskysoftware/idiomorph) DOM morphing algorithms for htmx swaps:
```html
<head>
<script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
</head>
<body hx-ext="morph">
...
<button hx-post="/example" hx-swap="morph" hx-target="#content">
Update Content
</button>
...
</body>
```
First the extension is included (it should be included *after* `htmx.js` is included), then the extension is referenced
by name via the `hx-ext` attribute. This enables you to then use the `morph` swap.
### 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 |
* [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
@ -1153,6 +1134,56 @@ htmx supports a few "core" extensions, which are supported by the htmx developme
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="extension-name">
...
```
An unminified version is also available at `https://unpkg.com/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://unpkg.com/htmx-ext-extension-name` (replace `extension-name` with the name of the extension) e.g., https://unpkg.com/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://unpkg.com/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).

29
www/content/extensions/head-support.md
View File

@ -13,10 +13,33 @@ The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this w
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.
## Install
## Installing
```html
<script src="https://unpkg.com/htmx-ext-head-support@2.0.1/head-support.js"></script>
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script>
</head>
<body hx-ext="head-support">
...
```
An unminified version is also available at https://unpkg.com/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://unpkg.com/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

28
www/content/extensions/htmx-1-compat.md
View File

@ -4,11 +4,33 @@ title = "htmx 1.x Compatibility Extension"
The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2.
## Install
## Installing
```html
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="htmx-1-compat">
...
```
An unminified version is also available at https://unpkg.com/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js.
<script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0/htmx-1-compat.js"></script>
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://unpkg.com/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

28
www/content/extensions/idiomorph.md
View File

@ -10,10 +10,32 @@ 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.
## Install
## Installing
```html
<script src="https://unpkg.com/idiomorph@0.3.0/dist/idiomorph-ext.min.js"></script>
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/idiomorph@0.3.0" integrity="sha384-tg/2Ca9U/RohyxmGCb8qJVR3j9cswtKbdRSXOaPX/aDDOW1bfbeyV+7G9ifYF4bC" crossorigin="anonymous"></script>
</head>
<body hx-ext="morph">
```
An unminified version is also available at https://unpkg.com/idiomorph/dist/idiomorph.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 the extension from `https://unpkg.com/idiomorph`, 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 `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.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 `idiomorph` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `idiomorph`;
```
## Usage

30
www/content/extensions/preload.md
View File

@ -10,10 +10,33 @@ behavior to fit your applications needs and use cases.
too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many
unused requests. Use this extension carefully!
## Install
## Installing
```html
<script src="https://unpkg.com/htmx-ext-preload@2.1.0/preload.js"></script>
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-preload@2.1.0" integrity="sha384-fkzubQiTB69M7XTToqW6tplvxAOJkqPl5JmLAbumV2EacmuJb8xEP9KnJafk/rg8" crossorigin="anonymous"></script>
</head>
<body hx-ext="preload">
...
```
An unminified version is also available at https://unpkg.com/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://unpkg.com/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
@ -23,7 +46,6 @@ and `hx-get` elements you want to preload. By default, resources will be loaded
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>

29
www/content/extensions/response-targets.md
View File

@ -22,10 +22,33 @@ The value of each attribute can be:
* `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)
## Install
## Installing
```html
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.0/response-targets.js"></script>
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script>
</head>
<body hx-ext="response-targets">
...
```
An unminified version is also available at https://unpkg.com/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://unpkg.com/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)

27
www/content/extensions/sse.md
View File

@ -24,11 +24,32 @@ Use the following attributes to configure how SSE connections behave:
* `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.
## Install
## Installing
```html
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-sse@2.2.2" integrity="sha384-Y4gc0CK6Kg+hmulDc6rZPJu0tqvk7EWlih0Oh+2OkAi1ZDlCbBDCQEE2uVk472Ky" crossorigin="anonymous"></script>
</head>
<body hx-ext="sse">
```
An unminified version is also available at https://unpkg.com/htmx-ext-sse/dist/sse.js.
<script src="https://unpkg.com/htmx-ext-sse@2.2.2/sse.js"></script>
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://unpkg.com/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

27
www/content/extensions/ws.md
View File

@ -18,11 +18,32 @@ Use the following attributes to configure how WebSockets behave:
event
or the event specified by [`hx-trigger`])
## Install
## Installing
```html
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://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/htmx-ext-ws@2.0.2" integrity="sha384-vuKxTKv5TX/b3lLzDKP2U363sOAoRo5wSvzzc3LJsbaQRSBSS+3rKKHcOx5J8doU" crossorigin="anonymous"></script>
</head>
<body hx-ext="ws">
```
An unminified version is also available at https://unpkg.com/htmx-ext-ws/dist/ws.js.
<script src="https://unpkg.com/htmx-ext-ws@2.0.1/ws.js"></script>
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://unpkg.com/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