HTMX Events & API

// Both work
document.addEventListener('htmx:afterSwap', handler);
document.addEventListener('htmx:after-swap', handler);

<!-- Correct -->
<div hx-on:htmx:after-swap="handler()">

<!-- Will NOT work (HTML lowercases attributes) -->
<div hx-on:htmx:afterSwap="handler()">

// Find single element
htmx.find('#my-element');
htmx.find(parentElt, '.child');

// Find all matching elements
htmx.findAll('.items');
htmx.findAll(parentElt, '.items');

// Find closest ancestor
htmx.closest(elt, 'form');

// Basic AJAX request
htmx.ajax('GET', '/api/data', '#target');

// With options
htmx.ajax('POST', '/api/data', {
    target: '#target',
    swap: 'innerHTML',
    values: { key: 'value' },
    headers: { 'X-Custom': 'header' },
    source: '#source-element',
    select: '#content',
    selectOOB: '#sidebar',
    push: true,
    replace: false
}).then(() => {
    console.log('Request complete');
});

// Class manipulation (all accept optional delay in ms)
htmx.addClass(elt, 'active');
htmx.addClass(elt, 'active', 1000);  // add after 1s delay
htmx.removeClass(elt, 'active');
htmx.removeClass(elt, 'active', 500);  // remove after 500ms
htmx.toggleClass(elt, 'active');

// Take class from siblings (only this element gets it)
htmx.takeClass(elt, 'selected');

// Remove element from DOM (optional delay in ms)
htmx.remove(elt);
htmx.remove(elt, 2000);  // remove after 2s

// Swap content programmatically
htmx.swap(targetElt, '<p>New content</p>', {
    swapStyle: 'innerHTML',
    swapDelay: 0,
    settleDelay: 20,
    transition: false,
    ignoreTitle: false,
    head: 'merge',  // or 'append'
    scroll: 'top',
    focusScroll: false
}, {
    select: '#content',
    selectOOB: '#sidebar',
    afterSwapCallback: function() {},
    afterSettleCallback: function() {}
});

// Listen for events
var listener = htmx.on('#my-element', 'htmx:afterSwap', function(event) {
    console.log('Swapped!', event.detail);
});

// Listen on document
htmx.on('htmx:afterSwap', function(event) {
    console.log('Any swap:', event.detail);
});

// Remove listener
htmx.off('#my-element', 'htmx:afterSwap', listener);

// Trigger events
htmx.trigger(elt, 'myCustomEvent', { key: 'value' });

// Trigger abort on an element's in-flight request
htmx.trigger(elt, 'htmx:abort');

// Process dynamically-added HTML for HTMX attributes
var newContent = document.createElement('div');
newContent.innerHTML = '<button hx-get="/api">Load</button>';
document.body.appendChild(newContent);
htmx.process(newContent); // Now HTMX recognizes the button

// Initialize third-party libraries on new content
htmx.onLoad(function(content) {
    // Runs every time HTMX swaps new content into the DOM
    var tooltips = content.querySelectorAll('[data-tooltip]');
    tooltips.forEach(initTooltip);
});

// Get form values from an element ('get' or 'post' mode)
var values = htmx.values(formElement);
var values = htmx.values(formElement, 'get');

// Parse interval string to milliseconds
htmx.parseInterval('500ms'); // 500
htmx.parseInterval('2s');    // 2000
// Caution: '3m' uses parseFloat, won't parse as minutes

// Customize SSE EventSource creation
htmx.createEventSource = function(url) {
    return new EventSource(url, { withCredentials: true });
};

// Customize WebSocket creation
htmx.createWebSocket = function(url) {
    return new WebSocket(url, ['wss']);
};

// Define a custom extension
htmx.defineExtension('my-ext', {
    onEvent: function(name, event) {
        if (name === 'htmx:beforeRequest') {
            // Modify request
        }
    },
    transformResponse: function(text, xhr, elt) {
        return text; // Transform response HTML
    },
    isInlineSwap: function(swapStyle) {
        return false;
    },
    handleSwap: function(swapStyle, target, fragment, settleInfo) {
        return false; // Return true if handled
    },
    encodeParameters: function(xhr, parameters, elt) {
        return null; // Return encoded body or null
    }
});

// Remove extension
htmx.removeExtension('my-ext');

htmx.config.defaultSwapStyle = 'outerHTML';
htmx.config.historyCacheSize = 20;

<meta name="htmx-config" content='{
    "defaultSwapStyle": "outerHTML",
    "historyCacheSize": 20
}' />

<!-- Via CDN -->
<script src="https://unpkg.com/htmx-ext-preload@2.1.0/preload.js"></script>

<!-- Enable on element or parent -->
<body hx-ext="preload">
    ...
</body>

<div hx-ext="sse" sse-connect="/events">
    <!-- Swap content when 'message' event is received -->
    <div sse-swap="message">Waiting for messages...</div>

    <!-- Trigger HTMX request on SSE event -->
    <div hx-get="/update" hx-trigger="sse:notification">Notifications</div>
</div>

<div hx-ext="ws" ws-connect="/ws">
    <!-- Send form data over WebSocket -->
    <form ws-send>
        <input name="message" />
        <button type="submit">Send</button>
    </form>

    <!-- Content area updated by WebSocket messages -->
    <div id="messages"></div>
</div>

<div hx-ext="response-targets">
    <form hx-post="/submit"
          hx-target="#success"
          hx-target-422="#form-errors"
          hx-target-5*="#server-error">
        ...
    </form>
    <div id="success"></div>
    <div id="form-errors"></div>
    <div id="server-error"></div>
</div>

<div hx-ext="preload">
    <!-- Preload enabled here -->
    <div hx-ext="ignore:preload">
        <!-- Preload disabled here -->
    </div>
</div>

htmx.logAll();

// Disable all logging
htmx.logNone();

htmx.logger = function(elt, event, data) {
    if (event === 'htmx:responseError') {
        console.error('HTMX Error:', data);
    }
};

// Monitor all events on a specific element
monitorEvents(document.getElementById('my-element'));

<script src="https://demo.htmx.org"></script>

<template url="/api/greeting" delay="500">
    <p>Hello, World!</p>
</template>

<button hx-get="/api/greeting" hx-target="#output">
    Get Greeting
</button>
<div id="output"></div>

<!-- React to DOM events -->
<button hx-on:click="console.log('clicked')">Click</button>

<!-- React to HTMX events (kebab-case required) -->
<form hx-post="/submit"
      hx-on:htmx:before-request="showSpinner()"
      hx-on:htmx:after-request="hideSpinner()">
    ...
</form>

<!-- Access event detail -->
<div hx-get="/data"
     hx-on:htmx:config-request="event.detail.parameters.timestamp = Date.now()">
    Load
</div>

<div x-data="{ count: 0 }" hx-get="/data" hx-trigger="click">
    <span x-text="count"></span>
    <button @click="count++">Local increment</button>
</div>

htmx.onLoad(function(content) {
    // Initialize any library that needs DOM elements
    var charts = content.querySelectorAll('.chart');
    charts.forEach(function(el) {
        new Chart(el, JSON.parse(el.dataset.config));
    });
});

document.addEventListener('htmx:beforeCleanupElement', function(event) {
    var chart = Chart.getChart(event.target);
    if (chart) {
        chart.destroy();
    }
});

var container = document.getElementById('dynamic');
container.innerHTML = '<button hx-get="/api/data">Load</button>';
htmx.process(container);

<!-- Third-party fires 'map:click' on this element -->
<div id="map"
     hx-get="/location"
     hx-trigger="map:click"
     hx-target="#location-info">
</div>
<div id="location-info"></div>