Building htmx Extensions

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

Migrating from htmx 2.x

If you’re migrating an extension from htmx 2.x, here’s a quick reference:

For detailed migration examples, see the Extension Migration Guide.

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
    },
});

Loading Extensions

Extensions are loaded by including the script file. They apply page-wide automatically.

To restrict which extensions can register, use the extensions config as a whitelist:

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

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

View Transition Events

Other 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) => {
        // Use internal API
        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") {
            // Implement custom swap logic
            target.appendChild(fragment);
            return true; // Handled
        }
        return false; // Not handled
    },
});

Complete Example

(() => {
    let api;

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

        htmx_after_init: (elt) => {
            let preloadSpec = api.attributeValue(elt, "hx-preload");
            if (!preloadSpec) return;

            let specs = api.parseTriggerSpecs(preloadSpec);
            let eventName = specs[0].name;

            elt.addEventListener(eventName, async (evt) => {
                let ctx = api.createRequestContext(elt, evt);
                // Prefetch logic here
            });
        },

        htmx_before_request: (elt, detail) => {
            // Use prefetched response if available
            if (elt._htmx?.preload) {
                detail.ctx.fetch = () => elt._htmx.preload;
                delete elt._htmx.preload;
            }
        },

        htmx_before_cleanup: (elt) => {
            // Clean up listeners
            if (elt._htmx?.preloadListener) {
                elt.removeEventListener(
                    elt._htmx.preloadEvent,
                    elt._htmx.preloadListener,
                );
            }
        },
    });
})();

Migration from htmx 2.x

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

Old API (htmx 2.x):

htmx.defineExtension("old", {  // Note: htmx 2.x used defineExtension with different format
    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