💉✅ Django Unicorn Loosened

This is a repository of a customized version of Django Unicorn package.

Loosened version of package is by default functionally the same as the official package. Extended stuff that were added are controllable with settings/feature flags.

This repository is intended to sync periodically with adamghill repository in order to be up to date with the latest changes.

Releasing as an installable package is planned only for a private repo for now, and version numbers will follow an official one with one extra dotted number. In the example, if there is an official version of 0.50.0, the tag that follows this version here will be 0.50.0.1.

Additional settings

Available additional settings that can be set to UNICORN dict in settings.py which are not part of official package.

• USE_CSRF_TOKEN - default: True - If set to False, unicorn does not check or send csrf token value so {% csrf_token %} is not mandatory in the templates. This is added due the fact to additional page caching system like Varnish does not operate effective if Cookie value is present in Vary header.
• CHECK_CHECKSUM_MATCH - default: True - If set to False, unicorn does not perform data checksum check on each request.
• COMPONENT_CACHE_TIMEOUT - default: 600 - Time in seconds used to cache components.

Deployment

1. Add your repository to poetry.config: poetry config repositories.myrepo http://to.my.repo

2. Publish package to your repository with --build flag poetry publish --build -r myrepo -u <myrepouser> -p <myrepopass>

Customization changelog

0.62.0.0 - (2025-08-08)

• Sync with main package, version 0.62.0

0.61.0.4 - (2025-03-25)

• Update restore_from_cache in to handle cases where parent of cached component does not have it in the children. It can happen when parent adds children dynamically and parent restored from cache was cached by another process where component being restored wasn't present.

0.61.0.3 - (2024-10-30)

• Components are now cached with timeout. Added COMPONENT_CACHE_TIMEOUT (Default: 600) setting that is used as component cache timeout.

0.61.0.2 - (2024-10-22)

• Delete json_tag from child components as it could cause RecursionError

0.61.0.1 - (2024-07-16)

• Avoid recursion upon caching parent/child complex components with pickle.dumps
• Sync with main package, version 0.61.0

0.60.0.1 - (2024-03-29)

• No customizations, just sync with main package.

0.58.1.2 - (2024-01-10)

• add optional CHECK_CHECKSUM_MATCH setting which is set by default to True. If turned off, unicorn does not perform data checksum check on each request.

0.58.1.1 - (2024-01-10)

• No customizations, just sync with main package.

0.57.1.1 - (2023-11-10)

• No customizations, just sync with main package.

0.55.0.1 - (2023-09-15)

• No customizations, just sync with main package.

0.54.0.1 - (2023-08-31)

• No customizations, just sync with main package.

0.53.0.1 - (2023-08-08)

• No customizations, just sync with main package.

0.50.1.1 - (2023-05-23)

• No customizations, just sync with main package.

0.50.0.1 - (2023-05-11)

• Add USE_CSRF_TOKEN (useCsrfToken) setting that if set to False (false) avoids CSRF token check. By default USE_CSRF_TOKEN is set to True.
• [views.init.py:message] - Added decorator csrf_handle that checks USE_CSRF_TOKEN setting and based on boolean applies csrf_protect or csrf_exempt decorator.
• [templatetags/unicorn.py:unicorn_scripts] - Added USE_CSRF_TOKEN to return in order to use in templates
• [templates/unicorn/scripts.html] - Translate USE_CSRF_TOKEN value into useCsrfToken javascript variable and pass it to Unicorn.init
• [static/unicorn/js/unicorn.js:init] - apply useCsrfToken to args that are used latter in component.
• [static/unicorn/js/component.js:Component] - add useCsrfToken to class instance in constructor
• [static/unicorn/js/messageSender.js:send] - set csrf token to headers only if useCsrfToken is set to true.

---

Official documentation below

---

Unicorn

The magical reactive component framework for Django ✨

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

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

• Form Validation
• Redirection
• Loading States
• Dirty States
• Partial Updates
• Polling
• Scroll Triggering
• Messages
• Javascript Integration

📖 Dig In

• Documentation
• Examples
• Screencasts
• Changelog

❤️ 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 💻	regoawt 💻 ⚠️	Lasse H. Bomholt 💻
Martey Dodoo 📖	Pierre 💻	Roman Imankulov ⚠️ 💻	Lemi Boyce 💻	Jack Sundberg 💻	siliconcow 💻 ⚠️	Akintola Rahmat 💻
Mario Munoz 📖	Emily Wood 💻	Jeremy Wright 💻

This project follows the all-contributors specification. Contributions of any kind welcome!