intercooler.js → htmx Migration Guide

The purpose of this guide is to:

• map the equivalent htmx attributes, headers, events, methods, etc. that are available in Intercooler
• provide workarounds to achieve the same/similar outcome in the cases where there is no direct equivalent in htmx core (usually via an htmx extension or via hyperscript)
• highlight gaps which can’t (yet) be elegantly solved via core htmx, any of the existing extensions or hyperscript

🔗Before you begin

It is worth noting the difference in approach between what Intercooler set out to do and what htmx is doing.

Intercooler tried to provide custom html attributes for most of it’s functionality. This is evident in it’s longer list of attributes, many of which could be described as convenience or client-side-focused in nature.

htmx follows the approach of trying to keep the core small, with a smaller set of available attributes that are mostly focused on content loading and swapping.

This capability is augmented in primarily 2 ways:

1. Extensions. The htmx extension framework allows for custom extensions/plugins to achieve specific functionality. An example of this is the dependencies mechanism baked into Intercooler, which is not present in htmx core. but available via an extension. There are also other extensions which enables new behavior that Intercooler was not capable of out the box, e.g. the preload extension

2. Using the htmx events system with vanilla javascript, alpine.js or hyperscript. Hyperscript is a small, open scripting language designed to be embedded in HTML, inspired by HyperTalk and is a companion project of htmx.

htmx also contains functionality which is not present in Intercooler. That is outside of the scope of this guide.

Finally, it’s worth noting that this is still a work in progress and is liable to change over time.

🔗Migration Information

The rest of this guide is laid out as a set of tables, each of which attempts to map the following common functional areas of Intercooler onto the htmx equivalents:

• Attributes
• Request Parameters
• Request Headers
• Response Headers
• Events
• Javascript API Methods
• Meta Tags

🔗Attributes

Note: For certain Intercooler attributes (mostly client-side specific attributes, e.g. the ic-action and associated attributes) there are no direct htmx equivalents. Instead, there is a small, expressive language available called hyperscript, (see http://hyperscript.org), which is designed to be embedded in HTML and acts as a seamless companion to htmx. It allows you to achieve the same behavior as some of especially the client-side focused Intercooler attributes, but in a more flexible and open manner.

See the htmx documentation on hyperscript for practical examples, as well as more on the philosophy behind hyperscipt.

🔗Request parameters

🔗Request headers

🔗Response headers

🔗Events

Note: All htmx events are fired in both Camel and Kebab casing.

🔗JavaScript API methods

🔗Meta tags