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.

Using Extensions

To use an extension you use the hx-ext attribute:

  <button hx-post="/example" hx-ext="debug">This Button Uses The Debug 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.

Tip: To use multiple extensions on one element, separate them with a comma:

  <button hx-post="/example" hx-ext="debug, json-enc">This Button Uses Two Extensions</button>

Included Extensions

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
method-override	use the X-HTTP-Method-Override header for non-GET and POST requests
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
remove-me	allows you to remove an element after a given amount of time
include-vals	allows you to include additional values in a request

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;},
    isInlineSwap : function(swapStyle) {return false;},
    handleSwap : function(swapStyle, target, fragment, settleInfo) {return false;},
    encodeParameters : function(xhr, parameters, elt) {return null;}
}