django-unicorn Documentation

Components can be organized into sub-folders within your app's components/ directory. To reference a component in a sub-folder, use dot notation in the {% unicorn %} tag.

Structure Example:

• myapp/components/hello/world.py
• myapp/templates/myapp/hello/world.html

<!-- index.html -->
{% load unicorn %}
{% csrf_token %}

{% unicorn 'hello.world' %}

Unicorn requires Python 3.8 or greater. It is recommended to use a virtual environment to manage dependencies like Django and Unicorn.

1. Verify your Python version: python --version
2. Create a virtual environment in your project directory: python -m venv .venv

Avoid defining mutable default values (like list or dict) directly on class variables, as all component instances will share the same reference in memory.

Instead, declare the type hint and initialize the mutable object inside the mount() method to ensure every instance gets its own unique object.

from django_unicorn.components import UnicornView

class SentenceView(UnicornView):
    words: list[str]  # Declare type hint without default
    word_counts: dict[str, int] = None  # Or use None as default

    def mount(self):
        # Initialize new objects every time the component is mounted
        self.words = []
        self.word_counts = {}

    def add_word(self, word: str):
        ...

The recommended way to handle modals or overlays triggered from within a table is to manage the state in the parent component and render the modal outside the <table> element. This prevents invalid DOM structures and ensures stable reactivity.

Implementation pattern:

1. In the child component, call a method on the parent to trigger the modal.
2. In the parent component, update state to show the modal.
3. In the parent template, render the modal after the </table> tag.

# Child component
def request_delete(self):
    self.parent.confirm_delete(self.item.id)

# Parent component
selected_id = None
show_modal = False

def confirm_delete(self, item_id):
    self.selected_id = item_id
    self.show_modal = True

<!-- Parent template -->
<table>
    ...contents...
</table>

{% if show_modal %}
    <div class="modal">...</div>
{% endif %}

Adding type hints to class variables helps Unicorn ensure that fields are correctly serialized/deserialized to the appropriate Python types. For example, without a float hint, a numeric field might be treated as a str during AJAX interactions.

from django_unicorn.components import UnicornView

class RatingView(UnicornView):
    rating: float = 0

    def calculate_percentage(self):
        # The type hint ensures rating is a float, not a str
        print(self.rating / 100.0)

To develop django-unicorn locally, fork the repository, clone it, and set up the environment using uv. You must install pre-commit hooks and sync dependencies with the minify and docs extras to ensure all development tools are available.

git clone <your-forked-repo>
cd django-unicorn
just install-pre-commit
# or
uv run pre-commit install

uv sync --extra minify --extra docs
just runserver

Use the unicorn:poll attribute to automatically refresh a component at a regular interval (defaulting to every 2 seconds). This is useful for real-time dashboards or chat interfaces.

Customizing Polling: To specify a specific method to be called during the poll, pass the method name as a string to the attribute: unicorn:poll="method_name".

# polling.py
from django.utils.timezone import now
from django_unicorn.components import UnicornView

class PollingView(UnicornView):
    current_time = now()

<!-- polling.html -->
<!-- Default polling (every 2 seconds) -->
<div unicorn:poll>
    Current time: {{ current_time }}
</div>

<!-- Polling with a specific method call -->
<div unicorn:poll="get_updates">
    Current time: {{ current_time }}
</div>