#Core Attribute Reference

The following are the most common attributes when using htmx.

hx-boostadd or remove progressive enhancement for links and forms
hx-getissues a GET to the specified URL
hx-postissues a POST to the specified URL
hx-onhandle any event with a script inline
hx-push-urlpushes the URL into the browser location bar, creating a new history entry
hx-selectselect content to swap in from a response
hx-select-oobselect content to swap in from a response, out of band (somewhere other than the target)
hx-swapcontrols how content is swapped in (outerHTML, beforeend, afterend, …)
hx-swap-oobmarks content in a response to be out of band (should swap in somewhere other than the target)
hx-targetspecifies the target element to be swapped
hx-triggerspecifies the event that triggers the request
hx-valsadds values to the parameters to submit with the request (JSON-formatted)

#Additional Attribute Reference

The table below lists all other attributes available in htmx.

hx-confirmshows a confirm() dialog before issuing a request
hx-deleteissues a DELETE to the specified URL
hx-disabledisables htmx processing for the given node and any children nodes
hx-disabled-eltadds the disabled attribute to the specified elements while a request is in flight
hx-disinheritcontrol and disable automatic attribute inheritance for child nodes
hx-encodingchanges the request encoding type
hx-extextensions to use for this element
hx-headersadds to the headers that will be submitted with the request
hx-historyprevent sensitive data being saved to the history cache
hx-history-eltthe element to snapshot and restore during history navigation
hx-includeinclude additional data in requests
hx-indicatorthe element to put the htmx-request class on during the request
hx-paramsfilters the parameters that will be submitted with a request
hx-patchissues a PATCH to the specified URL
hx-preservespecifies elements to keep unchanged between requests
hx-promptshows a prompt() before submitting a request
hx-putissues a PUT to the specified URL
hx-replace-urlreplace the URL in the browser location bar
hx-requestconfigures various aspects of the request
hx-ssehas been moved to an extension. Documentation for older versions
hx-synccontrol how requests made by different elements are synchronized
hx-validateforce elements to validate themselves before a request
hx-varsadds values dynamically to the parameters to submit with the request (deprecated, please use hx-vals)
hx-wshas been moved to an extension. Documentation for older versions

#CSS Class Reference

htmx-addedApplied to a new piece of content before it is swapped, removed after it is settled.
htmx-indicatorA dynamically generated class that will toggle visible (opacity:1) when a htmx-request class is present
htmx-requestApplied to either the element or the element specified with hx-indicator while a request is ongoing
htmx-settlingApplied to a target after content is swapped, removed after it is settled. The duration can be modified via hx-swap.
htmx-swappingApplied to a target before any content is swapped, removed after it is swapped. The duration can be modified via hx-swap.

#HTTP Header Reference

#Request Headers Reference

HX-Boostedindicates that the request is via an element using hx-boost
HX-Current-URLthe current URL of the browser
HX-History-Restore-Request“true” if the request is for history restoration after a miss in the local history cache
HX-Promptthe user response to an hx-prompt
HX-Requestalways “true”
HX-Targetthe id of the target element if it exists
HX-Trigger-Namethe name of the triggered element if it exists
HX-Triggerthe id of the triggered element if it exists

#Response Headers Reference

HX-Locationallows you to do a client-side redirect that does not do a full page reload
HX-Push-Urlpushes a new url into the history stack
HX-Redirectcan be used to do a client-side redirect to a new location
HX-Refreshif set to “true” the client-side will do a full refresh of the page
HX-Replace-Urlreplaces the current URL in the location bar
HX-Reswapallows you to specify how the response will be swapped. See hx-swap for possible values
HX-Retargeta CSS selector that updates the target of the content update to a different element on the page
HX-Reselecta CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing hx-select on the triggering element
HX-Triggerallows you to trigger client-side events
HX-Trigger-After-Settleallows you to trigger client-side events after the settle step
HX-Trigger-After-Swapallows you to trigger client-side events after the swap step

#Event Reference

htmx:abortsend this event to an element to abort a request
htmx:afterOnLoadtriggered after an AJAX request has completed processing a successful response
htmx:afterProcessNodetriggered after htmx has initialized a node
htmx:afterRequesttriggered after an AJAX request has completed
htmx:afterSettletriggered after the DOM has settled
htmx:afterSwaptriggered after new content has been swapped in
htmx:beforeCleanupElementtriggered before htmx disables an element or removes it from the DOM
htmx:beforeOnLoadtriggered before any response processing occurs
htmx:beforeProcessNodetriggered before htmx initializes a node
htmx:beforeRequesttriggered before an AJAX request is made
htmx:beforeSwaptriggered before a swap is done, allows you to configure the swap
htmx:beforeSendtriggered just before an ajax request is sent
htmx:configRequesttriggered before the request, allows you to customize parameters, headers
htmx:confirmtriggered after a trigger occurs on an element, allows you to cancel (or delay) issuing the AJAX request
htmx:historyCacheErrortriggered on an error during cache writing
htmx:historyCacheMisstriggered on a cache miss in the history subsystem
htmx:historyCacheMissErrortriggered on a unsuccessful remote retrieval
htmx:historyCacheMissLoadtriggered on a successful remote retrieval
htmx:historyRestoretriggered when htmx handles a history restoration action
htmx:beforeHistorySavetriggered before content is saved to the history cache
htmx:loadtriggered when new content is added to the DOM
htmx:noSSESourceErrortriggered when an element refers to a SSE event in its trigger, but no parent SSE source has been defined
htmx:onLoadErrortriggered when an exception occurs during the onLoad handling in htmx
htmx:oobAfterSwaptriggered after an out of band element as been swapped in
htmx:oobBeforeSwaptriggered before an out of band element swap is done, allows you to configure the swap
htmx:oobErrorNoTargettriggered when an out of band element does not have a matching ID in the current DOM
htmx:prompttriggered after a prompt is shown
htmx:pushedIntoHistorytriggered after an url is pushed into history
htmx:responseErrortriggered when an HTTP response error (non-200 or 300 response code) occurs
htmx:sendErrortriggered when a network error prevents an HTTP request from happening
htmx:sseErrortriggered when an error occurs with a SSE source
htmx:sseOpentriggered when a SSE source is opened
htmx:swapErrortriggered when an error occurs during the swap phase
htmx:targetErrortriggered when an invalid target is specified
htmx:timeouttriggered when a request timeout occurs
htmx:validation:validatetriggered before an element is validated
htmx:validation:failedtriggered when an element fails validation
htmx:validation:haltedtriggered when a request is halted due to validation errors
htmx:xhr:aborttriggered when an ajax request aborts
htmx:xhr:loadendtriggered when an ajax request ends
htmx:xhr:loadstarttriggered when an ajax request starts
htmx:xhr:progresstriggered periodically during an ajax request that supports progress events

