Django class-based views, tailored for htmx
Project description
Django Class Based Views for HTMX
django-htmx-cbv provides HTMX-friendly mixins and views for common Django class-based view workflows.
Requirements
- Python 3.14+
- Django 6.0+
- django-htmx
This package assumes Django 6.0 template partial support.
It does not require django-template-partials.
Installation
Install the package and django-htmx:
pip install django-htmx-cbv django-htmx
Or with Poetry:
poetry add django-htmx-cbv django-htmx
Django setup
Add the app to INSTALLED_APPS:
INSTALLED_APPS = [
# ...
"django_htmx_cbv",
]
Add middleware in this order:
MIDDLEWARE = [
# Django middleware...
"django_htmx.middleware.HtmxMiddleware",
"django_htmx_cbv.middleware.HtmxPartialTemplateMiddleware",
"django_htmx_cbv.middleware.HtmxVaryMiddleware",
"django_htmx_cbv.middleware.HtmxMessageMiddleware",
"django_htmx_cbv.middleware.HttpVerbViewMiddleware",
# Other middleware...
]
Notes:
django_htmx.middleware.HtmxMiddlewaremust run before thedjango_htmx_cbvmiddleware.HtmxMessageMiddlewaremust come after Django'sMessageMiddleware.HttpVerbViewMiddlewareshould come after Django'sCsrfViewMiddleware.
The package registers a Django system check for the HtmxMiddleware dependency/order.
Template partials
This library expects Django 6.0 partial syntax:
<!doctype html>
<html lang="en">
<body>
{% include "messages.html" %}
{% partialdef main %}
<main>
<h1>Example</h1>
{% partialdef content %}
<div id="content">Hello</div>
{% endpartialdef content %}
</main>
{% endpartialdef main %}
</body>
</html>
For HTMX requests, HtmxPartialTemplateMiddleware rewrites template names to template.html#partial_name.
Partial resolution follows this order:
HX-RetargetHX-Partial-Namerequest.htmx.targetDEFAULT_PARTIAL_NAMEsetting, which defaults to"main"
Request conventions
HttpVerbViewMiddleware adds two request attributes:
request.QUERY: URL parameters as aQueryDictrequest.BODY: request body data as aQueryDict
For PUT and PATCH, the middleware supports:
application/x-www-form-urlencodedmultipart/form-data
This makes it possible for form-oriented CBVs to treat non-POST verbs more like normal Django form submissions.
View conventions
The library is intentionally opinionated.
- Plain
TemplateView,DetailView, andListViewalready work with the middleware in this package. Use Django's stock render-only CBVs unless the view itself needs HTMX-aware response logic. HtmxTemplateResponseMixinis the reusable view-level abstraction for custom CBVs that want to render inline for HTMX requests.- HTMX form success responses render the normal template response instead of redirecting.
- HTMX form error responses retarget to
#<request.htmx.trigger>, so requests are expected to come from a form element with a stable HTML id. PATCHmany-to-many updates are additive and use.add(...)semantics rather than replacement via.set(...).ModelFormView.delete()only uses URL parameters for relationship deletion.
Choosing between the middleware and mixins
Use plain Django CBVs when the view just renders a normal template response and HTMX only changes which partial is returned.
Use HtmxTemplateResponseMixin when the view itself needs to decide how to finalize a response for HTMX requests.
Use HtmxFormMixin when the view is form-oriented and should keep form-specific HTMX behavior like inline success rendering and error retargeting.
Use HyperFormView or ModelFormView when you want a full HTMX-aware form view with the above behavior and some opinionated defaults.
Example imports
from django_htmx_cbv.views import (
HtmxFormMixin,
HtmxTemplateResponseMixin,
HyperFormView,
ModelFormView,
ProcessHyperFormView,
)
Status
This package is still evolving. The current API is centered on reusable HTMX behavior for Django CBVs, with explicit middleware and template conventions. I welcome input from the community on the API design and implementation; I want this to be something we can all use!
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file django_htmx_cbv-0.0.1.dev1.tar.gz.
File metadata
- Download URL: django_htmx_cbv-0.0.1.dev1.tar.gz
- Upload date:
- Size: 11.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.3.4 CPython/3.14.3 Linux/6.17.0-1010-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
81ddca2047cd081f2c27044dd56e13d06349f57092112ce68153a4a42ce960a4
|
|
| MD5 |
f15a86a72e6777f0c0606da256a2b4c4
|
|
| BLAKE2b-256 |
9f8e550e2e0eced7ec8be03da066df1c7ec3eae51758a317119f200b550c3be4
|
File details
Details for the file django_htmx_cbv-0.0.1.dev1-py3-none-any.whl.
File metadata
- Download URL: django_htmx_cbv-0.0.1.dev1-py3-none-any.whl
- Upload date:
- Size: 12.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.3.4 CPython/3.14.3 Linux/6.17.0-1010-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0fe8e43558e3571aa51dc4b69e0cd13f879df3cb7c07e1fdb96b17f29a2cfdcd
|
|
| MD5 |
8b622eabc50f72021bac0a1c1abad2ff
|
|
| BLAKE2b-256 |
3f5d6bb73f8a65b8fa43cf68e94c0aeb73c3c3820f0c7750e3586a369c1687c0
|
