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:

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

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.

Intercooler	htmx
`ic-action`	None. Use Hyperscript, e.g. `<button _="on click add .clicked">Add The "clicked" Class To Me</button>`. See the htmx documentation on hyperscript and hyperscript documentationfor more examples
`ic-action-target`	None. Use the Hyperscript target expression, e.g. `<div _="on click set .button.style.color to 'red'">Set All Buttons To Red</div>`
`ic-add-class`	None. Use Hyperscript, e.g. `<button _="on click add .clicked">Add The "clicked" Class To Me</button>`. See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-append-from`	None. Equivalent functionality can be achived by using for example `hx-get` and `hx-swap` with value `beforeend`
`ic-attr-src`	None. No direct equivalent functionality exists (TBC)
`ic-confirm`	`hx-confirm`
`ic-delete-from`	`hx-delete`
`ic-deps`	`hx-trigger="path-deps"` along with `path-deps="/foo/bar"`. (Requires the `path-deps` extension)
`ic-disable-when-doc-hidden`	None. No direct equivalent functionality exists (TBC)
`ic-disable-when-doc-inactive`	None. No direct equivalent functionality exists (TBC)
`ic-enhance`	`hx-boost`
`ic-fix-ids`	None. No direct equivalent functionality exists (TBC)
`ic-get-from`	`hx-get`
`ic-global-include`	None. `hx-include` can be used to achieve similar functionality
`ic-global-indicator`	None. `hx-indicator` can be used to achieve similar functionality
`ic-history-elt`	`hx-history-elt`
`ic-include`	`hx-include`
`ic-indicator`	`hx-indicator`
`ic-limit-children`	None. No direct equivalent functionality exists (TBC)
`ic-local-vars`	No direct equivalent. `hx-vars` could be used to facilitate.
`ic-on-beforeSend`	None. Use Hyperscript in conjunction with events (e.g. `htmx:beforeRequest`). See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-on-beforeTrigger`	None. Use Hyperscript in conjunction with events (e.g. `htmx:beforeRequest`). See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-on-complete`	None. Use Hyperscript in conjunction with events (e.g. `https://htmx.org/events#htmx:afterRequest`). See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-on-error`	None. Use Hyperscript in conjunction with events (e.g. `https://htmx.org/events#htmx:afterRequest`). See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-on-success`	None. Use Hyperscript in conjunction with events (e.g. `https://htmx.org/events#htmx:afterRequest`). See the htmx documentation on hyperscript and hyperscript documentation for more examples
`ic-patch-to`	`hx-patch`
`ic-pause-polling`	None. Techniques like `load polling` could be used
`ic-poll`	None. The equivalent can be achieved by triggering a load on schedule, e.g. `<div hx-get="/news" hx-trigger="every 2s"></div>`. See the documentation on polling
`ic-poll-repeats`	None. The equivalent can be achieved by triggering a load on schedule, e.g. `<div hx-get="/news" hx-trigger="every 2s"></div>`. See the documentation on polling
`ic-post-errors-to`	None. Errors can be trapped via events and logged via the `htmx.logger` mechanism
`ic-post-to`	`hx-post`
`ic-prepend-from`	The `hx-swap` attribute with value set to `beforeend` could be used to achieve the same outcome
`ic-prompt`	`hx-prompt`
`ic-push-url`	`hx-push-url`
`ic-push-params`	Parameters are automatically pushed in the case of a `GET` in htmx
`ic-put-to`	`hx-put`
`ic-remove-after`	None. See the htmx documentation on hyperscript for an example on how to implement it using hyperscript
`ic-remove-class`	None. Use Hyperscript, e.g. `<button class="red" _="on click remove .red">Remove The "red" class from me</button>`. See the htmx documentation on hyperscript and hyperscript documentationfor more examples
`ic-replace-target`	The `hx-swap` attribute with value set to `outerHTML` could be used to achieve the same outcome
`ic-scroll-offset`	None. No direct equivalent functionality exists
`ic-scroll-to-target`	See the `scroll` and `show` modifiers on the `hx-swap` attribute
`ic-select-from-response`	`hx-select`
`ic-src`	None. Use 'hx-get' in conjunction with triggers or the `path-deps` extension
`ic-sse-src`	`hx-sse`
`ic-style-src`	None. No direct equivalent functionality exists (TBC)
`ic-swap-style`	`hx-swap`
`ic-switch-class`	None. See the htmx documentation on _hyperscript for an example on how to implement it using _hyperscript and the `htmx:beforeOnLoad` event
`ic-target`	`hx-target`
`ic-transform-response`	None. The `client-side-templates` extension enablesJSON response transformation via templating engines like mustache, handlebars or nunjucks
`ic-transition-duration`	None. Equivalent functionality can be achieved by relying on the nature of htmx's swapping mechanism and CSS transitions
`ic-trigger-delay`	Use `hx-trigger` with modifiers
`ic-trigger-from`	Use `hx-trigger` with `from:` clause
`ic-trigger-on`	`hx-trigger`
`ic-verb`	None. By default htmx sends the actual http method. You can however non-`GET` verbs to `POST` via the `method-override` extension

