Using Extensions

htmx supports extensions to augment its core hypermedia infrastructure. The extension mechanism takes pressure off the core library to add new features, allowing it to focus on its main purpose of generalizing hypermedia controls.

Using Extensions

In htmx 4, extensions hook into standard events rather than callback extension points. They are lightweight with no performance penalty.

Extensions apply page-wide without requiring hx-ext on parent elements. They activate via custom attributes where needed.

Loading an Extension

Include the extension script after htmx:

<script src="/path/to/htmx.js"></script>
<script src="/path/to/ext/hx-sse.js"></script>

Or with a bundler:

import 'htmx.org';
import 'htmx.org/dist/ext/hx-sse';

Restricting Extensions

To restrict which extensions can register, use an allow list:

<meta name="htmx-config" content='{"extensions": "my-ext,another-ext"}'>

When this config is set, only the listed extensions will be loaded. Without it, all registered extensions are active.

Core Extensions

htmx supports a set of core extensions, maintained by the htmx development team and shipped with htmx:

Building Extensions

htmx 4 introduces an extension system based on event hooks rather than the old callback-based API.

Defining an Extension

Extensions are defined using htmx.registerExtension():

htmx.registerExtension("my-ext", {
    init: (internalAPI) => {
        // Called once when extension is registered
        // Store internalAPI reference if needed
    },

    htmx_before_request: (elt, detail) => {
        // Called before each request
        // Return false to cancel
    },

    htmx_after_request: (elt, detail) => {
        // Called after each request
    },
});

Event Hooks

Extensions hook into htmx lifecycle events. Event names use underscores instead of colons:

Core Lifecycle Events

Request Lifecycle Events

Swap Events

History Events

Cancelling Events

Return false or set detail.cancelled = true to cancel an event:

htmx.registerExtension("validator", {
    htmx_before_request: (elt, detail) => {
        if (!isValid(detail.ctx)) {
            return false; // Cancel request
        }
    },
});

Internal API

The init hook receives an internal API object with helper methods:

let api;

htmx.registerExtension("my-ext", {
    init: (internalAPI) => {
        api = internalAPI;
    },

    htmx_after_init: (elt) => {
        let value = api.attributeValue(elt, "hx-my-attr");
        let specs = api.parseTriggerSpecs("click, keyup delay:500ms");
        let { method, action } = api.determineMethodAndAction(elt, evt);
    },
});

Available internal API methods:

• attributeValue(elt, name, defaultVal, returnElt) - Get htmx attribute value with inheritance
• parseTriggerSpecs(spec) - Parse trigger specification string
• determineMethodAndAction(elt, evt) - Get HTTP method and URL
• createRequestContext(elt, evt) - Create request context object
• collectFormData(elt, form, submitter) - Collect form data
• handleHxVals(elt, body) - Process hx-vals attribute

Request Context

The detail.ctx object contains request information:

{
    sourceElement,      // Element triggering request
    sourceEvent,        // Event that triggered request
    status,            // Request status
    target,            // Target element for swap
    swap,              // Swap strategy
    request: {
        action,        // Request URL
        method,        // HTTP method
        headers,       // Request headers
        body,          // Request body (FormData)
        validate,      // Whether to validate
        abort,         // Function to abort request
        signal         // AbortSignal
    },
    response: {        // Available after request
        raw,           // Raw Response object
        status,        // HTTP status code
        headers        // Response headers
    },
    text,              // Response text (after request)
    hx                 // HX-* response headers (parsed)
}

Custom Swap Strategies

Extensions can implement custom swap strategies:

htmx.registerExtension("my-swap", {
    handle_swap: (swapStyle, target, fragment, swapSpec) => {
        if (swapStyle === "my-custom-swap") {
            target.appendChild(fragment);
            return true; // Handled
        }
        return false; // Not handled
    },
});

Migrating from htmx 2.x

The htmx 4 extension API is completely different from htmx 2.x:

Old API (htmx 2.x):

htmx.defineExtension("old", {
    onEvent: function (name, evt) {},
    transformResponse: function (text, xhr, elt) {},
    handleSwap: function (swapStyle, target, fragment, settleInfo) {},
});

New API (htmx 4):

htmx.registerExtension("new", {
    htmx_before_request: (elt, detail) => {},
    htmx_after_request: (elt, detail) => {},
    handle_swap: (swapStyle, target, fragment, swapSpec) => {},
});

Key differences:

• Event-based hooks instead of method callbacks
• Underscores in hook names (not colons)
• Extensions load by including the script (config whitelist is optional)
• Access to full request context via detail.ctx
• Internal API provided via init hook