HTMX brings SPA-feel interactions back to server-rendered Django: inline forms, live validation, infinite scroll, modals, and partial updates — all from regular Django views returning HTML fragments. The full pattern with CSRF and SSE.
The modern frontend has grown enormously complex: a separate single-page-app framework, a build pipeline, an API layer, client-side state management, and a duplication of logic across the client/server boundary — all to add some interactivity to pages. HTMX offers a different path. It lets you build dynamic, interactive interfaces while keeping your logic on the server in Django, returning HTML instead of JSON, and writing little to no JavaScript. This tutorial covers HTMX with Django: how it works, the patterns, and when it is the right tool.
Building a React or Vue frontend for a Django app means running two applications: the Django backend exposing a JSON API, and the JavaScript frontend consuming it. You duplicate models and validation across both, manage client-side state, maintain a build toolchain, and reason about a network boundary in the middle of every feature. For genuinely app-like products this is justified, but for the large category of sites that are mostly server-rendered pages with pockets of interactivity, it is enormous overhead for the benefit. HTMX exists for exactly that category — letting you add the interactivity without adopting the whole SPA architecture and its permanent complexity tax.
HTMX is a small JavaScript library you include once, and from then on you add interactivity through HTML attributes rather than writing code. An attribute on an element tells it to make an HTTP request on some event, and to swap the returned HTML into a target element on the page.
<button hx-get="/load-more/" hx-target="#list" hx-swap="beforeend">
Load more
</button>
Clicking this button issues a GET to /load-more/ and appends the returned HTML fragment to the list. No JSON, no client-side rendering, no JavaScript — the server returns ready HTML and HTMX places it. That is the entire model: HTML over the wire, swapped into the DOM, driven by attributes.
The conceptual shift at the heart of HTMX is returning HTML instead of JSON. In a SPA, the server sends data and the client renders it into HTML; with HTMX, the server renders the HTML and sends it ready to display. This collapses the duplication: there is one place that knows how to render a thing — your Django templates — instead of rendering logic split between server serializers and client components. Your views return template fragments, your business logic stays in Python, and the browser simply places the HTML where you tell it. Embracing "HTML over the wire" is what eliminates the API layer and the client-side rendering, and it is why HTMX apps are so much simpler.
Download the minified HTMX 2.x build once, commit it under your static files, and load it from the base template. Self-hosting keeps your Content Security Policy tight and makes upgrades a reviewed commit.
{# templates/base.html #}
{% load static %}
<script src="{% static 'vendor/htmx.min.js' %}" defer></script>
...
<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
The hx-headers attribute on <body> is the most important line for Django. HTMX attributes are inherited, so every request issued anywhere on the page carries the X-CSRFToken header and CsrfViewMiddleware accepts POST, PUT, PATCH and DELETE from buttons that are not inside a form. Forget it and every non-GET request fails with a 403 that HTMX does not swap by default — the button simply appears to do nothing. If you changed CSRF_HEADER_NAME, match it here.
The small django-htmx package is worth adding to most projects. Its django_htmx.middleware.HtmxMiddleware attaches a request.htmx object that is truthy for HTMX requests and exposes the other headers as attributes; reading request.headers directly works too.
HTMX views are ordinary Django views that return rendered HTML fragments rather than full pages. A request from HTMX hits a normal URL and view, which renders a small template — a list item, an updated form, a partial — and returns it. You often detect HTMX requests (via a request header HTMX sends) to decide whether to return a full page or just a fragment, so the same view serves both a normal navigation and an HTMX swap. This keeps everything in familiar Django territory: URLs, views, templates, the ORM. There is no new paradigm to learn on the backend, just the practice of returning focused fragments alongside full pages.
The canonical pattern: a list view that returns the full page on normal navigation and only the rows when HTMX asks. HTMX sends HX-Request: true on every request it makes.
from django.utils.cache import patch_vary_headers
@login_required
def task_list(request):
tasks = Task.objects.filter(owner=request.user).select_related("project")
page = Paginator(tasks.order_by("-created_at"), 25).get_page(request.GET.get("page"))
htmx = request.headers.get("HX-Request") == "true"
boosted = request.headers.get("HX-Boosted") == "true"
template = "tasks/_task_rows.html" if htmx and not boosted else "tasks/task_list.html"
response = render(request, template, {"page": page})
patch_vary_headers(response, ["HX-Request"])
return response
The patch_vary_headers call is not decoration. The same URL now returns two different bodies depending on a request header, and every cache in between must know that. Without Vary: HX-Request, a classic bug appears: the user navigates away, presses Back, and the browser serves the cached fragment as the whole page, an unstyled list with no layout. The HX-Boosted check matters too: hx-boost navigations also send HX-Request: true but expect a full document.
The natural way to structure HTMX templates is around small, reusable partials — a template for a single list row, a card, a form — that can be rendered both within a full page and on their own in response to an HTMX request. When the full page loads, it includes these partials; when an HTMX interaction occurs, the view renders just the relevant partial and returns it. This partial-oriented structure is the backbone of an HTMX codebase, and it keeps rendering DRY: the same fragment template produces the same HTML whether it is part of an initial page load or an interactive update, so what the user sees stays consistent.
HTMX gives precise control over where returned HTML goes and how it is inserted. The hx-target attribute names the element to update, and hx-swap controls the insertion — replace the target's contents, replace the element itself, append or prepend, and so on. This lets you express interactions declaratively: append a new item to a list, replace a form with a success message, update a counter in place. The combination of targeting and swap strategy covers the vast majority of UI updates a typical app needs, all specified in HTML attributes without a line of JavaScript. Understanding the swap options is most of what it takes to build fluent HTMX interfaces.
hx-swap value | Effect | Typical use |
|---|---|---|
innerHTML (default) | Replaces the target's children | Refreshing a results container |
outerHTML | Replaces the target element itself | Swapping a row for its edit form and back |
beforeend / afterbegin | Appends / prepends inside the target | Load more, adding a new item |
afterend | Inserts after the target as a sibling | Infinite scroll from the last row |
delete | Removes the target | Deleting a row |
none | No main swap; headers and out-of-band content still apply | Actions that only emit events |
Targets also accept relative selectors — hx-target="closest tr", hx-target="this" — so one row template works without knowing its own id.
HTMX makes form handling elegant because validation lives where it belongs — on the server, in your Django forms. A form submits via HTMX, the view validates it with the normal Django form machinery, and on error it returns the form partial re-rendered with the errors, which HTMX swaps in place; on success it returns the next state. There is no client-side validation logic to duplicate and keep in sync with the server's rules. This is a genuine simplification over the SPA approach, where validation is often implemented twice. Your single source of truth for what is valid stays in Python, and the user still gets inline, dynamic error feedback without a full page reload.
<form hx-post="{% url 'tasks:create' %}" hx-target="this"
hx-swap="outerHTML" hx-disabled-elt="find button">
{% csrf_token %}
{{ form }}
<button type="submit">Add task</button>
</form>
hx-disabled-elt disables the button while the request is in flight, preventing the double submit that creates duplicate rows on slow connections. Keep {% csrf_token %} anyway: it is what lets the same form work as a plain POST.
By default HTMX swaps 2xx responses and does not swap 4xx or 5xx. So the view must return the re-rendered invalid form with status 200; a 422 would be silently discarded. If you want semantically correct 422s, HTMX 2's htmx.config.responseHandling lets you add a rule that swaps them, or an htmx:beforeSwap listener can set event.detail.shouldSwap = true for chosen statuses. Pick one convention project-wide, and add a global htmx:responseError / htmx:sendError listener that shows a "please retry" message, so real failures are never invisible.
A handful of patterns cover most interactive needs, and HTMX expresses them concisely. Live search triggers a request as the user types (with a small delay), and the view returns matching results that replace the results area. Infinite scroll loads more items when the user reaches the bottom, appending them. Inline editing swaps a display element for an edit form and back. Deleting an item removes its row. Each of these — which would be a meaningful chunk of JavaScript in a SPA — is a few attributes plus a normal Django view returning a fragment. The expressiveness on common interactions is where HTMX's productivity advantage is most visible.
<input type="search" name="q" hx-get="{% url 'tasks:list' %}"
hx-trigger="input changed delay:300ms, search"
hx-target="#task-rows" hx-sync="this:replace" hx-push-url="true">
delay:300ms debounces typing; changed skips keys that do not alter the value; search fires when the browser's clear button empties the field. hx-sync="this:replace" aborts an in-flight request when a new one starts, fixing the race where a slow response for "ta" lands after the one for "task" and overwrites the correct results. hx-push-url makes results shareable — which works only because the view renders a full page for a normal GET.
For infinite scroll, put hx-get="?page={{ page.next_page_number }}" hx-trigger="revealed" hx-swap="afterend" on the last row when page.has_next. Remember to carry the current query into that URL or page two silently drops the filter, and prefer keyset pagination (filter(pk__lt=last_id)) over deep OFFSETs on large, busy tables.
HTMX handles server-driven interactions, but some interactivity is purely client-side — a dropdown toggle, a modal, a bit of animation — and does not need a server round trip. For these, a tiny sprinkle of JavaScript, often via a minimal library like Alpine.js, complements HTMX nicely: HTMX for anything involving the server, Alpine for local UI state. This pairing covers the gap without dragging in a full framework. The honest position is that HTMX is not a total replacement for JavaScript; it replaces the architecture of a SPA for server-driven interactivity, while light client-only behavior is still best done with a small amount of JavaScript. Knowing the division keeps your stack minimal.
A defining property of the HTMX approach is that application state lives on the server, not in the client. There is no client-side store to manage, synchronize, or debug — the server is the source of truth, and each interaction fetches the current rendered state. This eliminates an entire class of bugs around client/server state divergence that plagues SPAs, where the client's idea of the world can drift from the server's. The tradeoff is a server round trip for interactions, which is fine for most apps but matters for things needing instant local feedback. For the many applications where server-authoritative state is natural, removing client state management is a large simplification.
HTMX's performance profile differs from a SPA's. Each interaction is a server request returning HTML, so you depend on fast server responses and benefit from all the server-side performance work — efficient queries, caching, quick template rendering. The upside is a tiny client payload (no megabytes of framework JavaScript) and fast initial loads, which is great for perceived performance and for users on slower devices or connections. The consideration is that highly interactive, latency-sensitive features may feel better with local rendering. For typical content-and-forms applications, HTMX often delivers better real-world performance than a heavy SPA precisely because the client stays light, while the server work is the same work you would optimize anyway.
HTMX shines for server-rendered applications with pockets of interactivity: content sites, dashboards, admin tools, CRUD apps, most business software. It lets a Django team build dynamic interfaces without a separate frontend stack, staying productive in one language and one codebase. It is the wrong choice for genuinely app-like products with heavy, complex client-side interactivity — rich text editors, real-time collaborative canvases, offline-first apps — where a full frontend framework's capabilities are genuinely needed. The judgment is honest self-assessment of how app-like your product really is. A great many projects that reach for React do not need it, and HTMX serves them better; a few genuinely do, and should use it.
Sometimes a single interaction needs to update several parts of the page at once — adding an item to a cart should update both the cart list and the header count. HTMX handles this with out-of-band swaps: the response can include extra fragments marked to update elements elsewhere on the page, beyond the main target. This lets one request refresh multiple independent regions, which would otherwise require either multiple requests or client-side coordination. Out-of-band swaps are the answer to the common "but I need to update two things" objection to server-driven UI, keeping even multi-region updates within HTMX's simple request-returns-HTML model rather than forcing a return to client-side state.
{# tasks/_task_created.html: main swap plus two out-of-band updates #}
{% include "tasks/_task_form.html" %}
<tbody hx-swap-oob="afterbegin:#task-rows">{% include "tasks/_task_row.html" %}</tbody>
<span id="task-count" hx-swap-oob="true">{{ task_count }}</span>
hx-swap-oob="true" replaces the element with the same id; the strategy:selector form inserts the element's children, which is how you prepend a row. Wrap rows in a <tbody>: a bare <tr> outside table context can be dropped by the HTML parser. Beyond two or three OOB targets, a view is coupled to regions it does not own; emit an event instead and let each region refresh itself.
HTMX is event-driven, and it offers rich control over what triggers requests and how the page reacts. You can trigger requests on a wide range of events, debounce or throttle them, and respond to custom events that the server signals back through response headers — so a server action can tell the page to refresh some other component. This event model lets components coordinate without bespoke JavaScript: one action can cause another part of the page to update by emitting an event the other listens for. Understanding HTMX's triggers and events is what lets you build genuinely interactive, coordinated interfaces declaratively, going well beyond simple click-to-load patterns.
# view: announce what happened
response["HX-Trigger"] = json.dumps({"tasksChanged": None})
{# template: any widget can listen #}
<div hx-get="{% url 'tasks:stats' %}" hx-trigger="load, tasksChanged from:body"></div>
Events from HX-Trigger are dispatched on the requesting element and bubble, hence from:body. The most useful headers:
| Header | Direction | Purpose |
|---|---|---|
HX-Request, HX-Boosted | Request | Is this HTMX, and is it a boosted navigation? |
HX-Target, HX-Current-URL | Request | Target element id; the browser's current URL |
HX-Trigger | Response | Dispatch client-side events |
HX-Redirect, HX-Refresh | Response | Full-page redirect or reload |
HX-Retarget, HX-Reswap | Response | Override target and swap for this response |
HX-Push-Url | Response | Update the address bar from the server |
HX-Retarget and HX-Reswap cleanly express "on success replace the row, on error show the form elsewhere": the element declares the success case and the view overrides only on failure.
A real strength of the HTMX approach is that it builds naturally on working HTML. Because interactions are driven by attributes on standard elements that already function as links and forms, an HTMX app can degrade gracefully — the underlying actions still work as ordinary page navigations even where the enhanced behavior does not apply. This progressive-enhancement posture, where the server-rendered HTML is the foundation and HTMX layers interactivity on top, produces interfaces that are inherently more robust than a JavaScript app that shows a blank page if its scripts fail to load. Designing with this resilience in mind yields applications that are fast, accessible, and dependable by default.
Testing an HTMX app is refreshingly straightforward precisely because the logic lives on the server. Your views return HTML fragments, so you test them with Django's ordinary view and template tests — assert that the right fragment is returned for a given request, that forms validate correctly, that the HTML contains what it should. There is no client-side state machine to test, no separate JavaScript test suite to maintain, no API contract to verify between two codebases. This testability is a direct consequence of keeping everything in Django, and it is part of HTMX's broader appeal: by avoiding the SPA architecture, you avoid much of its testing complexity along with it.
Django's test client accepts a headers argument, so simulating an HTMX request is one keyword. Test both response shapes and the headers your front end depends on:
class TaskListTests(TestCase):
def test_htmx_gets_fragment_only(self):
self.client.force_login(self.user)
r = self.client.get("/tasks/", headers={"HX-Request": "true"})
self.assertTemplateUsed(r, "tasks/_task_rows.html")
self.assertTemplateNotUsed(r, "base.html")
self.assertIn("HX-Request", r["Vary"])
def test_complete_emits_event(self):
self.client.force_login(self.user)
r = self.client.post(f"/tasks/{self.task.pk}/complete/",
headers={"HX-Request": "true"})
self.assertEqual(r.status_code, 200)
self.assertIn("tasksChanged", r["HX-Trigger"])
Keep a handful of browser tests (Playwright or Selenium via StaticLiveServerTestCase) for the flows where attribute wiring matters — a typo in hx-target passes every view test.
Most HTMX bugs fall into a small set of symptoms. Open the browser's network tab first: it tells you whether a request fired, what status came back, and what HTML was returned.
| Symptom | Likely cause | Fix |
|---|---|---|
| Button does nothing, network shows 403 | Missing CSRF header | Add hx-headers with X-CSRFToken on <body> |
| Form errors never appear | View returns 4xx, which HTMX does not swap | Return 200, or configure swapping for 422 |
| Back button shows an unstyled fragment | Missing Vary: HX-Request | patch_vary_headers(response, ["HX-Request"]) |
| Login page rendered inside a table cell | Session expired; login_required redirect followed by the XHR | Middleware that returns HX-Redirect to the login URL for HTMX requests |
| Whole page nested inside a div | View returned the full template to an HTMX request | Check the HX-Request / HX-Boosted branching |
| Newly swapped content does not respond | Third-party widget initialized only on page load | Initialize in an htmx:load listener |
| Stale or out-of-order search results | Racing requests | hx-sync="this:replace" |
The expired-session row only appears in production, after users leave a tab open overnight: the browser follows the redirect transparently, so HTMX swaps the login page wherever the target was. A short middleware that turns such redirects into an empty response with HX-Redirect fixes it. For deeper debugging, htmx.logAll() in the console logs every HTMX event.
Server-rendered HTML keeps you on Django's well-trodden security path, but a few HTMX-specific points need attention:
get_object_or_404(Task, pk=pk, owner=request.user)) and apply login_required or permission checks to every partial view.hx-* attributes in inserted HTML, so unescaped user input could carry live HTMX attributes as well as script. Autoescaping prevents both; audit any |safe or mark_safe in partials.htmx.config.selfRequestsOnly to true, restricting requests to your own origin; keep it. Setting htmx.config.allowEval to false disables features that evaluate strings as code, which helps under a strict Content Security Policy.hx-post, hx-patch or hx-delete with require_http_methods, never behind hx-get, so CSRF protection applies.HTMX offers a compelling alternative to the SPA architecture for the large category of applications that are server-rendered with pockets of interactivity. By driving interactions through HTML attributes and returning HTML fragments instead of JSON, it eliminates the separate frontend framework, the API layer, the duplicated logic, and the client-side state management — keeping everything in Django, in Python, in one codebase. Build around small partial templates rendered both in full pages and as HTMX responses, keep validation in Django forms, and use targeting and swap strategies to express updates declaratively. Reach for a sprinkle of Alpine.js for purely client-side behavior, lean on server-side performance work since each interaction is a request, and enjoy the simplification of server-authoritative state. Choose HTMX when your product is mostly pages with interactivity, and a full framework only when it is genuinely app-like — and you may find, as many teams have, that you needed far less frontend complexity than you thought.