Confession: I tried htmx three times before any of it stuck. The first two times I read the docs, built a task list, decided I missed JSX, and went back to React. The third time someone explained the mental model in a single sentence and the whole thing finally clicked. The sentence: “In htmx, the server returns HTML fragments and the page swaps them in.” That’s it. That’s the whole framework. Everything else is plumbing.<\/p>\n
If you’re a React developer reading the official htmx docs<\/a> and finding yourself confused, this post is for you. I’m not going to convert you. I’m going to give you the bridge between “build a virtual DOM and reconcile” and “return HTML strings from your server.”<\/p>\n In React, your component tree lives in JavaScript memory. State changes trigger a render. The render produces a new virtual DOM. The reconciler diffs it against the previous one and updates the real DOM.<\/p>\n In htmx<\/a>, there is no component tree in the browser. There is a real DOM, period. When the user clicks a button or submits a form, htmx makes an HTTP request to your server. Your server returns an HTML fragment. Htmx swaps that fragment into a specific spot in the DOM. The page updates because the DOM was literally replaced, not because a reconciler decided to update it.<\/p>\n If that sounds primitive, it is. It is also exactly how the web worked for fifteen years before React existed, with the one important change that htmx lets you swap fragments<\/em> instead of full pages.<\/p>\n This is the canonical example because it’s the one that lets you stop writing React state for forms:<\/p>\n When the button is clicked, htmx GETs The form replaces the original div. On save, the server returns the display fragment again. No client-side state. No The React equivalent is roughly fifty lines once you include the optimistic update, the loading state, the error boundary, and the test for the loading state. The htmx version is fifteen lines of HTML across two templates.<\/p>\n For a slow-to-render section that I don’t want blocking the initial page:<\/p>\n The section loads the moment it scrolls into view. The server returns the rendered HTML. No Real-time dashboards that don’t actually need WebSockets:<\/p>\n When the server is satisfied the job is done, it returns the final status without the This is the pattern that took me longest to internalize. After a form submit, you often want to update two unrelated parts of the page (say, a sidebar count and the main table). React would do this with shared state. Htmx does it with The primary swap target updates as normal. Any element with Not every UI fits this model. The cases where I still reach for React:<\/p>\n The rule I use: if the user’s next action depends on a UI state the server cannot reasonably know, htmx fights you. Otherwise it gets out of the way.<\/p>\n When the unit of UI is an HTML fragment your backend returns, your server templates are doing real work. I’ve been writing more Filament-style admin code with PHP<\/a> because the loop got short again. Two minutes per change instead of ten because there’s no bundler to wait on.<\/p>\n I write my htmx backends in three languages depending on the project: Go with If I had to compress six months of opinion into a heuristic:<\/p>\n Use htmx for CRUD apps, dashboards that don’t need keystroke-level interactivity, internal tools, and anything where the user’s mental model is “submit a thing, see the new state.” Use React for editors, charts that respond to mouse moves, anything offline-capable, or anything where the design has been driven by a designer who assumes a JavaScript framework.<\/p>\nThe mental model in one paragraph<\/h2>\n
The four patterns I actually ship<\/h2>\n
1. Inline edit with
hx-get<\/code> and hx-post<\/code><\/h3>\n<!-- Display mode -->\n<div id="user-row-42">\n <span>Name: Jane Doe<\/span>\n <button hx-get="\/users\/42\/edit"\n hx-target="#user-row-42"\n hx-swap="outerHTML">\n Edit\n <\/button>\n<\/div>\n<\/code><\/pre>\n\/users\/42\/edit<\/code>. The server returns the edit form as an HTML fragment:<\/p>\n<!-- Edit mode (returned by \/users\/42\/edit) -->\n<form id="user-row-42"\n hx-post="\/users\/42"\n hx-target="this"\n hx-swap="outerHTML">\n <input name="name" value="Jane Doe">\n <button type="submit">Save<\/button>\n<\/form>\n<\/code><\/pre>\nuseState<\/code>, no useReducer<\/code>, no React Query cache to invalidate. Two endpoints and two HTML templates.<\/p>\n2. Lazy-loaded sections with
hx-trigger=\"intersect\"<\/code><\/h3>\n<div hx-get="\/dashboard\/revenue"\n hx-trigger="intersect once"\n hx-swap="outerHTML">\n <div class="skeleton">Loading revenue...<\/div>\n<\/div>\n<\/code><\/pre>\nuseEffect<\/code>, no IntersectionObserver<\/code> polyfill, no loading-state state machine.<\/p>\n3. Polling with
hx-trigger=\"every 5s\"<\/code><\/h3>\n<div hx-get="\/jobs\/123\/status"\n hx-trigger="every 5s"\n hx-swap="innerHTML">\n pending\n<\/div>\n<\/code><\/pre>\nhx-trigger<\/code> attribute, and polling stops. This is the pattern I reach for whenever someone says “we need real-time” and they actually mean “five-second freshness is fine.”<\/p>\n4. Out-of-band swaps for “update multiple regions”<\/h3>\n
hx-swap-oob<\/code>:<\/p>\n<!-- Server response to POST \/items -->\n<div id="item-list">\n <!-- updated list -->\n<\/div>\n<span id="item-count" hx-swap-oob="true">7<\/span>\n<\/code><\/pre>\nhx-swap-oob=\"true\"<\/code> in the response is also swapped into wherever its id<\/code> matches on the page. Two regions, one request, no shared state.<\/p>\nWhat htmx is bad at<\/h2>\n
\n
The part I underrated: server-side templating gets fun again<\/h2>\n
html\/template<\/code>, Laravel with Blade, and Hono with JSX. All three are fine. The framework matters less than the discipline of returning fragments instead of full pages.<\/p>\nWhen I reach for htmx vs React<\/h2>\n