Skip to content

Commit

Permalink
Merge branch 'ext-npm-doc'
Browse files Browse the repository at this point in the history
  • Loading branch information
@marisst
marisst committed Jan 12, 2025
2 parents aeeb216 + d6573ef commit 8e8e187
Show file tree
Hide file tree
Showing 8 changed files with 225 additions and 42 deletions.
69 changes: 49 additions & 20 deletions www/content/docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]/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
Expand All @@ -1153,6 +1134,54 @@ 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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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 `htx-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`.

### 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).
Expand Down
29 changes: 26 additions & 3 deletions www/content/extensions/head-support.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]/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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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 `htx-ext-head-support` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-head-support`;
```

## Usage
Expand Down
28 changes: 25 additions & 3 deletions www/content/extensions/htmx-1-compat.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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.

```html
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.

<script src="https://unpkg.com/[email protected]/htmx-1-compat.js"></script>
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 `htx-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
Expand Down
28 changes: 25 additions & 3 deletions www/content/extensions/idiomorph.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]/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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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
Expand Down
30 changes: 26 additions & 4 deletions www/content/extensions/preload.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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.

```html
<script src="https://unpkg.com/[email protected]/preload.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 `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 `htx-ext-preload` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-preload`;
```

## Usage
Expand All @@ -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>
Expand Down
29 changes: 26 additions & 3 deletions www/content/extensions/response-targets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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.

```html
<script src="https://unpkg.com/[email protected]/response-targets.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 `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 `htx-ext-response-targets` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-response-targets`;
```

## Configure (optional)
Expand Down
27 changes: 24 additions & 3 deletions www/content/extensions/sse.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

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/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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.

```html
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.

<script src="https://unpkg.com/[email protected]/sse.js"></script>
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 `htx-ext-sse` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-sse`;
```

## Usage
Expand Down
27 changes: 24 additions & 3 deletions www/content/extensions/ws.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,32 @@ Use the following attributes to configure how WebSockets behave:
event
or the event specified by [`hx-trigger`])

## Install
## Installing

The fastest way to install `ws` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage).
```HTML
<head>
<script src="https://unpkg.com/[email protected]" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]" 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.

```html
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.

<script src="https://unpkg.com/[email protected]/ws.js"></script>
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 `htx-ext-ws` via npm
- Import both packages to your `index.js`
```JS
import `htmx.org`;
import `htmx-ext-ws`;
```

## Usage
Expand Down

0 comments on commit 8e8e187

Please sign in to comment.