Request parameters

Intercooler	htmx
`ic-request`	None. Use `HX-Request` header
`_method`	_method (requires the `rails-method` extension)
`ic-element-id`	None
`ic-element-name`	None
`ic-target-id`	None. Use `HX-Target` header
`ic-trigger-id`	None. Use `HX-Trigger` header
`ic-trigger-name`	None. Use `HX-Trigger-Name` header
`ic-current-url`	None. Use the `HX-Current-URL` header
`ic-prompt-value`	None. Use the `HX-Prompt` header

Request headers

Intercooler	htmx
`X-IC-Request`	`HX-Request`
`X-HTTP-Method-Override`	`X-HTTP-Method-Override`

Response headers

Intercooler	htmx
`X-IC-Trigger`	`HX-Trigger`, `HX-Trigger-After-Settle`, `HX-Trigger-After-Swap`. See documentation for more details
`X-IC-Refresh`	`HX-Refresh`
`X-IC-Redirect`	`HX-Redirect`
`X-IC-Script`	None. No direct equivalent functionality exists (TBC)
`X-IC-CancelPolling`	None. Respond with HTTP response code `286` to cancel polling.
`X-IC-ResumePolling`	None. No direct equivalent functionality exists
`X-IC-SetPollInterval`	None. If using load polling, respond with content that contains a different load interval.
`X-IC-Open`	None. No direct equivalent functionality exists (TBC)
`X-IC-PushURL`	`HX-Push`
`X-IC-Remove`	None. No direct equivalent functionality exists (TBC)
`X-IC-Title`	None. No direct equivalent functionality exists (TBC)
`X-IC-Title-Encoded`	None. No direct equivalent functionality exists (TBC)
`X-IC-Set-Local-Vars`	None. No direct equivalent functionality exists (TBC)

Events

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

Intercooler	htmx
`log.ic`	None. Equivalent achieved via `htmx.logger`. See `Events & Logging` documentation
`beforeAjaxSend.ic`	`htmx:configRequest`
`beforeHeaders.ic`	None. No direct equivalent functionality exists (TBC)
`afterHeaders.ic`	None. No direct equivalent functionality exists (TBC)
`beforeSend.ic`	`htmx:beforeRequest`
`success.ic`	`htmx:afterOnLoad`
`after.success.ic`	Approximate equivalent: `htmx:beforeSwap`
`error.ic`	`htmx:sendError` or `htmx:sseError` or `htmx:responseError` or `htmx:swapError` or `htmx:onLoadError` (TBC)
`complete.ic`	`htmx:afterRequest`
`onPoll.ic`	No direct equivalent. When using load polling, the [`htmx:load` event] could potentially be used
`handle.onpopstate.ic`	`htmx:historyRestore` (TBC)
`elementAdded.ic`	`htmx:load`
`pushUrl.ic`	tbd
`beforeHistorySnapshot.ic`	`htmx:beforeHistorySave`

Javascript API methods

Intercooler	htmx
`Intercooler.refresh(eltOrPath)`	`PathDeps.refresh()` (requires the `path-deps` extension)
`Intercooler.triggerRequest(elt, handler)`	`htmx.trigger()`
`Intercooler.processNodes(elt)`	`htmx.process()`
`Intercooler.closestAttrValue(elt, attr)`	`htmx.closest()` can be used with any selector
`Intercooler.verbFor(elt)`	None. No direct equivalent functionality exists (TBC)
`Intercooler.isDependent(elt1, elt2)`	None. No direct equivalent functionality exists (TBC)
`Intercooler.getTarget(elt1)`	None. No direct equivalent functionality exists (TBC)
`Intercooler.processHeaders(elt, xhr)`	None. No direct equivalent functionality exists (TBC)
`Intercooler.ready(func(elt))`	`htmx.onLoad()`
`LeadDyno.startPolling(elt)`	None. No direct equivalent functionality exists (TBC)
`LeadDyno.stopPolling(elt)`	None. No direct equivalent functionality exists (TBC)

Meta tags

Intercooler	htmx
`<meta name="intercoolerjs:use-data-prefix" content="true"/>`	None. You can simply use the `data-` prefix without specifying a meta tag. htmx will automatically recognize htmx attributes like this: `<a data-hx-post="/click">Click Me!</a>`
`<meta name="intercoolerjs:use-actual-http-method" content="true"/>`	None. By default htmx sends the actual http method. You can however change the verb for all non-GET requests to POST via the `method-override` extension