hub / github.com/django-commons/django-unicorn

github.com/django-commons/django-unicorn @0.67.0

Chat with this repo

repository ↗ · DeepWiki ↗ · release 0.67.0 ↗ · + Follow

1,392 symbols 5,076 edges 227 files 299 documented · 21%

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

Unicorn The magical reactive component framework for Django ✨

PyPI PyPI - Downloads GitHub Sponsors

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

Use your favorite package manager to install Unicorn:

uv add django-unicorn
pip install django-unicorn
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


{% 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


{% 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.






  <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>




    {% if tasks %}
      <ul>
        {% for task in tasks %}
          <li>{{ task }}</li>
        {% endfor %}
      </ul>
    {% else %}
      No tasks 🎉
    {% endif %}

# 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):
    form_class = TodoForm

    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. 🤩

Unicorn progressively enhances a normal Django view, so the initial render is fast and great for SEO.
Unicorn binds to the elements you specify and automatically makes AJAX calls when needed.
Unicorn seamlessly 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:

📖 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.

_{Adam Hill} 💻 ⚠️	_{Andres Vargas} 💻	_{Eddy Ernesto del Valle Pino} 💻	_{Yaser Al-Najjar} 💻	_{Stephan Traub} ⚠️	_{Fredrik Borg} 💻 ⚠️	_mbacicc 💻
_Ron 📖	_Franziskhan 💻	_{Josh Higgins} ⚠️ 💻	_{Amayas Messara} 💻	_{Apoorva Pandey} ⚠️ 💻	_{Christian González} 💻 📖	_robwa 💻 ⚠️
_{Preston Badeer} 📖	_Sergei 📖 💻 ⚠️	_bazubii 💻 ⚠️	_{Dan Caron} 📖	_Shantanu 💻

Core symbols most depended-on inside this repo

src/django_unicorn/utils.py

create

called by 44

src/django_unicorn/components/unicorn_view.py

post_and_get_response

called by 42

tests/views/message/utils.py

set_property_from_data

called by 38

src/django_unicorn/views/utils.py

render

called by 36

src/django_unicorn/templatetags/unicorn.py

get_root_element

called by 31

src/django_unicorn/components/unicorn_template_response.py

Shape

Function 725

Method 394

Class 271

Route 2

Languages

Python87%

TypeScript13%

Modules by API surface

tests/views/test_security_deep.py80 symbols

tests/serializer/test_dumps.py62 symbols

tests/components/test_component.py61 symbols

tests/templatetags/test_unicorn_render.py48 symbols

src/django_unicorn/components/unicorn_view.py44 symbols

tests/views/fake_components.py41 symbols

tests/views/action_parsers/call_method/test_call_method_name.py41 symbols

tests/views/message/test_call_method.py31 symbols

tests/test_typer.py28 symbols

src/django_unicorn/static/unicorn/js/unicorn.min.js28 symbols

src/django_unicorn/static/unicorn/js/component.js25 symbols

tests/views/message/test_calls.py24 symbols

For agents

$ claude mcp add django-unicorn \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact