I spent most of 2024 being quietly rude about htmx. Not loudly, I never wrote the post, but in my head it was filed under “things Twitter likes that don’t survive a real project.” Then last year I built an admin panel for a client, badly, in React, and spent three days debugging a stale cache in a table that displayed forty rows of data and had exactly one filter.<\/p>\n
Three days. Forty rows. I rebuilt that screen with htmx over a weekend and it has needed no maintenance since.<\/p>\n
So I was wrong, but not in the way htmx advocates usually want me to be wrong. Here’s where I actually land now, including the parts where I still reach for React and don’t apologise for it.<\/p>\n
htmx lets you put HTTP requests on HTML attributes and swap the response into the DOM. That’s the whole library. Your server returns HTML fragments instead of JSON, and there is no client-side model to keep in sync, because there is no client-side model.<\/p>\n
The React version of a “load comments when clicked” button:<\/p>\n
function Comments({ postId }) {\n const [comments, setComments] = useState(null);\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n\n async function load() {\n setLoading(true);\n try {\n const res = await fetch(`\/api\/posts\/${postId}\/comments`);\n if (!res.ok) throw new Error(res.statusText);\n setComments(await res.json());\n } catch (e) {\n setError(e);\n } finally {\n setLoading(false);\n }\n }\n\n if (error) return <p>Something broke.<\/p>;\n if (loading) return <Spinner \/>;\n if (!comments) return <button onClick={load}>Load comments<\/button>;\n return <ul>{comments.map(c => <li key={c.id}>{c.body}<\/li>)}<\/ul>;\n}\n<\/code><\/pre>\nThe htmx version:<\/p>\n
<button hx-get="\/posts\/42\/comments"\n hx-target="#comments"\n hx-swap="innerHTML">\n Load comments\n<\/button>\n<div id="comments"><\/div>\n<\/code><\/pre>\nAnd on the server, you render the same partial template you’d render anywhere else. No serialiser, no API contract, no second representation of a comment that has to stay in step with the first one.<\/p>\n
That last point is the actual argument, and it took me too long to hear it. The cost of a JSON API isn’t the endpoint. It’s that you now maintain two models of every object and a translation layer between them, forever.<\/p>\n
The rule I use to decide<\/h2>\n
Carson Gross, who wrote htmx, has an essay called When Should You Use Hypermedia?<\/a> and his framing is that apps like Google Sheets and Google Maps aren’t candidates, because they have large amounts of interdependent state and need to respond to mouse movement faster than a server round trip allows. Almost everything else is fair game.<\/p>\nMy version is blunter. I ask one question: does this screen need to stay correct while the user is offline or mid-gesture?<\/p>\n
Drag-and-drop reordering, a canvas, a rich text editor, a spreadsheet grid, an optimistic UI that must feel instant on a slow connection. Those need client state, and I’ll use React or Vue, and I won’t feel bad about it.<\/p>\n
A CRUD table, a form, a filter, a dashboard, an admin panel, a settings page, a checkout. Those need a server round trip anyway. Wrapping them in a framework that maintains a virtual DOM so it can re-render data that came from the server two seconds ago is work you’re doing for no one.<\/p>\n
Roughly eighty percent of the screens I’ve been paid to build fall in the second group. That number surprised me when I counted.<\/p>\n
htmx 4 is coming, and the reason is interesting<\/h2>\n
Gross said publicly there would never be an htmx 3. He then announced htmx 4<\/a>, on the grounds that he’d never said anything about a version four. I laughed harder at that than I should have.<\/p>\nThe joke is doing real work, though. The big change is replacing XMLHttpRequest<\/code> with fetch()<\/code>, which lets streaming responses and server-sent events move into core rather than living as extensions, and lets DOM morphing come along too.<\/p>\nThe other change is the one I care about more. In htmx 2, attribute inheritance is implicit. A hx-target<\/code> on a parent quietly applies to every child. Gross calls this the biggest mistake in htmx 1 and 2, says he was inspired by CSS, and says the results were “powerful and maddening”, which is the most accurate description of CSS inheritance I’ve read.<\/p>\nIn htmx 4, inheritance is explicit:<\/p>\n
<div hx-target:inherited="#output">\n <button hx-post="\/up">Like<\/button>\n <button hx-post="\/down">Dislike<\/button>\n<\/div>\n<output id="output">Pick a button...<\/output>\n<\/code><\/pre>\nWithout that :inherited<\/code> modifier, the buttons don’t pick up the target. You can turn old behaviour back on with a config flag if you need to.<\/p>\nHistory handling changes too: htmx 4 stops snapshotting the DOM into local storage and just re-requests the content instead. Slower on paper. Correct in practice, because DOM snapshots break the moment a third-party script touches the page, and the standard advice for history bugs in htmx 2 was already “turn the cache off.”<\/p>\n
If you’re on htmx 2 and nervous: the project page says 2.0 will be supported in perpetuity<\/a> and 4.0 rolls out over multiple years, with 4.x sitting on next<\/code> for a long time before it becomes latest<\/code>. There’s no cliff here.<\/p>\nThe caching thing nobody mentions<\/h2>\n
Here’s a practical difference that took me a while to notice and that I now bring up early.<\/p>\n
When your server returns JSON, your HTML shell is static and cacheable at the edge, and the data arrives separately. When your server returns HTML fragments, the fragment is the response, and its cacheability depends entirely on whether that fragment is personalised. A comments list is probably cacheable. A comments list with an “edit” button that only appears for the author is not, at least not without varying on something.<\/p>\n
This isn’t an argument against htmx. It’s an argument for deciding, per fragment, whether it’s public or personal, and being disciplined about not mixing the two in one response. In practice I split them: the public list is one endpoint, the per-user controls are a small out-of-band swap. It’s slightly more endpoints and dramatically simpler cache headers.<\/p>\n
The related point is that your server rendering has to be quick, because now it’s on the critical path of every interaction rather than just the initial page load. A template render that takes 80ms was invisible when it happened once. At 80ms per filter change, users notice. If your framework has a template cache, turn it on before you benchmark anything and blame htmx for a number your renderer produced.<\/p>\n
Where htmx bit me<\/h2>\n
It isn’t free. Three things I hit on real work.<\/p>\n
Your templates fragment. You end up with a lot of small partials, and if your template language has no good story for composing them, you get a directory of forty files named things like _row_edit_mode.html<\/code>. That’s manageable. It’s also not the tidy story the demos tell.<\/p>\nForm validation gets chatty. Every keystroke-level validation is a request. You can debounce with hx-trigger=\"keyup changed delay:500ms\"<\/code>, and you should, but it’s a decision you now have to make on every field rather than something the client framework handled for free.<\/p>\nAnd you will still write JavaScript. Not much, and the htmx docs point you at Alpine for it, but the “zero JavaScript” framing is marketing. Budget for a little.<\/p>\n
The one I underestimated most, though, was testing. With a JSON API you can test the endpoint’s contract independently of how anything renders it, and that separation is genuinely useful when the frontend and backend change at different speeds. With HTML fragments, your endpoint test is asserting on markup, which is more brittle and couples your test suite to your templates. There are reasonable answers, mostly asserting on a handful of stable selectors rather than whole strings, but “reasonable answers” is doing real work in that sentence. If you have a mobile client consuming the same API, none of this applies, because you needed the JSON anyway and htmx was never the right call.<\/p>\n
There’s also a team dimension I’ve stopped pretending doesn’t matter. If your frontend and backend people are different humans with different repos, HTML fragments put the rendering decision on the backend side of that line, and some teams are organised in a way that makes this genuinely painful. The technology is fine. The org chart might not be.<\/p>\n
How this sits next to server actions<\/h2>\n
If you’re in the Next.js world, none of this is unfamiliar. Server actions are chasing the same idea from the other direction: keep the mutation on the server, stop maintaining an API layer whose only client is your own frontend. I wrote about the two rules I learned the hard way with server actions<\/a>, and the underlying instinct is identical.<\/p>\nThe difference is what you ship to the browser. Server actions still hand the client a React runtime. htmx hands it about 14kb and some attributes. Which trade is right depends on whether the rest of your app needs the runtime anyway. If it does, use the thing you already have. If your app is mostly forms and tables and you’re pulling in React solely to render them, that’s the case where I’d genuinely stop and reconsider.<\/p>\n
Try this one thing<\/h2>\n
Pick the dullest screen in your current project. The settings page, the one nobody demos. Rebuild it with htmx from a CDN script tag and your existing server templates, in one sitting, without deleting anything.<\/p>\n
If it takes longer than an afternoon, your server-side rendering story is the problem, not htmx, and that’s useful information too. If it takes an hour, you’ve learned something about how much framework your dull screens have been carrying. Most of the client work I take on<\/a> has at least three screens like this, and they’re usually the ones generating support tickets.<\/p>\n","protected":false},"excerpt":{"rendered":"Where htmx earns its place, where I still reach for React, what htmx 4 changes with fetch and explicit inheritance, and the costs the demos leave out.<\/p>\n","protected":false},"author":2,"featured_media":596,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Where htmx earns its place, where I still reach for React, what htmx 4 changes with fetch and explicit inheritance, and the costs the demos leave out.","rank_math_focus_keyword":"htmx","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[138,35],"tags":[38,193,650,41,39],"class_list":["post-597","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-frontend","category-web-development","tag-frontend","tag-htmx","tag-hypermedia","tag-react","tag-web-development"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/597","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=597"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/597\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/596"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=597"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=597"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=597"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}