Events

Htmx provides an extensive events system that can be used to modify and enhance behavior. Events are listed below.

Event - htmx:abort

This event is different than other events: htmx does not trigger it, but rather listens for it.

If you send an htmx:abort event to an element making a request, it will abort the request:

<button id="request-button" hx-post="/example">Issue Request</button>
<button onclick="htmx.trigger('#request-button', 'htmx:abort')">Cancel Request</button>

Event - htmx:afterOnLoad

This event is triggered after an AJAX onload has finished. Note that this does not mean that the content has been swapped or settled yet, only that the request has finished.

Details

Event - htmx:afterProcessNode

This event is triggered after htmx has initialized a DOM node. It can be useful for extensions to build additional features onto a node.

Details

Event - htmx:afterRequest

This event is triggered after an AJAX request has finished either in the case of a successful request (although one that may have returned a remote error code such as a 404) or in a network error situation. This event can be paired with htmx:beforeRequest to wrap behavior around a request cycle.

Details

Event - htmx:afterSettle

This event is triggered after the DOM has settled.

Details

Event - htmx:afterSwap

This event is triggered after new content has been swapped into the DOM.

Details

Event - htmx:beforeCleanupElement

This event is triggered before htmx disables an element or removes it from the DOM.

Details

Event - htmx:beforeOnLoad

This event is triggered before any response processing occurs. If you call preventDefault() on the event to cancel it, no swap will occur.

Details

Event - htmx:beforeProcessNode

This event is triggered before htmx initializes a DOM node and has processed all of its hx- attributes. This gives extensions and other external code the ability to modify the contents of a DOM node before it is processed.

Details

Event - htmx:beforeRequest

This event is triggered before an AJAX request is issued. If you call preventDefault() on the event to cancel it, no request will occur.

Details

Event - htmx:beforeSend

This event is triggered right before a request is sent. You may not cancel the request with this event.

Details

Event - htmx:beforeSwap

This event is triggered before any new content has been swapped into the DOM. If you call preventDefault() on the event to cancel it, no swap will occur.

You can modify the default swap behavior by modifying the shouldSwap and target properties of the event detail. See the documentation on configuring swapping for more details.

Details

Event - htmx:beforeTransition

This event is triggered before a View Transition wrapped swap occurs. If you call preventDefault() on the event to cancel it, the View Transition will not occur and the normal swapping logic will happen instead.

Details

Event - htmx:configRequest

This event is triggered after htmx has collected parameters for inclusion in the request. It can be used to include or update the parameters that htmx will send:

document.body.addEventListener('htmx:configRequest', function(evt) {
    evt.detail.parameters['auth_token'] = getAuthToken(); // add a new parameter into the mix
});

Note that if an input value appears more than once the value in the parameters object will be an array, rather than a single value.

Details

Event - htmx:confirm

This event is fired on every trigger for a request (not just on elements that have a hx-confirm attribute). It allows you to cancel (or delay) issuing the AJAX request. If you call preventDefault() on the event, it will not issue the given request. The detail object contains a function, evt.detail.issueRequest(skipConfirmation=false), that can be used to issue the actual AJAX request at a later point. Combining these two features allows you to create an asynchronous confirmation dialog.

Here is a basic example that shows the basic usage of the htmx:confirm event without altering the default behavior:

document.body.addEventListener('htmx:confirm', function(evt) {
  // 0. To modify the behavior only for elements with the hx-confirm attribute,
  //    check if evt.detail.target.hasAttribute('hx-confirm')

  // 1. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();
  
  // 2. Do your own logic here
  console.log(evt.detail)

  // 3. Manually issue the request when you are ready
  evt.detail.issueRequest(); // or evt.detail.issueRequest(true) to skip the built-in window.confirm()
});

And here is an example using sweet alert on any element with a confirm-with-sweet-alert="{question}" attribute on it:

document.body.addEventListener('htmx:confirm', function(evt) {
  // 1. The requirement to show the sweet alert is that the element has a confirm-with-sweet-alert
  //    attribute on it, if it doesn't we can return early and let the default behavior happen
  if (!evt.detail.target.hasAttribute('confirm-with-sweet-alert')) return

  // 2. Get the question from the attribute
  const question = evt.detail.target.getAttribute('confirm-with-sweet-alert');

  // 3. Prevent the default behavior (this will prevent the request from being issued)
  evt.preventDefault();

  // 4. Show the sweet alert
  swal({
    title: "Are you sure?",
    text: question || "Are you sure you want to continue?",
    icon: "warning",
    buttons: true,
    dangerMode: true,
  }).then((confirmed) => {
    if (confirmed) {
      // 5. If the user confirms, we can manually issue the request
      evt.detail.issueRequest(true); // true to skip the built-in window.confirm()
    }
  });
});
Details

