HTMX Patterns for Django
Core Philosophy
- Server renders HTML fragments, not JSON
- Partial templates (
_partial.html) for HTMX responses - Progressive enhancement — pages work without JS, HTMX enhances UX
- Minimal client-side complexity — let the server do the heavy lifting
HTMX Detection in Views
With django-htmx middleware installed, use request.htmx:
python1def my_view(request): 2 context = {...} 3 if request.htmx: 4 return render(request, "app/_partial.html", context) 5 return render(request, "app/full_page.html", context)
Form Handling Pattern
python1def create_view(request): 2 if request.method == "POST": 3 form = MyForm(request.POST) 4 if form.is_valid(): 5 obj = form.save() 6 if request.htmx: 7 return render(request, "app/_item.html", {"item": obj}) 8 return redirect("app:list") 9 # Return form WITH errors for HTMX 10 if request.htmx: 11 return render(request, "app/_form.html", {"form": form}) 12 else: 13 form = MyForm() 14 return render(request, "app/create.html", {"form": form})
Template Organization
- Partials:
_partial.html(underscore prefix) — HTML fragments only - Full pages:
page.html— extendsbase.html, includes partials - Each partial = one logical UI component
CSRF Configuration
Add to <body> tag in base template — all HTMX requests include it automatically:
html1<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
Response Headers
| Header | Purpose | Example |
|---|---|---|
HX-Trigger | Trigger client-side events | response["HX-Trigger"] = "applicationCreated" |
HX-Redirect | Client-side redirect | response["HX-Redirect"] = reverse("app:detail", args=[obj.pk]) |
HX-Retarget | Override target from server | response["HX-Retarget"] = "#main" |
HX-Refresh | Force full page refresh | response["HX-Refresh"] = "true" |
UX Requirements
- Always use
hx-indicatorfor loading states - Always use
hx-disabled-elt="this"to prevent double submissions - Always return form errors in partial templates on validation failure
- Always provide feedback via Django messages or response content
Common Pitfalls
- Missing loading indicators — users click multiple times
- Returning full pages instead of partials for HTMX requests
- Not handling form errors — only handling the success case
- N+1 queries — HTMX views need
select_related()/prefetch_related()too
