htmx Events Guide

Listening For Events

There are three ways to listen for an htmx event.

Use htmx.on(), which listens on document by default:

htmx.on('htmx:after:swap', function (evt) {
    console.log('swapped', evt.detail.ctx.target);
});

Use the standard addEventListener:

document.body.addEventListener('htmx:after:init', function (evt) {
    setUpElement(evt.detail.elt);
});

Or use an hx-on:* attribute on the element itself:

<button hx-post="/example"
        hx-on:htmx:config:request="ctx.request.body.set('source', 'button')">
    Post Me!
</button>

htmx events bubble, so a listener on document or document.body sees events from every element. Use an hx-on:* attribute when you only want to handle events from one element.

The Event Detail

Most htmx events carry a detail object. For request and swap events, detail.ctx is the request context. It holds the source element, the target, the swap style, the request, and, after the response arrives, the response.

htmx.on('htmx:before:request', function (evt) {
    let ctx = evt.detail.ctx;
    console.log(ctx.request.method, ctx.request.action, ctx.target);
});

Inside an hx-on:* attribute every property of detail is already in scope, so you write ctx rather than event.detail.ctx.

Element lifecycle events use detail.elt instead, which is the element htmx processed.

The ctx Object

ctx is the request context object. It is created when a request is triggered and lives until the swap lifecycle ends. Properties marked writable can be changed in an event handler to alter htmx’s behavior.

ctx.request

ctx.request maps directly onto the Fetch API RequestInit. Changes made in htmx:config:request are applied before the request is sent.

Cancelling An Event

htmx events are cancelable. Call preventDefault() to stop htmx from continuing:

htmx.on('htmx:before:request', function (evt) {
    if (!isLoggedIn()) {
        evt.preventDefault();
    }
});

Cancelling has a different effect for each event:

The Event Lifecycle

Request Events

These events fire in order for every request.

Swap Events

Element Lifecycle Events

History Events

See the events reference for the full list, including the trigger events load, intersect and every.

Common Recipes

Initialize A Third Party Library

New content that htmx swaps in is not known to your other libraries. Listen for htmx:after:init to set it up:

htmx.on('htmx:after:init', function (evt) {
    setUpElement(evt.detail.elt);
});

You can also use htmx.onLoad(), which is a shorthand for this.

Add A Value To Every Request

htmx:config:request fires before the request body is encoded, so ctx.request.body is still a FormData object:

htmx.on('htmx:config:request', function (evt) {
    evt.detail.ctx.request.body.set('csrf-token', getToken());
});

To add a header instead, write to ctx.request.headers:

htmx.on('htmx:config:request', function (evt) {
    evt.detail.ctx.request.headers['X-CSRF-Token'] = getToken();
});

Change The Target Or Swap Style

Both are on the context, so you can change them up to the point of the swap:

htmx.on('htmx:after:request', function (evt) {
    if (evt.detail.ctx.response.status === 404) {
        evt.detail.ctx.target = document.querySelector('#errors');
    }
});

For the declarative version of this, see hx-status.

Logging Events

Set htmx.config.logAll to true to log every htmx event to the console:

htmx.config.logAll = true;

You can also set it from HTML:

<meta name="htmx-config" content="logAll:true">

htmx always logs events whose detail carries an error at error level, and events whose detail carries a warn at warning level. logAll adds everything else.

See Also

• Client-Side Scripting
• The hx-on:* attributes
• Events reference
• htmx Extension Authoring Guide, which hooks the same events from an extension