htmx Fundamentals

A classic web page works like this: a link or a form makes the browser request a URL, the server answers with a complete HTML document, and the browser replaces the current page. htmx keeps that model and removes one restriction: any element can issue the request, on any event, with any HTTP method, and the response replaces any element instead of the whole window. The server still answers with HTML, so the application stays a hypermedia application: the markup it returns contains the next set of available actions (links, forms, buttons with hx-* attributes), which is the idea of Hypertext As The Engine Of Application State (HATEOAS). There is no JSON contract to keep in sync with a front-end model, and no client-side templating. This style is called HTML over the wire, and it fits Thymeleaf very well, because a Thymeleaf template can already render a fragment on its own (see Fragments and Fragment Rendering & AJAX).

The whole exchange of one htmx request, from the keystroke to the swapped DOM, looks like this (this is the active-search input of the demo application of this page):

Source: htmx — Requests & Responses

htmx has a design rule that matters for Thymeleaf applications: it is progressive enhancement friendly. The search input of the demo sits inside a normal GET form with a submit button, so a browser without JavaScript still searches (the whole page is reloaded). hx-boost goes further and turns ordinary links and forms into AJAX requests with no change to the markup, and falls back to normal navigation when JavaScript is off. Other patterns need more work to degrade gracefully, and some cannot degrade at all; that is a trade-off you make per feature. Two server-side consequences follow, and both appear again in the pitfalls table:

Source: htmx — Progressive Enhancement

htmx has no dependencies and needs no build step. Four ways of getting htmx.min.js into a Thymeleaf application, from quickest to most controlled:

Source: htmx — Installing

The CDN snippet with SRI. The hash below is the SHA-384 of the exact file at that exact version: it was computed on 2026-10-08 with curl ... | openssl dgst -sha384 -binary | openssl base64 -A and matches the value printed on the htmx documentation. A hash is only valid for the pinned version, so update both together; with @2 or @latest the SRI check would fail on the next release, and without a pinned URL there is nothing to verify.

Source: htmx — Via a CDN

The webjar variant used by the demo (Maven; the Spring Boot 4.1.1 BOM does not manage org.webjars.npm:htmx.org, so give the version, which is the htmx version):

and the reference from a template, with the versioned path (the context path and any resource versioning are applied by the @{...} link expression; see Link URLs):

