A handy collection of reusable Django UI components, allowing me to share and integrate elements efficiently across various projects.
Project description
django-sample-components
A reusable Django library that provides ready-to-use UI components — template tags, templates, and static assets — for use across Django projects.
Components are split into two groups:
- Static (
{% load sample_tags %}) — pure server-side rendered components, no JavaScript dependencies beyond Bootstrap. - Async (
{% load async_tags %}) — interactive components powered by HTMX that update without page reloads.
Installation
pip install django-sample-components
# or
poetry add django-sample-components
Add to INSTALLED_APPS in settings.py:
INSTALLED_APPS = [
# ...
'django_sample_components',
'django_htmx', # required for async components
]
Add HtmxMiddleware to MIDDLEWARE (required for async components):
MIDDLEWARE = [
# ...
'django_htmx.middleware.HtmxMiddleware',
]
Include the library URLs in your project's urls.py:
from django.urls import include, path
urlpatterns = [
path('components/', include('django_sample_components.urls')),
]
Collect static files:
python manage.py collectstatic
Static Components
Load with {% load sample_tags %} in any template. No HTMX or JavaScript required (except Bootstrap JS for simple_popup).
| Tag | Type | Quick usage |
|---|---|---|
greeting |
simple_tag | {% greeting "Alice" %} |
show_today_timestamp |
simple_tag | {% show_today_timestamp %} |
simple_typewriter |
simple_tag | {% simple_typewriter words %} |
simple_button |
simple_tag | {% simple_button "Label" href="/url" btn_type="primary" %} |
simple_toast |
simple_tag | {% simple_toast position="bottom-end" autohide=True delay=6000 %} |
shout |
block_tag | {% shout %}...{% endshout %} |
simple_alert |
block_tag | {% simple_alert type="success" %}...{% endsimple_alert %} |
simple_popup |
block_tag | {% simple_popup name_button="Open" title="Title" %}...{% endsimple_popup %} |
Quick example
{% load sample_tags %}
{% simple_alert type="success" %}
Your changes have been saved.
{% endsimple_alert %}
{% simple_popup name_button="Open" title="Confirm" size="sm" %}
<p>Are you sure?</p>
{% endsimple_popup %}
{% simple_button "Download" href="/files/report.pdf" icon_before="fa fa-download" %}
{# Toast container for Django messages + JS API (window.showToast) #}
{% simple_toast position="bottom-end" autohide=True delay=5000 %}
Async Components (HTMX)
Load with {% load async_tags %}. These components require HTMX and django-htmx. The easiest way to set them up is to extend master_async.html, which includes HTMX and handles CSRF automatically.
| Tag | Quick usage | Doc |
|---|---|---|
async_counter |
{% async_counter initial_value=0 step=1 %} |
docs |
async_lazy_load |
{% async_lazy_load url="/async/lazy-load/" delay_ms=1200 %} |
docs |
async_active_search |
{% async_active_search search_url="/search/" %} |
docs |
async_lazy_popup |
{% async_lazy_popup name_button="Open" content_url="/content/" %} |
docs |
async_sum_form |
{% async_sum_form %} |
docs |
async_registration_form |
{% async_registration_form %} |
docs |
Quick example
{% load async_tags %}
{# Counter with step 5, bounded 0–100 #}
{% async_counter initial_value=0 step=5 min_value=0 max_value=100 %}
{# Live search against your own endpoint #}
{% async_active_search search_url="/contacts/search/" placeholder="Search contacts..." %}
{# Modal that loads content only when opened #}
{% async_lazy_popup name_button="View Report" title="Monthly Report"
content_url="/reports/monthly/" size="lg" %}
{# Lazy load any endpoint on reveal #}
{% async_lazy_load url="/async/counter/component/?initial_value=10&step=2" delay_ms=2000 %}
{# Async forms #}
{% async_sum_form %}
{% async_registration_form %}
HTMX setup in your own base template
If you are not extending master_async.html, add the following to your base template:
{% load django_htmx %}
<head>
{% htmx_script %}
{% django_htmx_script %}
</head>
<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
...
</body>
Static vs Async — key differences
Static (sample_tags) |
Async (async_tags) |
|
|---|---|---|
| Rendered | Server-side, with the page | On demand via HTMX |
| JavaScript | None (Bootstrap JS for popups) | HTMX required |
| Page reload | N/A | Never |
| Dependencies | Bootstrap CSS/JS | Bootstrap CSS/JS + HTMX + django-htmx |
| Best for | Simple UI elements | Interactive, live, or heavy-content components |
Running locally
git clone https://github.com/GustavoRizzo/django-sample-components.git
cd django-sample-components
poetry install
poetry run task run-demo
Open http://127.0.0.1:8000 to browse the component showcase.
Tests
poetry run task test
Publishing
poetry version patch # bump version (e.g. 0.1.0 → 0.1.1)
poetry build
poetry publish
Update the version in both pyproject.toml and django_sample_components/__init__.py before releasing.
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_sample_components-0.1.8.tar.gz.
File metadata
- Download URL: django_sample_components-0.1.8.tar.gz
- Upload date:
- Size: 29.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.2.1 CPython/3.10.12 Linux/6.6.87.2-microsoft-standard-WSL2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4a72bbf7f60d72e71baa985ce725b49a531c2b58549bfe064f771557aa055c37
|
|
| MD5 |
a081ee0aba9cbb5d745a2ea741a69ca4
|
|
| BLAKE2b-256 |
9a972a74f95a8fd25a4a50d5511845078e692831db29ee9b88c448944dffaeb0
|
File details
Details for the file django_sample_components-0.1.8-py3-none-any.whl.
File metadata
- Download URL: django_sample_components-0.1.8-py3-none-any.whl
- Upload date:
- Size: 56.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.2.1 CPython/3.10.12 Linux/6.6.87.2-microsoft-standard-WSL2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f09e465a129b555dfd613ae49ed5bba5cd79906a1230187b221316b14c6024ae
|
|
| MD5 |
21bbfb4b3ea855dc3282b6421f955960
|
|
| BLAKE2b-256 |
98e50073fd651adb18597cde1e1f8f20dac647882e63932657e8488e1e089c4b
|