Event - htmx:historyCacheError

This event is triggered when an attempt to save the cache to localStorage fails

Details

Event - htmx:historyCacheMiss

This event is triggered when a cache miss occurs when restoring history

Details

Event - htmx:historyCacheMissError

This event is triggered when a cache miss occurs and a response has been retrieved from the server for the content to restore, but the response is an error (e.g. 404)

Details

Event - htmx:historyCacheMissLoad

This event is triggered when a cache miss occurs and a response has been retrieved successfully from the server for the content to restore

Details

Event - htmx:historyRestore

This event is triggered when htmx handles a history restoration action

Details

Event - htmx:beforeHistorySave

This event is triggered before the content is saved in the history api.

Details
Details

Event - htmx:load

This event is triggered when a new node is loaded into the DOM by htmx.

Details

Event - htmx:noSSESourceError

This event is triggered when an element refers to an SSE event in its trigger, but no parent SSE source has been defined

Details

Event - htmx:oobAfterSwap

This event is triggered as part of an out of band swap and behaves identically to an after swap event

Details

Event - htmx:oobBeforeSwap

This event is triggered as part of an out of band swap and behaves identically to a before swap event

Details

Event - htmx:oobErrorNoTarget

This event is triggered when an out of band swap does not have a corresponding element in the DOM to switch with.

Details

Event - htmx:onLoadError

This event is triggered when an error occurs during the load handling of an AJAX call

Details

Event - htmx:prompt

This event is triggered after a prompt has been shown to the user with the hx-prompt attribute. If this event is cancelled, the AJAX request will not occur.

Details

Event - htmx:beforeHistoryUpdate

This event is triggered before a history update is performed. It can be used to modify the path or type used to update the history.

Details

Event - htmx:pushedIntoHistory

This event is triggered after a URL has been pushed into history.

Details

Event - htmx:replacedInHistory

This event is triggered after a URL has been replaced in history.

Details

Event - htmx:responseError

This event is triggered when an HTTP error response occurs

Details

Event - htmx:sendAbort

This event is triggered when a request is aborted

Details

Event - htmx:sendError

This event is triggered when a network error prevents an HTTP request from occurring

Details

Event - htmx:sseError

This event is triggered when an error occurs with an SSE source

Details

Event - htmx:swapError

This event is triggered when an error occurs during the swap phase

Details

Event - htmx:targetError

This event is triggered when a bad selector is used for a hx-target attribute (e.g. an element ID without a preceding #)

Details

Event - htmx:timeout

This event is triggered when a request timeout occurs. This wraps the typical timeout event of XMLHttpRequest.

Timeout time can be set using htmx.config.timeout or per element using hx-request

Details

Event - htmx:trigger

This event is triggered whenever an AJAX request would be, even if no AJAX request is specified. It is primarily intended to allow hx-trigger to execute client-side scripts; AJAX requests have more granular events available, like htmx:beforeRequest or htmx:afterRequest.

Details

Event - htmx:validateUrl

This event is triggered before a request is made, allowing you to validate the URL that htmx is going to request. If preventDefault() is invoked on the event, the request will not be made.

document.body.addEventListener('htmx:validateUrl', function (evt) {
  // only allow requests to the current server as well as myserver.com
  if (!evt.detail.sameHost && evt.detail.url.hostname !== "myserver.com") {
    evt.preventDefault();
  }
});
Details

Event - htmx:validation:validate

This event is triggered before an element is validated. It can be used with the elt.setCustomValidity() method to implement custom validation rules.

<form hx-post="/test">
  <input _="on htmx:validation:validate
               if my.value != 'foo'
                  call me.setCustomValidity('Please enter the value foo')
               else
                  call me.setCustomValidity('')"
         name="example">
</form>
Details

Event - htmx:validation:failed

This event is triggered when an element fails validation.

Details

Event - htmx:validation:halted

This event is triggered when a request is halted due to validation errors.

Details

Event - htmx:xhr:abort

This event is triggered when an ajax request aborts

Details

Event - htmx:xhr:loadstart

This event is triggered when an ajax request starts

Details

Event - htmx:xhr:loadend

This event is triggered when an ajax request finishes

Details

Event - htmx:xhr:progress

This event is triggered periodically when an ajax request that supports progress is in flight

Details