What Is HTMX? Hypermedia for Modern Web

Photo: Godfrey Atima / Pexels
HTMX is a small, dependency-free JavaScript library, about 14 kilobytes minified and gzipped, that lets ordinary HTML elements make network requests and swap page content without a build step, a virtual DOM, or a client-side framework. It was created by Carson Gross, first released as version 1.0.0 on November 24, 2020, and it grew out of an earlier project called intercooler.js that Gross started in 2013 (htmx on Wikipedia). This piece explains exactly how HTMX intercepts events, builds requests, and swaps DOM nodes, and where the architecture wins and loses against the JavaScript framework model most developers already know.
If terms like AJAX or hypermedia are new to you, our glossary has plain-language definitions worth keeping open in a tab while you read this. The reason HTMX keeps coming up in developer surveys and conference talks is not nostalgia. It is a direct response to a specific pain: teams that write a JSON API, then write a second program (a React or Vue app) whose entire job is turning that JSON back into HTML. HTMX asks a blunt question — what if the server just sent HTML in the first place? — and then builds a small, disciplined set of tools to make that answer practical for real applications, not just static pages.
What problem HTMX is actually solving
To understand HTMX, you have to understand the detour the web took to get here. In the 1990s and 2000s, almost every site worked the same way: a click or a form submission sent a request to a server, the server rendered a full HTML page, and the browser replaced everything on screen. This is the original hypermedia model the web was built on, sometimes called HATEOAS (hypermedia as the engine of application state) — a term coined by Roy Fielding in his 2000 doctoral dissertation on REST architecture. Build tooling is a separate concern; see what Vite is.
Then AJAX arrived in the mid-2000s, and single-page applications (SPAs) followed. Instead of full-page reloads, JavaScript in the browser would fetch JSON data and re-render parts of the page itself. This unlocked genuinely new experiences (think Gmail's inbox or Google Maps panning) but it came with a structural cost: the client now had to duplicate a huge amount of what the server already knew. Every SPA effectively contains two applications — a server that understands your data model, and a client that has to reconstruct a mirror image of that model in JavaScript to decide what to render.
That duplication is where a lot of frontend complexity actually comes from: state synchronization bugs, hydration mismatches, the entire category of "why does the UI show stale data" tickets. HTMX's bet is that for a large share of real applications — internal tools, admin panels, content sites, e-commerce catalogs, dashboards — that duplication is pure overhead. The server already has the data and already knows how to render it. HTMX's job is just to make the wire protocol for updating small pieces of a page as easy as a full-page navigation used to be.
Gross's own account, told in interviews on shows like Software Engineering Radio and Go Time, traces the project back to a practical annoyance: sorting a table with a couple thousand rows client-side in jQuery around 2013, when browser JavaScript engines were not fast enough to make that pleasant. That frustration led to intercooler.js, a jQuery plugin that let ordinary HTML attributes trigger AJAX calls. When jQuery itself became a liability rather than an asset, Gross rewrote the library from scratch without any dependency, and htmx was the result (SE Radio 671, Carson Gross on HTMX).
How HTMX actually works, attribute by attribute
HTMX extends HTML with a family of attributes prefixed hx-. Critically, these attributes work on any element, not just anchors and forms. A <div>, a <tr>, a <span> — any of them can issue a request and receive a swap.
<button hx-get="/users/42" hx-target="#user-card" hx-swap="innerHTML">
Load User
</button>
<div id="user-card"></div>
When a visitor clicks that button, HTMX intercepts the default click behavior, fires a GET request to /users/42, and — once the response arrives — inserts the returned HTML inside the element matching #user-card. No JSON parsing happens anywhere in this flow. No client-side templating engine runs. The response the server sends is already the exact HTML that ends up on screen.
What each core attribute does
hx-get,hx-post,hx-put,hx-patch,hx-delete— issue an AJAX request using that HTTP verb, sending the element's nearest enclosing form data (if any) plus any values set withhx-valsorhx-include.hx-trigger— defines the DOM event that fires the request. Defaults are sensible (clickfor buttons and links,submitfor forms,changefor inputs), but you can specify anything:keyup changed delay:500ms,every 2s,intersect once, or even chained events likeclick, keyup[key=='Enter'].hx-target— a CSS selector identifying which element in the page receives the response. Without it, the triggering element updates itself.hx-swap— controls how the response is inserted:innerHTML(default, replaces contents),outerHTML(replaces the whole element),beforebegin/afterbegin/beforeend/afterend(relative insertion points borrowed directly from the DOM's nativeinsertAdjacentHTMLAPI), ordelete(removes the target entirely, useful for delete confirmations).hx-push-url— updates the browser's address bar and history stack so the back and forward buttons behave correctly, without a full page load.hx-swap-oob("out of band") — lets a single response update multiple, non-adjacent parts of the page at once, by tagging fragments in the response with an id HTMX recognizes independent of the main target.hx-boost— the "escape hatch" attribute. Applied to a container (often<body>), it converts every normal link and form inside it into an AJAX request automatically, turning a fully classic multi-page app into something that feels like an SPA with zero extra markup.
What actually happens under the hood when you click
HTMX's request lifecycle runs through a documented, six-step event pipeline that fires custom DOM events at each stage: htmx:configRequest (you can mutate headers or parameters here), the actual fetch/XMLHttpRequest call, htmx:beforeSwap (you can veto or alter the swap based on response status), the DOM mutation itself, htmx:afterSwap, and finally htmx:afterSettle, which fires after any CSS transitions triggered by the swap have finished. Every one of these is a real, listenable browser event — document.body.addEventListener('htmx:afterSwap', ...) works exactly like any other JavaScript event listener, which is part of why HTMX composes cleanly with small amounts of imperative JavaScript when you genuinely need it.
This event-driven design is also what makes HTMX extensible without forking the library. Official and community extensions hook into these lifecycle events to add features like WebSocket and server-sent-event support, response caching, and client-side response validation, all without touching HTMX's core 14 kilobytes.
The hypermedia philosophy: why HATEOAS matters again
HTMX is not just a convenience library; it is an argument about architecture. The idea it revives, HATEOAS, holds that the server should tell the client what actions are currently possible by embedding links and forms directly in its responses, rather than the client independently knowing (and hard-coding) what the API supports.
Here is the analogy that makes this click: think of a JSON API as a vending machine with no labels. You already have to know the exact product code to press before you press it — the machine trusts you've memorized the whole catalog elsewhere. A hypermedia response is a vending machine with buttons that light up for what's actually available right now, and the labels change themselves when stock runs out. The client does not need a separate rulebook; the current state of the world is baked into what it's looking at. That is what "the server returns HTML with the next possible actions already in it" buys you in practice: a delete button that only appears in the response if the current user is actually allowed to delete that row, with no duplicate permission-check logic living in the frontend.
The second useful analogy is Locality of Behaviour, a design principle HTMX's own documentation names explicitly and treats as a first-class goal (htmx.org essay, Locality of Behaviour). Compare it to a kitchen where every appliance's manual lives in a separate room down the hall (the "separation of concerns" model most JavaScript frameworks encourage, splitting markup, styles, and behavior into different files) versus a kitchen where the instructions are printed right on each appliance. HTMX's hx-* attributes sit directly on the element they affect, so reading one line of markup tells you everything that element does. No hunting through a controllers/ folder or a hooks file to find the click handler; it's right there in the <button> tag.
Does HTMX replace the concept of a JSON API entirely?
No. HTMX changes what the browser-facing layer of your application returns, not necessarily your whole backend. Many HTMX-based systems still expose a JSON API for mobile apps, third-party integrations, or webhooks — they simply add a second, HTML-returning layer of routes specifically for the browser frontend, often reusing the same underlying data-access and business-logic code.
The hyperscript companion and how HTMX handles client state
HTMX deliberately does almost nothing beyond requests and swaps. For the small slice of behavior that genuinely needs to live entirely in the browser — toggling a class, showing a loading spinner, running a CSS transition before removal — Carson Gross built a companion scripting language called hyperscript, explicitly modeled on HyperCard's HyperTalk language from the late 1980s (htmx on Wikipedia).
Hyperscript reads close to plain English:
<div _="on click toggle .highlight on me">
Click to highlight
</div>
Hyperscript is optional. Most production HTMX codebases lean on a lightweight reactive library like Alpine.js instead, or plain vanilla JavaScript, for anything hyperscript doesn't cover cleanly. The point is not that hyperscript is mandatory — it is that HTMX's ecosystem treats "a little bit of client-side scripting, scoped to one element" as fine, rather than insisting everything route through a single global state store the way Redux-era React applications often did.
Why HTMX picked up real momentum
Developer sentiment data backs up the anecdotal buzz. HTMX's GitHub repository passed 47,000 stars by mid-2026, having added roughly 16,800 stars in 2024 alone — outpacing React's star growth that year in the JavaScript Rising Stars "front-end frameworks" category by more than 4,000 stars (devtoolswatch.com, HTMX vs React 2026). Weekly npm downloads for htmx.org run in the range of roughly 150,000-plus per week as of mid-2026 (npmjs.com/package/htmx.org). In 2023, htmx was selected for the inaugural cohort of the GitHub Accelerator program, which funds and mentors open source maintainers (htmx on Wikipedia).
The State of JavaScript 2025 survey, published in early 2026, placed htmx among the more admired tools in its libraries and frameworks sections, with usage rankings shifting enough that htmx and Alpine.js swapped positions relative to the prior year's survey (2025.stateofjs.com). None of this means HTMX is displacing React at the scale of the overall job market — React's installed base, tooling, and hiring pipeline remain far larger — but it does mean a meaningful and growing slice of professional developers are choosing it deliberately, not as a toy.
Common interface patterns that used to require real frontend engineering become one or two attributes with HTMX:
| Pattern | HTMX implementation | What used to be required |
|---|---|---|
| Live search / autocomplete | hx-get on keyup changed delay:500ms, target a results container |
Debounce logic, fetch wrapper, JSON parsing, results component, loading state |
| Infinite scroll | hx-trigger="revealed" on the last list item, hx-swap="afterend" |
Intersection Observer setup, pagination state, list re-render logic |
| Inline edit | Swap a <div> for a <form> on click, hx-put on submit, swap back |
Local edit-mode state, controlled form component, optimistic update handling |
| Modal dialogs | hx-get into a hidden modal container, hx-target="#modal" |
Portal/overlay component, focus trap, modal state in a global store |
| Lazy-loaded widgets | hx-trigger="load" or hx-trigger="intersect once" |
Code-splitting, dynamic import, loading skeleton component |
| Polling / live updates | hx-trigger="every 5s" |
setInterval, cleanup on unmount, state diffing |
Table: Common UI patterns and their HTMX vs. traditional-framework implementation cost.
None of the right-hand column items are impossible in React or Vue — they're all extremely well-trodden, in fact — but each one is a small amount of client-side application logic that HTMX simply doesn't require, because the "state" that logic would track already lives, correctly, on the server.
A complete, realistic example: deleting a todo item
Abstract descriptions only go so far. Here is a full "delete a todo" feature, front to back, the way it would actually ship.
The markup:
<li id="todo-7">
Buy groceries
<button hx-delete="/todos/7" hx-target="#todo-7" hx-swap="outerHTML"
hx-confirm="Delete this item?">
Delete
</button>
</li>
The server route, in Flask:
@app.delete("/todos/<int:id>")
def delete_todo(id):
db.session.delete(Todo.query.get_or_404(id))
db.session.commit()
return "", 200 # empty body; hx-swap=outerHTML removes the <li> entirely
That is the entire feature. hx-confirm triggers a native browser confirmation dialog before the request fires, no custom modal component required. When the server responds with an empty 200, hx-swap="outerHTML" replaces the whole <li> — including itself — with nothing, so the item simply disappears from the list. There is no Redux action, no reducer, no thunk, no optimistic update with a rollback path if the request fails, no client-side cache invalidation. If the request does fail, HTMX fires an htmx:responseError event you can listen for globally to show a toast notification, again without wiring that logic into every individual component.
Now compare the same feature's rough shape in a typical React + REST setup: a deleteTodo action creator, a reducer case removing the item from a normalized store, an async thunk (or a data-fetching library like TanStack Query) managing loading and error states, a component subscribing to that slice of state, and — if you want the UI to feel instant — optimistic removal from the list before the server confirms, plus rollback logic if the DELETE call 500s. Every piece of that is standard, well-understood React work. It is also, undeniably, more code, more state to keep synchronized, and more places a bug can hide.
When HTMX is genuinely the right call
HTMX earns its keep in a specific, common category of application:
- Content-heavy sites with pockets of interactivity — admin panels, internal dashboards, CRUD-heavy line-of-business apps, most e-commerce catalog and checkout flows.
- Teams that want one language across the stack. A Django or Rails team can ship interactive features without hiring a separate frontend specialist or maintaining a parallel JavaScript codebase.
- Projects where fast first paint and SEO matter. Since the server renders full HTML on every request by default, there's no hydration delay and no client-rendered blank-page flash for crawlers or slow connections to contend with.
- Anything you'd previously have reached for Django templates plus a sprinkle of jQuery to build. HTMX is, in a real sense, the spiritual and technical successor to exactly that stack.
- Teams already comfortable with server-rendered tooling. If your stack already leans on server-first rendering patterns, HTMX's instincts will feel familiar rather than foreign — see our broader web development coverage for related server-rendering approaches.
When HTMX is the wrong tool
The same properties that make HTMX simple make it a poor fit elsewhere:
- Rich, persistent client state. Design tools like Figma, collaborative editors like Google Docs, or project trackers like Linear need local undo stacks, optimistic multi-user conflict resolution, and offline-first behavior that genuinely lives on the device. HTMX's server-roundtrip model fights that requirement rather than supporting it.
- Unreliable networks. Every meaningful interaction is a network round trip. On a flaky mobile connection, an HTMX app can feel noticeably slower than a client-rendered SPA that already has the data it needs cached locally.
- Native-feeling gesture-driven interfaces. Complex drag interactions, physics-based animations, and page transitions synchronized across many elements are considerably easier to build with a component-oriented framework than by orchestrating server responses. See our htmx vs React 2026 deep dive for a fuller comparison of where each architecture wins.
- Organizations already deeply invested in a React-shaped hiring pipeline. If your component library, design system, testing tooling, and hiring funnel already assume React fluency, swapping to HTMX has real organizational switching cost that has nothing to do with the technology itself.
- APIs that must serve many independent, non-HTML client types identically. If your mobile app, third-party integrations, and web frontend all need to consume the exact same endpoint shape, a single JSON API is simpler to maintain than running parallel JSON and HTML-returning routes.
Trade-offs that don't disappear just because the code is shorter
HTMX genuinely reduces client-side complexity, but it does not eliminate complexity, it relocates it. Being honest about where it moves matters more than repeating the "40% less code" marketing framing that shows up in a lot of blog posts.
- More server round trips, by design. Every interaction that would have been handled by client-side state in a SPA now hits your server. This raises the importance of response caching, CDN edge caching for fragment responses, and database query performance under a higher request volume than a JSON-API backend serving the same features might see.
- Your server does more rendering work. Templating HTML on every request, including partial-page fragments, is more CPU-intensive per request than serving a static JSON payload and letting the client's already-downloaded JavaScript handle the rendering.
- Thinner error typing. You work with HTTP status codes and HTML fragments rather than a typed error schema. Teams used to strongly-typed API contracts (say, generated from an OpenAPI spec or GraphQL schema) will feel this loss of type safety at the network boundary.
- A smaller ecosystem, in absolute terms. Fewer prebuilt component libraries, fewer Stack Overflow answers per weird edge case, fewer job listings that name HTMX specifically. This is shrinking as adoption grows, but it is real today.
- Debugging tooling is less mature. React DevTools has over a decade of refinement for inspecting component trees and state. HTMX's introspection story leans more on browser devtools' Network tab and its own event system than on a purpose-built inspector.
For most CRUD-shaped applications, these trade-offs land as acceptable costs rather than deal-breakers. For applications with genuinely complex client-side interaction, they compound quickly.
What people get wrong about HTMX
"HTMX means no JavaScript." Not accurate. HTMX itself is written in JavaScript and requires JavaScript to be enabled in the browser. What HTMX eliminates is the need for you to hand-write JavaScript for common interaction patterns — the library does that work internally. You can still add custom JavaScript, hyperscript, or Alpine.js for anything HTMX's attributes don't cover.
"HTMX doesn't work without a specific backend." Also wrong. HTMX only requires a server that can return HTML, which is every backend that has ever existed. Documented integration guides exist for Node.js, Django, Flask, Ruby on Rails, ASP.NET, Java Spring, Clojure, PHP/Laravel, Go, and even Adobe ColdFusion. There is no HTMX-specific server framework to adopt.
"It's just jQuery with extra steps." The comparison is understandable given HTMX's direct lineage from intercooler.js, a jQuery plugin. But jQuery is a DOM-manipulation and utility library with no opinion about server communication patterns or hypermedia. HTMX is opinionated specifically about the request/response/swap lifecycle and is built around the HATEOAS constraint from REST theory, a design position jQuery never had.
"HTMX can't do SEO or fast pages, since it's 'just AJAX.'" This gets it backward. HTMX's default mode of operation is full server-side HTML rendering on the initial page load, identical to any classic multi-page site. Search engine crawlers see complete content immediately, with none of the client-side-rendering indexing complications that plagued early SPAs.
"Adopting HTMX means rewriting the whole frontend at once." In practice, HTMX is commonly adopted incrementally. Because hx-* attributes are just HTML attributes, you can add them to individual buttons or forms inside an otherwise-unchanged legacy server-rendered page, one feature at a time, without a big-bang rewrite.
Getting started, concretely
The entire installation is one script tag:
<script src="https://unpkg.com/htmx.org@2"></script>
There is no npm install required unless you want one for bundling purposes, no webpack configuration, no build step. Add hx-* attributes to existing HTML, and forms and links gain progressive enhancement immediately — meaning the underlying href or form action still works as a fallback if JavaScript fails to load, if you write the markup with that fallback in mind. HTMX's official documentation at htmx.org is short by framework standards and realistically readable end-to-end in an afternoon, which is itself a notable claim in an ecosystem where full framework documentation often runs to hundreds of pages.
Frequently asked questions
Q: Is HTMX a replacement for React? A: For a meaningful set of applications, yes, particularly content sites, admin dashboards, and CRUD-heavy line-of-business tools. For applications with complex, persistent client-side state, like design tools or real-time collaborative editors, React or a comparable component framework still tends to make more sense.
Q: Do I need a special backend for HTMX? A: No. HTMX works with any backend capable of returning HTML, which is effectively all of them. Documented integrations exist for Django, Flask, Rails, Node.js/Express, Go, ASP.NET, Java Spring, Laravel, Clojure, and more.
Q: How big is the HTMX library, exactly? A: Approximately 14 kilobytes minified and gzipped, before you write any application code, compared to roughly 45 to 47 kilobytes for React plus ReactDOM alone, also before app code.
Q: Does HTMX work if JavaScript is disabled in the browser?
A: HTMX itself requires JavaScript to run, since it is a JavaScript library. However, because it enhances existing HTML elements rather than replacing them, a well-built HTMX page can degrade gracefully: a button with hx-get can also carry a real href that works as a normal link if HTMX fails to load or JavaScript is off.
Q: Is HTMX good for SEO? A: Yes. Initial page loads are fully server-rendered HTML by default, so search engine crawlers see complete content immediately on first request, unlike client-rendered single-page applications that historically required extra crawler-side JavaScript execution to index properly.
Q: How does HTMX handle authentication and CSRF protection?
A: HTMX requests are standard HTTP requests, so cookies, authorization headers, and CSRF tokens all function exactly as they would for any other request. The hx-headers attribute lets you attach a CSRF token globally, typically on the <body> element, so every HTMX request on the page includes it automatically.
Q: Who created HTMX, and when? A: Carson Gross created HTMX as a rewrite of his earlier jQuery-dependent project, intercooler.js, which he started in 2013. HTMX version 1.0.0 was released on November 24, 2020, and version 2.0.0 followed on June 17, 2024, primarily dropping Internet Explorer support without changing the core API.
Q: What is hyperscript, and do I need it to use HTMX? A: Hyperscript is a companion scripting language, also created by Carson Gross and modeled on HyperCard's HyperTalk, designed for small, element-scoped client-side behaviors like toggling a class on click. It is entirely optional; many HTMX projects use Alpine.js instead, or skip both and write small amounts of vanilla JavaScript.
Q: Can I mix HTMX with a JavaScript framework like React or Vue? A: It's technically possible on the same page in different sections, since HTMX just manipulates the DOM it's told to target, but the two approaches manage state in fundamentally incompatible ways (server-owned versus client-owned), so most real projects choose one architecture rather than blending them extensively.
Q: Does using HTMX mean giving up on TypeScript-style safety? A: You lose typed contracts at the specific boundary of client-server communication, since responses are HTML rather than a typed JSON schema. Your server-side code, and any hyperscript or JavaScript you add, can still be as strongly typed as your language and tooling allow.
The takeaway
HTMX is not a rejection of everything JavaScript frameworks accomplished over the past decade; it is a narrower, more disciplined tool for a specific and very common job — applications where the server already owns the data and the interactivity needed is a series of partial-page updates, not a persistent client-side application state. The hx-* attributes, the event lifecycle, and the HATEOAS philosophy behind them all point at the same goal: let the server keep doing what it already does well, and stop asking the browser to rebuild a second copy of your application just to display it. For teams shipping CRUD apps, dashboards, and content sites, that trade genuinely reduces the amount of code that has to exist and the number of places a bug can hide. For teams building Figma-class interactive tools, it is the wrong trade, and HTMX's own documentation and creator do not pretend otherwise.
Read next:
Follow new articles
Add SciHub101 to your feed reader to see new science and technology stories.
About the Author
SciHub101 is an independent science and technology publication founded and edited by Buğra Sözeri, a software engineer and app developer based in Türkiye. AI tools assist with drafting and research. Source documentation in the existing archive is uneven, and articles are being reviewed and corrected. The Editorial Team byline identifies editorial responsibility; it does not certify specialist or independent human review. Where we compare products, anything built by our own team is labelled as such — see the editorial guidelines and About page for how corrections and disclosures work.
Related Articles

Bun vs Node.js vs Deno — 2026 Comparison
Bun is fastest, Node is bulletproof, Deno is the most secure. A 2026 comparison of the three major JavaScript runtimes with benchmarks and trade-offs.

What Is Vite? Modern Frontend Build Tool
Vite is a fast frontend build tool by Evan You using native ESM + esbuild for dev and Rollup for production. How it works and when to use it.

htmx vs React 2026 — When to Skip the JavaScript Framework
htmx vs React in 2026: how server-sent HTML fragments compare with client-rendered JavaScript, where each fits, and what a documented React-to-htmx port saved.

HTML, CSS, JavaScript Fundamentals — Web Dev Basics
Learn the three pillars of web development. HTML structure, CSS styling, JavaScript interactivity. Interactive examples.

Next.js vs React 2026 — Which Should You Learn First?
Next.js is a framework built on React, not a rival. What each does, Server Components, App vs Pages Router, and when to pick which, per the official docs.

React vs Vue vs Svelte 2026 — Which Framework to Learn?
Compare React, Vue, Svelte side-by-side. Job market demand, learning curve, salary, real-world usage. Which one to choose.