django-unicorn
The magical reactive component framework for Django ✨
MIT License
Unicorn adds modern reactive component functionality to your Django templates without having to learn a new templating language or fight with complicated JavaScript frameworks. It seamlessly extends Django past its server-side framework roots without giving up all of its niceties or forcing you to rebuild your application. With Django Unicorn, you can quickly and easily add rich front-end interactions to your templates, all while using the power of Django.
https://www.django-unicorn.com has extensive documentation, code examples, and more!
⚡ Getting started
1. Install the package
pip install django-unicorn OR poetry add django-unicorn
2. Add django_unicorn to INSTALLED_APPS
# settings.py
INSTALLED_APPS = (
# other apps
"django_unicorn",
)
3. Update urls.py
# urls.py
import django_unicorn
urlpatterns = (
# other urls
path("unicorn/", include("django_unicorn.urls")),
)
4. Add Unicorn to the HTML template
<!-- template.html -->
{% load unicorn %}
<html>
<head>
{% unicorn_scripts %}
</head>
<body>
{% csrf_token %}
</body>
</html>
5. Create a component
python manage.py startunicorn myapp COMPONENT_NAME
Unicorn uses the term "component" to refer to a set of interactive functionality that can be put into templates. A component consists of a Django HTML template and a Python view class which contains the backend code. After running the management command, two new files will be created:
-
myapp/templates/unicorn/COMPONENT_NAME.html(component template) -
myapp/components/COMPONENT_NAME.py(component view)
6. Add the component to your template
<!-- template.html -->
{% load unicorn %}
<html>
<head>
{% unicorn_scripts %}
</head>
<body>
{% csrf_token %}
{% unicorn 'COMPONENT_NAME' %}
</body>
</html>
Example todo component
The unicorn: attributes bind the element to data and can also trigger methods by listening for events, e.g. click, input, keydown, etc.
<!-- todo.html -->
<div>
<form unicorn:submit.prevent="add">
<input type="text"
unicorn:model.defer="task"
unicorn:keyup.escape="task=''"
placeholder="New task" id="task"></input>
</form>
<button unicorn:click="add">Add</button>
<button unicorn:click="$reset">Clear all tasks</button>
<p>
{% if tasks %}
<ul>
{% for task in tasks %}
<li>{{ task }}</li>
{% endfor %}
</ul>
{% else %}
No tasks 🎉
{% endif %}
</p>
</div>
# todo.py
from django_unicorn.components import UnicornView
from django import forms
class TodoForm(forms.Form):
task = forms.CharField(min_length=2, max_length=20, required=True)
class TodoView(UnicornView):
task = ""
tasks = []
def add(self):
if self.is_valid():
self.tasks.append(self.task)
self.task = ""
✨ Wait, is this magic?
Sort of! At least it might feel like it. 🤩
-
Unicornprogressively enhances a normal Django view, so the initial render is fast and great for SEO. -
Unicornbinds to the elements you specify and automatically makes AJAX calls when needed. -
Unicornseamlessly updates the DOM when the HTML changes.
Focus on building regular Django templates and Python classes without needing to switch to another language or use unnecessary infrastructure.
🤯 But wait, there's more!
As if that wasn't enough, other features include:
- Form Validation
- Redirection
- Loading States
- Dirty States
- Partial Updates
- Polling
- Scroll Triggering
- Messages
- Javascript Integration
📖 Dig In
❤️ Support
This project is supported by GitHub Sponsors and Digital Ocean.
🔧 Contributors
Check out this guide for more details on how to contribute.
Thanks to the following wonderful people (emoji key) who have helped build Unicorn.
This project follows the all-contributors specification. Contributions of any kind welcome!
