Drop-in playground for your django-cotton components — annotate them once with @prop comments and get a live, themable, copy-and-paste gallery with auto-generated controls, a lint report, and an insights dashboard.
📚 Docs: https://velezanthony.github.io/django-cotton-gallery/
The gallery is a development-only tool, so the recommended install is as a dev dependency with uv — that way it never ships to production (uv sync --no-dev leaves it out):
uv add --dev django-cotton-galleryPrefer pip? That works just as well:
pip install django-cotton-gallery# settings.py
INSTALLED_APPS = [
# ...
"django_cotton", # already there if cotton is set up
"django_cotton_gallery",
]# urls.py
from django.conf import settings
from django.urls import include, path
urlpatterns = [...]
# Gate it — the gallery exposes component source code. Do NOT ship to prod.
if settings.DEBUG:
urlpatterns += [path("", include("django_cotton_gallery.urls"))]Run your server and open http://localhost:8000/django-cotton-gallery/. That's it — the gallery indexes whatever cotton already finds. The empty state walks you through your first component if the catalog is empty.
Need production access patterns (staff-only, feature flags), asset injection, or per-setting reference? → Getting started · Configuration
Live playground — every component renders with auto-generated controls from your @prop annotations. Tweak any prop in real time, copy the tag, done.
Lint report — three severity tiers (errors, warnings, hints) for @prop/<c-vars> mismatches, missing descriptions, and undeclared variables. The same engine runs in CI as python manage.py cotton_lint.
Insights dashboard — config health, annotation coverage, zombie components, most-referenced ranking. Spot rot before it ships.
Ctrl+K switcher with structured filters (prop:size, slot:actions, accepts-attrs, has-named-slots, deprecated) — find any component without leaving the keyboard.
Plus: a refactor planner (transitive dependency tree), an annotation builder (form-based @prop editor), a side-by-side compare view, and i18n chrome (English, Spanish, Basque, French). → Full feature tour
| Versions | |
|---|---|
| Python | 3.10 · 3.11 · 3.12 · 3.13 |
| Django | 4.2 LTS · 5.0 · 5.1 · 5.2 LTS · 6.0 |
| i18n | English (default) · Spanish · Basque · French |
CI verifies every valid Python × Django combination on every push (plus Windows + macOS smoke tests).
Clone, then make dev && make serve to run the bundled demo at http://localhost:8000/django-cotton-gallery/. Everything else — repo layout, tests, the Python × Django matrix, i18n, releases — lives in docs/contributors/. See also CONTRIBUTING.md and the CHANGELOG.
If this project saves you time, consider sponsoring its development. It helps keep it maintained.
MIT — see LICENSE.