The script is deferred, so other scripts that call htmx (the demo’s shelf.js) must be deferred too and listed after it. The BOM does manage webjars-locator-lite, which can resolve version-less webjar paths; that route was not exercised here. Spring Security must let the unauthenticated login page load the script and styles, so the demo’s filter chain permits /webjars/**, /js/** and /css/**.

Source: WebJars

Five attributes issue a request, each with the URL as its value: hx-get, hx-post, hx-put, hx-patch and hx-delete. The element makes the request when its trigger fires (see Triggers) and, by default, puts the response inside itself.

Source: htmx — AJAX

In a Thymeleaf template the URL is a link expression, so the context path, the path variables and the URL encoding are handled by Thymeleaf. The attribute is written as th:hx-get, because the Standard Dialect sets any attribute with the th: prefix by evaluating its value as a Standard Expression (the default attribute processor); th:hx-get="@{/shelf}" renders as hx-get="/shelf". The same works for every hx-* attribute, and a conditional expression that yields null removes the attribute, which this page uses for hx-swap-oob and for the polling of a finished job. If you also write a static hx-get next to the th:hx-get, the static value is what a browser shows when it opens the template file without Thymeleaf, which keeps the template natural.

Rendered (book 1):

Source: Using Thymeleaf — Setting the value of any attribute (default attribute processor)

The hx-* attribute values that are fixed (hx-target, hx-swap, hx-confirm above) need no th: prefix. Use th:hx-* only for values computed on the server: URLs, ids, flags. Never concatenate user-provided text into an attribute that htmx interprets as code or JSON, see Security. The dialect that adds shorter attributes (hx:get, with automatic CSRF) belongs to the library described on htmx with Spring Boot; everything here works without it.

htmx also accepts the data- prefix for every attribute (data-hx-post), for editors or validators that reject unknown attributes. Attribute names are case-insensitive in HTML, so hx-on handlers cannot use camel-case event names; see Events.

Source: htmx — Introduction

All examples below come from one small Spring MVC application, the Bookshelf shelf page at /shelf. It keeps three books in memory (Dune, Emma, Hyperion) in a Shelf bean, and has a controller (ShelfController) and two template files: shelf/index.html (the page) and shelf/fragments.html (the fragments that an htmx request returns). Spring Security is on with its default CSRF protection; the filter chain permits the static resources and additionally enables HTTP Basic, only so that curl can authenticate without a login form.

The head of every page is a fragment. It loads htmx and the demo script, publishes the CSRF token in two meta tags (see CSRF), and puts the htmx configuration in the htmx-config meta tag (see Configuration):

Source: htmx — Configuring htmx

The controller answers the same URL with the full page or with the fragment. A boosted request also carries HX-Request: true, but it swaps the whole body, so it must get the full page; the controller therefore looks at HX-Boosted as well. The view names are constants chosen by the controller, never built from the request:

Source: htmx — Caching

The page contains the search field and a div that holds the results table. The th:insert pulls in the same results fragment the controller returns for an htmx request, so there is a single definition of the table:

Source: Using Thymeleaf — Including template fragments

Calling the URL with and without the header (the cookie jar keeps the session, SHELF_USER and SHELF_PASSWORD stand for the credentials of the scratch application, which are placeholders in its application.properties):

Source: htmx — Request Headers

A request starts when the element’s trigger fires. Without hx-trigger the natural event of the element is used: change for input, textarea and select, submit for a form, and click for everything else. hx-trigger takes a comma-separated list of triggers; each one has its own modifiers. It is not inherited.

A filter is a JavaScript expression in square brackets after the event name; the symbols are resolved against the event first (ctrlKey, key), then the global scope, and this is the element. Filters need eval, so they stop working when htmx.config.allowEval is false. Special events are load (fires once when the element is loaded), revealed (once, when the element scrolls into the viewport), and intersect (once, when it first intersects the viewport; options root:<selector> and threshold:<0.0 to 1.0>). Inside an element with overflow scrolling, use intersect once instead of revealed. Polling is written every <time>, with an optional filter after it (every 1s [!document.hidden] polls only while the tab is visible). A response with HTTP status 286 stops the polling; the response is still swapped. A custom event, for example one sent by the server, is just another trigger name.

Source: htmx — hx-trigger

The demo has one element per kind of trigger. Each one calls /shelf/echo, a small endpoint that reflects the htmx request headers it received (the full list is in Request and response headers):

Source: htmx — Triggers

The echo endpoint, with the fragment it renders. HX-Trigger is the id of the element that triggered the request, HX-Target the id of the target, HX-Trigger-Name the name of the element, and each missing header is null:

Source: htmx — Request Headers

What Chromium (driven by Playwright) did with these triggers:

The every element needs a stop condition on the server. ShelfController counts the requests and sets the status itself:

Source: htmx — Polling

Load polling is the alternative that needs no special status: an element asks once (load delay:300ms) and replaces itself with the response; when the job is finished the server returns a version of the element without the trigger, and polling ends by itself. The th:hx-get and th:hx-trigger below yield null once the progress reaches 100, so both attributes disappear from the rendered element:

The import button (th:hx-post="@{/shelf/import}" with hx-target="#import-slot" and hx-disabled-elt="this") starts it. In Chromium the progress element went through 0%, 25%, 50%, 75% and 100% Import finished, and the button was disabled for the duration of the request and enabled again afterwards.

Source: htmx — Load Polling

By default the response is swapped into the element that made the request. hx-target names another element and is inherited, so it can be placed on a form or a container. Its value is a CSS selector, or one of the extended forms:

Most attributes that take a selector accept the same extended syntax. Relative targets avoid peppering the markup with ids. The demo has one button per form; after clicking each of them, its target contained the tip text. One mistake worth noting, because it is easy to make and the error is quiet: find looks inside the element. A first version of the demo had the find span button next to its span, htmx logged htmx:targetError, find span to the console, and nothing was swapped. The hx-target has to be on the container of the span:

Source: htmx — hx-target

The server sees the id of the target in the HX-Target header (see below). That is also useful for choosing a fragment: a controller that serves two different targets from one URL can return different constant fragments, but it must map the id to a fixed view name instead of using it in a template name or selector.

hx-swap says how the response is put into the target. The default is innerHTML (the value of htmx.config.defaultSwapStyle); the attribute is inherited. The demo starts every swap from the same list:

and every button requests /shelf/swap/piece, which returns <li class="piece">new</li>, with hx-target="#swap-target" and a different hx-swap. The resulting ul after each click in Chromium:

(The li inside li is the browser DOM after the swap, shown literally; it is invalid HTML but proves what each strategy does.) The th:hx-swap on the demo buttons comes from a loop over the nine names, which also shows that a th:hx-* value may be any expression:

Source: htmx — hx-swap

Morphing swaps merge the new content into the existing DOM instead of replacing it, which preserves focus and state, at the cost of more CPU; they come from the idiomorph extension (or morphdom-swap and alpine-morph, which are community extensions).

Besides the verb, the trigger, the target and the swap, a handful of attributes shape what is sent and what happens around it. Most are inherited, so one attribute on a container applies to every htmx element inside it; set a child to unset (or use hx-disinherit) to opt out, and htmx.config.disableInheritance plus hx-inherit turn the model around. hx-trigger and hx-swap-oob are not inherited.

Source: htmx — Reference, Attributes

The most used ones in the demo, in the rows and the toolbar of the page. The status button sends stars but not tracking: hx-vals is static JSON, and hx-params="not tracking" drops it again; the filter select borrows the search text with hx-include; the delete button asks first:

Source: htmx — hx-vals

What the browser sent (Playwright’s record of the requests; the Cookie and CSRF header are left out):

The PUT reached the controller as ordinary request parameters, because Spring Boot’s FormContentFilter parses the body of PUT, PATCH and DELETE forms:

Source: htmx — Parameters

hx-select is for when the server returns more than you want. The button below requests the whole About page and keeps only the element with the id about-body; the rest of the page never reaches the DOM:

In Chromium #about-box afterwards contained exactly <div id="about-body"><p>The Bookshelf keeps your reading list.</p></div>.

Source: htmx — hx-select

A request indicator uses the htmx-request class: the class is put on the requesting element, or on the element named by hx-indicator, and the default style sheet that htmx injects (switch it off with includeIndicatorStyles) fades any htmx-indicator inside it in. The search field of the demo uses hx-indicator="#spinner" with <span id="spinner" class="htmx-indicator">; the opacity transition itself was not measured. hx-disabled-elt="find button" on the add form and hx-disabled-elt="this" on the import button block double submissions.

Source: htmx — hx-indicator

A response can carry more than the main fragment. An element with hx-swap-oob is taken out of the response and swapped into the page by id, wherever it is, and everything else goes to the target in the normal way. The value is true (same as outerHTML), any hx-swap value, or a swap value, a colon and a selector (beforeend:#table tbody). With a strategy other than outerHTML the wrapping element is stripped, so give it the right tag for the context. An element that cannot stand alone in HTML (tr, td, thead, tbody, li and others) is put inside a template element; the template is removed afterwards. It is the way to update a counter, a toast or a navigation highlight in the same response as the main change.

The demo adds a book. The response is the new table row for the target (hx-target="#rows" with hx-swap="beforeend") plus the book counter in the page heading. The counter is the same fragment the page itself includes, rendered without the attribute the first time (oob is false) and with it in the response (oob is true); th:hx-swap-oob yields null when oob is false and the attribute is not rendered:

Source: htmx — Out of Band Swaps

Controller and the wire (curl; the token comes from the page, see CSRF):

In the browser the new row appeared at the end of the table, #count changed from 3 to 4, the hx-on::after-request handler reset the form, and the bookAdded event (see Server-triggered events) wrote "Book #4 added" in the toast.

Source: htmx — hx-swap-oob

Notes on out-of-band swaps:

hx-boost="true" converts the anchors and forms inside an element into AJAX requests: a link becomes a GET whose response replaces the body (the innerHTML swap), the URL is pushed into the browser history, and a form is submitted with its own method and action. Only links to the same domain that are not local anchors are boosted. hx-boost="false" turns it off for a child, and with JavaScript disabled everything is a normal link. The request carries HX-Boosted: true; since it is an AJAX request, keep that in mind for redirects. The demo boosts its navigation:

In Chromium a click on "About" sent GET /shelf/about with HX-Request: true, HX-Boosted: true and HX-Current-URL; the page was not reloaded (a JavaScript marker survived), the URL changed to /shelf/about and document.title became "About - Bookshelf", because htmx takes the title of the response.

Source: htmx — hx-boost

History. hx-push-url="true" pushes the request URL (or the URL given as the attribute value) onto the browser history; hx-replace-url replaces the current entry; false disables a push that would come from an ancestor or from boost. Before the request, htmx saves a snapshot of the body (or of the element with hx-history-elt) in the browser’s web storage, and when the user goes back it swaps the snapshot in again. On a cache miss it requests the URL from the server with HX-History-Restore-Request: true and expects the full page; if htmx.config.refreshOnHistoryMiss is true it reloads the page instead. The documentation says the snapshots live in localStorage; the 2.0.11 source and the Chromium run use sessionStorage under the key htmx-history-cache, so clear that key when testing. hx-history="false" anywhere on a page keeps it out of the cache (for sensitive pages), and htmx.config.historyCacheSize set to 0 disables the cache.

The demo pushes the search URL (hx-push-url="true" on the input and the select; the URL after typing em was /shelf?q=em). The two back-navigation cases, measured in Chromium after a boosted click on "About":

Without that setting a history restore request also carries HX-Request: true, so a controller that returns a fragment for every htmx request would send a fragment where the whole page is needed; the docs recommend always disabling it, and the demo does in the htmx-config meta tag. Vary: HX-Request (the demo adds it) keeps a browser cache from serving a fragment for the full URL; alternatively htmx.config.getCacheBusterParam adds a cache-busting parameter to htmx GET requests.

Source: htmx — History Support

If you push a URL, you must be able to open that URL directly and get a full page back: someone will paste it into an email, and history restoration needs it.

htmx communicates with the server through headers, so the controller can tell an htmx request from a normal one, and the server can steer what the client does with the response.

Source: htmx — Reference, Request Headers

Source: htmx — Reference, Response Headers

Response headers are not processed on 3xx responses: the browser follows a redirect internally and htmx sees the headers of the final response. Use a 200 for responses whose headers must be honoured, and HX-Redirect or HX-Location instead of a 302 to move an htmx request somewhere else. This is also why Post/Redirect/Get is no longer needed for an htmx form: return the new fragment.

htmx swaps responses according to their HTTP status. The defaults of htmx.config.responseHandling are: 204 is not swapped and is not an error, 2xx and 3xx are swapped, 4xx and 5xx are not swapped and are errors (htmx:responseError is fired), and anything else is not swapped. A network failure fires htmx:sendError. The array can be replaced; each entry has a code (a regular expression), swap, error, ignoreTitle, select, target and swapOverride. For inline validation, the usual change is to swap 422 responses; the demo does it in the htmx-config meta tag shown above.

The add form of the demo then works like this. An invalid submission answers 422, retargets the response from the table to the form itself, and re-renders the form with the messages:

Source: htmx — Configuring Response Handling

In Chromium, submitting the empty title showed "must not be blank" next to both fields, the table kept its four rows, and the page still had exactly one #add-form (the outerHTML swap replaced it). Over curl the invalid POST answers (the message text follows the locale of the request):

The same flow without JavaScript is a normal form post: the controller sees no HX-Request header, renders the whole page with the errors (or redirects after a successful save). The delete answer is 200 with an empty body. A 204 No Content does not swap, even with a body, which is right for "do something, change nothing" (the pin button), and wrong for an outerHTML delete that should remove the row.

Source: htmx — Requests & Responses

For errors you want to handle with code, listen for htmx:responseError (a 4xx or 5xx that is not swapped), htmx:sendError (network) and htmx:timeout, or change the swap decision for one response in a htmx:beforeSwap listener (evt.detail.shouldSwap, evt.detail.isError, evt.detail.target). The response-targets extension does the same declaratively. The page Error Handling & Flash Messages covers the server-side half (error pages, @ControllerAdvice).

Every step of a request fires an event on the element, bubbling up the DOM, and each event is fired under two names: camel-case (htmx:afterSwap) and kebab-case (htmx:after-swap), so Alpine.js and the attribute-based hx-on handlers can use them. The ones needed most often:

Source: htmx — Events

Handlers: document.body.addEventListener(name, fn), htmx.on(name, fn), or inline with hx-on:<event> attributes. The hx-on attribute names are case-insensitive, so use the kebab-case event name (hx-on:htmx:after-request) or the shorthand hx-on::after-request for events that start with htmx:. In the handler this is the element and event is the event. The add form of the demo resets itself with hx-on::after-request="if (event.detail.successful) this.reset()". Attribute handlers need allowEval. htmx.logAll() logs every event and htmx.logger installs a custom logger; the browser console’s monitorEvents(element) shows what a DOM element fires.

The JavaScript API is the htmx global:

Source: htmx — JavaScript API

The page script above calls htmx.ajax from a click handler, and the result in Chromium was the tip text in #about-box:

htmx.onLoad is the right place to initialise anything that must be set up for the new nodes of every swap, such as Alpine components or web components; see Alpine.js & Web Components. In the demo it ran once for the initial document and again for each loaded fragment.

Source: htmx — Initialize a 3rd Party Library With Events

htmx is configured declaratively in a meta tag (preferred) or programmatically on htmx.config. The meta tag belongs in the head, before the script that loads htmx:

The options that matter most for a server-rendered application (htmx 2.0.11 defaults, from the reference):

Source: htmx — Configuration Options

With Spring Security’s default CSRF protection, a POST, PUT, PATCH or DELETE without the token is rejected. A th:action form that is submitted by htmx gets the token as the hidden _csrf input Thymeleaf adds to it (the request body of the add form in the browser run was _csrf=<token>&title=Solaris&author=Stanislaw%20Lem). An element that is not inside such a form (the hx-delete and hx-put buttons) has no hidden input, and th:hx-post does not add a token automatically. Send it as a header for every htmx request:

Do not send the token as a request parameter for hx-delete: htmx 2 puts the parameters of a DELETE in the URL, where the token would end up in access logs. The hx: Thymeleaf dialect of htmx-spring-boot-thymeleaf adds the header for you and is described on htmx with Spring Boot; the Spring Security side (CsrfToken, the SecurityFilterChain, an expired session) is on Spring Security Integration.

With the header removed on purpose (Playwright stripped X-CSRF-TOKEN from the pin request), the server rejected the request and htmx fired htmx:responseError with the status; in the scratch application it was 401 over HTTP Basic (the MockMvc test with a mock user saw 403), and with curl a POST without the token answered 401 too, while the same POST with -H "X-CSRF-TOKEN: $TOKEN" answered 200. If an ordinary form login is used the same failure is a 403.

Source: htmx — CSRF Prevention

htmx makes HTML more expressive, which means HTML injected into a page can now start requests. The rules:

Source: htmx — Security

htmx 2.0 is deliberately close to 1.x. The migration guide lists these changes:

Source: htmx — 1.x to 2.x Migration Guide

htmx 4.0.0 was published to npm on 2026-08-28 and is available only on the next tag; latest is still 2.0.11 (published 2026-09-22), and the htmx home page and this page’s examples pin 2.0.11. The documentation of htmx 4 is at https://four.htmx.org/docs/ and lists three major behaviour changes compared with htmx 2:

Event names were also standardised, htmx 4 uses fetch() instead of XMLHttpRequest, it ships an upgrade-check command-line tool (npx htmx.org@4.0.0 upgrade-check — ./path/to/project/root) and an htmx-2-compat extension. The Spring Boot library moves with it: htmx-spring-boot 6.0.0 targets htmx 4, is documented on the project’s main branch, and was not on Maven Central on 2026-10-08, so 5.2.0 is the version for htmx 2. A new application on Thymeleaf can start on htmx 2.0.11 today (everything on this page was run on it) and take on htmx 4 as a separate, deliberate upgrade once the library and the extensions you use are released for it. Re-check the dates above before relying on them: htmx 4 is the part of this page that is changing.

Source: htmx 4 — Documentation

Source: htmx — Documentation

The consulted edition of Modern frontends with htmx is v1.0.0 (2023, htmx 1.x). Its chapters 3 to 6 (starting with htmx, request and response headers, the TodoMVC project and out-of-band swaps) are still a good read for the concepts, but code written for htmx 1.x needs these corrections: extensions are separate files since htmx 2, the parameters of a DELETE go in the URL, and the old hx-on attribute became hx-on:. The book loads htmx from a version-less webjar path (/webjars/htmx.org/dist/htmx.min.js), while this page uses the versioned path that needs no extra dependency. The book’s htmx-spring-boot code uses the 3.x API; this section uses 5.2.0 (see htmx with Spring Boot). Taming Thymeleaf was written before htmx became part of the Thymeleaf story.