Django HTMX

1.27.0 · active · verified Sun Apr 12

django-htmx is a Python package that provides extensions for integrating Django with htmx. It simplifies building dynamic and interactive web applications by offering middleware, template tags, and HTTP response utilities, allowing developers to leverage htmx's capabilities without writing extensive JavaScript. The library is actively maintained with a regular release cadence, ensuring compatibility with recent Django and Python versions.

Warnings

gotcha CSRF Token Handling for POST requests: HTMX requests do not automatically send Django's CSRF token, which is required for POST, PUT, and DELETE requests. Failure to include it will result in 403 Forbidden errors.
Fix: Add `hx-headers='{"x-csrftoken": "{{ csrf_token }}"}'` to your `<body>` tag or specific elements, or include a custom JavaScript to add the header to all htmx requests.
gotcha HTMX.org JavaScript Library is Separate: `django-htmx` provides Python utilities and template tags to *include* its own extension script, but it does NOT bundle or serve the core `htmx.org` JavaScript library itself. You must explicitly include `htmx.org` in your templates.
Fix: Include `htmx.org` via a CDN (`<script src="https://unpkg.com/htmx.org@latest"></script>`) or by downloading and serving it as a static file in your Django project.
gotcha `HtmxMiddleware` is practically essential: While technically optional, most of the core features like `request.htmx` (used to detect htmx requests and access htmx-specific headers) rely on `HtmxMiddleware` being added to your `MIDDLEWARE` setting.
Fix: Always include `'django_htmx.middleware.HtmxMiddleware'` in your `MIDDLEWARE` list in `settings.py` for full functionality.
gotcha Vary Headers for HTTP Caching: If your Django views render different HTML content for HTMX requests versus standard browser requests (using `if request.htmx:`), you must add `HX-Request` to the `Vary` header for proper HTTP caching behavior.
Fix: Use `@vary_on_headers('HX-Request')` decorator or manually set `response['Vary'] = 'HX-Request'` in your views that differentiate content based on `request.htmx`.
breaking Removal of old template tags and mixins in 1.0.0: `{% htmx_script %}` (for htmx.org), `HTMXViewMixin`, `{% htmx_include %}`, and `{% htmx_attrs %}` were removed in `django-htmx` version 1.0.0. This was a significant breaking change for users upgrading from pre-1.0.0 versions.
Fix: Update your templates to directly include `htmx.org` (as mentioned above) and use the current `{% django_htmx_script %}`. Refactor views to use `request.htmx` directly instead of `HTMXViewMixin`.
breaking Potential breaking changes in `htmx.org` 4.0+: While `django-htmx` is separate, the underlying `htmx.org` library is releasing major versions (e.g., 4.0), which may introduce breaking changes to its core API, extension system, or event handling, potentially impacting custom JavaScript or advanced integrations.
Fix: Consult the `htmx.org` migration guide (e.g., for `htmx.org` 2.0 to 4.0) and thoroughly test your application when upgrading the client-side `htmx.org` library to major versions. Pay attention to changes in the extension API.

Install

pip install django-htmx Install package

Imports

HtmxMiddleware
```
from django_htmx.middleware import HtmxMiddleware
```
Required to enable `request.htmx` and other htmx-specific request processing.
request.htmx
```
if request.htmx: ...
```
Attribute added to the `HttpRequest` object by `HtmxMiddleware`, used to detect htmx requests and access htmx-specific headers (e.g., `request.htmx.boosted`, `request.htmx.current_url_abs_path`).
django_htmx_script
```
{% load django_htmx %} {% django_htmx_script %}
```
Django template tag to include the `django-htmx` extension JavaScript, which provides debug error handling and other features.
HttpResponseClientRedirect
```
from django_htmx.http import HttpResponseClientRedirect
```
Custom Django `HttpResponse` class for triggering client-side redirects via the `HX-Redirect` header.
HttpResponseStopPolling
```
from django_htmx.http import HttpResponseStopPolling
```
Custom Django `HttpResponse` class for stopping htmx polling requests via the HTTP status code 286.

Quickstart

This quickstart demonstrates how to set up `django-htmx` and create a basic view that responds differently to HTMX requests. It includes necessary `settings.py` configurations, an example view using `request.htmx`, and a corresponding HTML template snippet. Remember to include the `htmx.org` JavaScript library (e.g., via CDN) and configure CSRF token handling for POST requests.

import os
from django.shortcuts import render
from django.http import HttpResponse

# settings.py additions
# INSTALLED_APPS = [
#     ...,
#     'django_htmx',
# ]
# MIDDLEWARE = [
#     ...,
#     'django_htmx.middleware.HtmxMiddleware',
# ]

def my_view(request):
    if request.htmx:
        # This branch handles HTMX requests
        return HttpResponse("<div>Updated content from HTMX!</div>")
    else:
        # This branch handles initial page load or regular requests
        context = {'initial_message': 'Click the button below to update!'}
        return render(request, 'my_template.html', context)

# my_template.html (within your templates directory, inheriting a base.html)
# Assuming base.html includes the htmx.org script and {% django_htmx_script %}
# and has <body hx-headers='{"x-csrftoken": "{{ csrf_token }}"}'>
#
# {% load django_htmx %}
# <!DOCTYPE html>
# <html lang="en">
# <head>
#     <meta charset="UTF-8">
#     <title>Django HTMX Demo</title>
#     <script src="https://unpkg.com/htmx.org@1.9.10"></script> <!-- or self-host -->
#     {% django_htmx_script %}
# </head>
# <body hx-headers='{"x-csrftoken": "{{ csrf_token }}"}'>
#     <div id="content">{{ initial_message }}</div>
#     <button hx-get="/my-htmx-view/" hx-target="#content" hx-swap="innerHTML">Load HTMX Content</button>
# </body>
# </html>

# urls.py addition (example)
# from django.urls import path
# from . import views
#
# urlpatterns = [
#     path('my-htmx-view/', views.my_view, name='my_htmx_view'),
# ]

view raw JSON →