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

Extension Approval

Extensions can be approved via the extensions config option in a meta tag:

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

If this is set then only approved extensions will be loaded. This prevents unauthorized extensions from running. By default without this config set in a meta tag all extensions will be approved.

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

SSE 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", {
    htmx_handle_swap: (target, detail) => {
        let { swapSpec, fragment } = detail;
        if (swapSpec.style === "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) => {},
    htmx_handle_swap: (elt, detail) => {},
});

Key differences:

• Event-based hooks instead of method callbacks
• Underscores in hook names (not colons)
• Extensions must be approved via config
• Access to full request context via detail.ctx
• Internal API provided via init hook