Htmx provides an extensive events system that can be used to modify and enhance behavior. Events are listed below.
htmx:afterOnLoadThis 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.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:afterProcessNodeThis event is triggered after htmx has initialized a DOM node. It can be useful for extensions to build additional features onto a node.
detail.elt - the element that dispatched the requesthtmx:afterRequestThis 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.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:afterSettleThis event is triggered after the DOM has settled.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:afterSwapThis event is triggered after new content has been swapped into the DOM.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:beforeOnLoadThis event is triggered before any response processing occurs. If the event is cancelled, no swap will occur.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:beforeProcessNodeThis 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.
detail.elt - the element that dispatched the requesthtmx:beforeRequestThis event is triggered before an AJAX request is issued. If the event is cancelled, no request will occur.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:beforeSendThis event is triggered right before a request is sent. You may not cancel the request with this event.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:beforeSwapThis event is triggered before any new content has been swapped into the DOM. If the event is cancelled, 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.
detail.elt - the element that dispatched the requestdetail.xhr - the XMLHttpRequestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requestdetail.shouldSwap - if the content will be swapped (defaults to false for non-200 response codes)detail.target - the target of the swaphtmx:configRequestThis 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.
detail.parameters - the parameters that will be submitted in the requestdetail.unfilteredParameters - the parameters that were found before filtering by hx-selectdetail.headers - the request headersdetail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.verb - the HTTP verb in usehtmx:historyCacheErrorThis event is triggered when an attempt to save the cache to localStorage fails
detail.cause - the Exception that was thrown when attempting to save history to localStoragehtmx:historyCacheMissThis event is triggered when a cache miss occurs when restoring history
detail.xhr - the XMLHttpRequest that will retrieve the remote content for restorationdetail.path - the path and query of the page being restoredhtmx:historyCacheMissErrorThis 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)
detail.xhr - the XMLHttpRequestdetail.path - the path and query of the page being restoredhtmx:historyCacheMissLoadThis event is triggered when a cache miss occurs and a response has been retrieved succesfully from the server for the content to restore
detail.xhr - the XMLHttpRequestdetail.path - the path and query of the page being restoredhtmx:historyRestoreThis event is triggered when htmx handles a history restoration action
detail.path - the path and query of the page being restoredhtmx:beforeHistorySaveThis event is triggered when htmx handles a history restoration action
detail.path - the path and query of the page being restoreddetail.historyElt - the history element being restored intodetail.config - the config that will be passed to the EventSource contstructorhtmx:loadThis event is triggered when a new node is loaded into the DOM by htmx.
detail.elt - the newly added elementhtmx:noSSESourceErrorThis event is triggered when an element refers to a SSE event in its trigger, but no parent SSE source has been defined
detail.elt - the element with the bad SSE triggerhtmx:onLoadErrorThis event is triggered when an error occurs during the load handling of an AJAX call
detail.xhr - the XMLHttpRequestdetail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.exception - the exception that occurreddetail.requestConfig - the configuration of the AJAX requesthtmx:oobErrorNoTargetThis event is triggered when an out of band swap does not have a corresponding element in the DOM to switch with.
detail.content - the element with the bad oob idhtmx:promptThis 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.
detail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.prompt - the user response to the prompthtmx:pushedIntoHistoryThis event is triggered after an url has been pushed into history.
detail.path - the path and query of the url that has been pushed into historyhtmx:responseErrorThis event is triggered when an HTTP error response occurs
detail.xhr - the XMLHttpRequestdetail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:sendErrorThis event is triggered when a network error prevents an HTTP request from occurring
detail.xhr - the XMLHttpRequestdetail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:sseErrorThis event is triggered when an error occurs with a SSE source
detail.elt - the element with the bad SSE sourcedetail.error - the errordetail.source - the SSE sourcehtmx:swapErrorThis event is triggered when an error occurs during the swap phase
detail.xhr - the XMLHttpRequestdetail.elt - the element that triggered the requestdetail.target - the target of the requestdetail.requestConfig - the configuration of the AJAX requesthtmx:targetErrorThis event is triggered when a bad selector is used for a hx-target attribute (e.g. an
element id without a preceding #)
detail.elt - the element that triggered the requestdetail.target - the bad CSS selectorThis 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>
detail.elt - the element that triggered the requestThis event is triggered when an element fails validation.
detail.elt - the element that triggered the requestdetail.message - the validation error messagedetail.validity - the validity object, which contains properties specifying how validation failedThis event is triggered when a request is halted due to validation errors.
detail.elt - the element that triggered the requestdetail.errors - an array of error objects with the invalid elements and errors associated with themThis event is triggered when an ajax request aborts
detail.elt - the element that triggered the requestThis event is triggered when an ajax request starts
detail.elt - the element that triggered the requestThis event is triggered when an ajax request finishes
detail.elt - the element that triggered the requestThis event is triggered periodically when an ajax request that supports progress is in flight
detail.elt - the element that triggered the request