htmx/www/extensions.md

layout	title
layout.njk	</> htmx - high power tools for html

htmx Extensions

Htmx has an extension mechanism for defining and using extensions to the default behavior in a simple and obvious manner.

There is a registry of officially supported (i.e. tested) extensions here.

Defining an Extensions

To define an extension you need to call the htmx.defineExtension() function:

<script>
  htmx.defineExtension('my-ext', {
    onEvent : function(name, evt) {
        console.log("Fired event: " + name, evt);
    }
  })
</script>

Extensions should have names that are dash separated like above and that are reasonably short and descriptive.

Extensions can override the following default extension fields:

{
    onEvent : function(name, evt) {return true;},
    transformResponse : function(text, xhr, elt) {return text;},
    handleSwap : function(swapStyle, target, fragment) {return false;},
    encodeParameters : function(xhr, parameters, elt) {return null;}
}

Using An Extension

To use an extension you use the hx-ext attribute. To use our extension defined above you would say:

  <button hx-post="/example" hx-ext="my-ext">This Button Uses My Extension</button>

Note that the hx-ext tag may be placed on parent elements if you want a plugin to apply to an entire swath of the dom, and on the body tag for it to apply to all htmx requests.

Extensions Reference

The following extensions that are tested and distributed with htmx:

Extension	Description
json-enc	use JSON encoding in the body of requests, rather than the default x-www-form-urlencoded
morphdom-swap	an extension for using the morphdom library as the swapping mechanism in htmx.
client-side-templates	support for client side template processing of JSON responses
debug	an extension for debugging of a particular element using htmx
path-deps	an extension for expressing path-based dependencies similar to intercoolerjs
class-tools	an extension for manipulating timed addition and removal of classes on HTML elements