Django class-based views for HTMX-powered Bootstrap modals
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
Django Htmx Modal Forms
Documentation: https://django-htmx-modal-forms.readthedocs.io
Source Code: https://github.com/abe-101/django-htmx-modal-forms
A Django package that provides class-based views for handling forms in Bootstrap modals using HTMX. This package makes it easy to add create and update functionality to your Django models with a clean modal interface.
Features
- 🚀 Easy-to-use class-based views for modal forms
- ⚡ HTMX-powered for dynamic updates without page reloads
- 🎨 Bootstrap modal integration with customizable sizes
- ✨ Automatic form validation with error handling
- 🐛 Debug mode for development
Requirements
- Python 3.8+
- Django 4.2+
- django-htmx
- Bootstrap 5
- django-crispy-forms
Installation
- Install via pip:
pip install django-htmx-modal-forms
- Add to your
INSTALLED_APPS:
INSTALLED_APPS = [
...
"crispy_forms",
"crispy_bootstrap5",
"django-htmx"
"django_htmx_modal_forms",
]
- Load and include the JavaScript in your base template:
{% load htmx_modal_forms %}
<!doctype html>
<html>
<head>
<!-- Required dependencies -->
<script src="{% static 'js/bootstrap.bundle.min.js' %}"></script>
<script src="{% static 'js/htmx.min.js' %}"></script>
<!-- Modal handlers -->
{% htmx_modal_script %}
</head>
<body>
<!-- Your content -->
</body>
</html>
Quick Start
- Create your view:
from django_htmx_modal_forms import HtmxModalUpdateView
class PersonUpdateView(HtmxModalUpdateView):
model = Person
form_class = PersonForm
detail_template_name = "persons/_person_card.html"
modal_size = "lg" # Optional: sm, lg, or xl
- Add the URL pattern:
path("persons/<int:pk>/edit/", PersonUpdateView.as_view(), name="person_update"),
- Create your detail template (
_person_card.html):
<div id="person-{{ person.id }}" class="card">
<div class="card-body">
<h5 class="card-title">{{ person.name }}</h5>
<p class="card-text">{{ person.email }}</p>
</div>
</div>
Important: The wrapper element must have an ID that matches your model instance (e.g.,
id="person-{{ person.id }}")! This ID is used by the view to locate and replace the content after a successful form submission.
- Add a button to trigger the modal:
<button
hx-get="{% url 'person_update' pk=person.pk %}"
hx-target="body"
hx-swap="beforeend"
class="btn btn-primary"
>
Edit Person
</button>
That's it! When you click the edit button, a modal will appear with your form. On successful submission, the person's card will automatically update with the new information.
Advanced Usage
Custom Modal Titles
class PersonCreateView(HtmxModalCreateView):
model = Person
form_class = PersonForm
modal_title = "Add New Team Member" # Custom title
Different Modal Sizes
class PersonUpdateView(HtmxModalUpdateView):
model = Person
form_class = PersonForm
modal_size = "xl" # Available: sm, lg, xl
Debug Mode
Debug mode is automatically enabled when settings.DEBUG = True. It provides helpful console logging for:
- Modal initialization
- Event triggers
- Bootstrap/HTMX availability
- Error conditions
How It Works Behind the Scenes
The package orchestrates a series of interactions between Django, HTMX, and Bootstrap:
- When you click an edit button, HTMX makes a GET request to your view
- The view returns a Bootstrap modal containing your form and triggers the
modal:showevent - The included JavaScript initializes and displays the modal
- When submitting the form:
- If there are validation errors, the view replaces the form content with the errors
- On success:
- The view updates your model
- Renders the new content using your detail template
- Uses HTMX's out-of-band swap to replace the content using the ID you provided
- Triggers the modal to close
This approach provides a smooth user experience with minimal JavaScript while maintaining Django's server-side validation and template rendering.
[Previous content remains the same until Contributing section]
Credits
This package was inspired by Josh Karamuth's blog posts on Django + HTMX modals:
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. To develop locally:
- Clone the repository
- Install dependencies:
uv sync - Run tests:
uv run pytest
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Abe Hanoka 💻 🤔 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Credits
This package was created with Copier and the browniebroke/pypackage-template project template.
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
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_modal_forms-0.3.0.tar.gz.
File metadata
- Download URL: django_htmx_modal_forms-0.3.0.tar.gz
- Upload date:
- Size: 15.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.0.1 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e072dd29105acf770f8d98f9be95ad9e04842d979c1b7fa21aa6067fc0e1b8ba
|
|
| MD5 |
87a7beb91619adeeb0c9cf53df618766
|
|
| BLAKE2b-256 |
8b10ea7f09e2abb38a8d8eba6dd4f4fb68f2b2b403127a8dbc51d26550acbeab
|
Provenance
The following attestation bundles were made for django_htmx_modal_forms-0.3.0.tar.gz:
Publisher:
ci.yml on abe-101/django-htmx-modal-forms
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_htmx_modal_forms-0.3.0.tar.gz -
Subject digest:
e072dd29105acf770f8d98f9be95ad9e04842d979c1b7fa21aa6067fc0e1b8ba - Sigstore transparency entry: 160215546
- Sigstore integration time:
-
Permalink:
abe-101/django-htmx-modal-forms@a264fae22efe399f26fb9f91fafc08514419c1ee -
Branch / Tag:
refs/heads/main - Owner: https://github.com/abe-101
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@a264fae22efe399f26fb9f91fafc08514419c1ee -
Trigger Event:
push
-
Statement type:
File details
Details for the file django_htmx_modal_forms-0.3.0-py3-none-any.whl.
File metadata
- Download URL: django_htmx_modal_forms-0.3.0-py3-none-any.whl
- Upload date:
- Size: 12.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.0.1 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
189852c65f79a8ea300ab7452342aa8190f21f81ae5beba44bfe3a526b0b8320
|
|
| MD5 |
97240c4033533d9f2b83b6467acc2ec2
|
|
| BLAKE2b-256 |
214e0e56ecb5e22b108605078b8d54ab94f290e9e649663922320f466b401ac9
|
Provenance
The following attestation bundles were made for django_htmx_modal_forms-0.3.0-py3-none-any.whl:
Publisher:
ci.yml on abe-101/django-htmx-modal-forms
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
django_htmx_modal_forms-0.3.0-py3-none-any.whl -
Subject digest:
189852c65f79a8ea300ab7452342aa8190f21f81ae5beba44bfe3a526b0b8320 - Sigstore transparency entry: 160215548
- Sigstore integration time:
-
Permalink:
abe-101/django-htmx-modal-forms@a264fae22efe399f26fb9f91fafc08514419c1ee -
Branch / Tag:
refs/heads/main - Owner: https://github.com/abe-101
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@a264fae22efe399f26fb9f91fafc08514419c1ee -
Trigger Event:
push
-
Statement type:
