htmx/htmx-1-compat.md at 90a91a60e0fcd2d7c42e04c615177cba89c33151

mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-28 05:21:18 +00:00

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

* 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

2025-02-14 22:37:21 +01:00

3.4 KiB

Raw Blame History

+++ title = "htmx 1.x Compatibility Extension" +++

The htmx-1-compat extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2.

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.

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

While the CDN approach is simple, you may want to consider not using CDNs in production. 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:

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

import `htmx.org`;
import `htmx-ext-htmx-1-compat`;

What it covers

Htmx 2 introduced a few breaking changes.

To make upgrading from htmx 1.x to htmx 2 easier, we're providing this extension that reverts most of those, so you're able to benefit from the other changes without breaking your application.

Obsolete attributes

htmx 2 removed the deprecated hx-ws and hx-sse attributes, that this extension restores.
htmx 2 removed the deprecated hx-on attribute in favor of the wildcard hx-on* attribute, that this extension restores.

Default Changes

reverts htmx.config.scrollBehavior to 'smooth'.
makes DELETE requests use a form-encoded body rather than URL parameters (htmx 2 uses URL parameters for DELETE as default as per the spec).
allows cross-domain requests by default (htmx 2 now forbids it by default).

What it does not cover

IE11 support was dropped in htmx 2, and this extension cannot revert that. If you need IE11 support, please stay with htmx 1 that will continue being supported.
htmx 2 introduced the breaking change that is the swap method to the extensions API. If you were only using core extensions, then you shouldn't need any additional work. If you were using custom or community extensions, make sure that they were updated to work with htmx 2's API.

3.4 KiB Raw Blame History