#JavaScript API Reference

htmx.addClass()Adds a class to the given element
htmx.ajax()Issues an htmx-style ajax request
htmx.closest()Finds the closest parent to the given element matching the selector
htmx.configA property that holds the current htmx config object
htmx.createEventSourceA property holding the function to create SSE EventSource objects for htmx
htmx.createWebSocketA property holding the function to create WebSocket objects for htmx
htmx.defineExtension()Defines an htmx extension
htmx.find()Finds a single element matching the selector
htmx.findAll() htmx.findAll(elt, selector)Finds all elements matching a given selector
htmx.logAll()Installs a logger that will log all htmx events
htmx.loggerA property set to the current logger (default is null) an event listener from the given element
htmx.on()Creates an event listener on the given element, returning it
htmx.onLoad()Adds a callback handler for the htmx:load event
htmx.parseInterval()Parses an interval declaration into a millisecond value
htmx.process()Processes the given element and its children, hooking up any htmx behavior
htmx.remove()Removes the given element
htmx.removeClass()Removes a class from the given element
htmx.removeExtension()Removes an htmx extension
htmx.takeClass()Takes a class from other elements for the given element
htmx.toggleClass()Toggles a class from the given element
htmx.trigger()Triggers an event on an element
htmx.values()Returns the input values associated with the given element

#Configuration Reference

Htmx has some configuration options that can be accessed either programmatically or declaratively. They are listed below:

Config VariableInfo
htmx.config.historyEnableddefaults to true, really only useful for testing
htmx.config.historyCacheSizedefaults to 10
htmx.config.refreshOnHistoryMissdefaults to false, if set to true htmx will issue a full page refresh on history misses rather than use an AJAX request
htmx.config.defaultSwapStyledefaults to innerHTML
htmx.config.defaultSwapDelaydefaults to 0
htmx.config.defaultSettleDelaydefaults to 20
htmx.config.includeIndicatorStylesdefaults to true (determines if the indicator styles are loaded)
htmx.config.indicatorClassdefaults to htmx-indicator
htmx.config.requestClassdefaults to htmx-request
htmx.config.addedClassdefaults to htmx-added
htmx.config.settlingClassdefaults to htmx-settling
htmx.config.swappingClassdefaults to htmx-swapping
htmx.config.allowEvaldefaults to true, can be used to disable htmx’s use of eval for certain features (e.g. trigger filters)
htmx.config.allowScriptTagsdefaults to true, determines if htmx will process script tags found in new content
htmx.config.inlineScriptNoncedefaults to '', meaning that no nonce will be added to inline scripts
htmx.config.attributesToSettledefaults to ["class", "style", "width", "height"], the attributes to settle during the settling phase
htmx.config.useTemplateFragmentsdefaults to false, HTML template tags for parsing content from the server (not IE11 compatible!)
htmx.config.wsReconnectDelaydefaults to full-jitter
htmx.config.wsBinaryTypedefaults to blob, the the type of binary data being received over the WebSocket connection
htmx.config.disableSelectordefaults to [hx-disable], [data-hx-disable], htmx will not process elements with this attribute on it or a parent
htmx.config.withCredentialsdefaults to false, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates
htmx.config.timeoutdefaults to 0, the number of milliseconds a request can take before automatically being terminated
htmx.config.scrollBehaviordefaults to ‘smooth’, the behavior for a boosted link on page transitions. The allowed values are auto and smooth. Smooth will smoothscroll to the top of the page while auto will behave like a vanilla link.
htmx.config.defaultFocusScrollif the focused element should be scrolled into view, defaults to false and can be overridden using the focus-scroll swap modifier.
htmx.config.getCacheBusterParamdefaults to false, if set to true htmx will include a cache-busting parameter in GET requests to avoid caching partial responses by the browser
htmx.config.globalViewTransitionsif set to true, htmx will use the View Transition API when swapping in new content.
htmx.config.methodsThatUseUrlParamsdefaults to ["get"], htmx will format requests with these methods by encoding their parameters in the URL, not the request body
htmx.config.selfRequestsOnlydefaults to false, if set to true will only allow AJAX requests to the same domain as the current document
htmx.config.ignoreTitledefaults to false, if set to true htmx will not update the title of the document when a title tag is found in new content
htmx.config.scrollIntoViewOnBoostdefaults to true, whether or not the target of a boosted element is scrolled into the viewport. If hx-target is omitted on a boosted element, the target defaults to body, causing the page to scroll to the top.

You can set them directly in javascript, or you can use a meta tag:

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