Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adamghill/django-unicorn

The magical reactive component framework for Django ✨
https://github.com/adamghill/django-unicorn

django frontend-framework fullstack javascript python

Last synced: 2 days ago
JSON representation

The magical reactive component framework for Django ✨

Host: GitHub
URL: https://github.com/adamghill/django-unicorn
Owner: adamghill
License: mit
Created: 2020-07-11T23:17:06.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2025-02-03T04:04:03.000Z (17 days ago)
Last Synced: 2025-02-11T15:11:19.537Z (9 days ago)
Topics: django, frontend-framework, fullstack, javascript, python
Language: Python
Homepage: https://www.django-unicorn.com
Size: 5.49 MB
Stars: 2,459
Watchers: 25
Forks: 123
Open Issues: 92
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-python-web-frameworks - Django-Unicorn

README

        


  





  Unicorn

  
The magical reactive component framework for Django ✨


![PyPI](https://img.shields.io/pypi/v/django-unicorn?color=blue&style=flat-square)

![PyPI - Downloads](https://img.shields.io/pypi/dm/django-unicorn?color=blue&style=flat-square)

![coverage](https://raw.githubusercontent.com/adamghill/django-unicorn/python-coverage-comment-action-data/badge.svg)

![GitHub Sponsors](https://img.shields.io/github/sponsors/adamghill?color=blue&style=flat-square)

[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors-)

[Unicorn](https://www.django-unicorn.com) 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](https://www.django-unicorn.com) has extensive documentation, code examples, and more!**

## ⚡ Getting started

### 1. [Install the package](https://www.django-unicorn.com/docs/installation/)

`pip install django-unicorn` OR `poetry add django-unicorn`

### 2. Add `django_unicorn` to `INSTALLED_APPS`

```python

# settings.py

INSTALLED_APPS = (

    # other apps

    "django_unicorn",

)

```

### 3. Update urls.py

```python

# urls.py

import django_unicorn

urlpatterns = (

    # other urls

    path("unicorn/", include("django_unicorn.urls")),

)

```

### 4. Add `Unicorn` to the HTML template

```html

{% load unicorn %}

  

    {% unicorn_scripts %}

  

  

    {% csrf_token %}

  

```

### 5. [Create a component](https://www.django-unicorn.com/docs/components/)

`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

```html

{% load unicorn %}

  

    {% unicorn_scripts %}

  

  

    {% csrf_token %}

    {% unicorn 'COMPONENT_NAME' %}

  

```

## [Example todo component](https://www.django-unicorn.com/examples/todo)

The `unicorn:` attributes bind the element to data and can also trigger methods by listening for events, e.g. `click`, `input`, `keydown`, etc.

```html



  

    

  

  Add

  Clear all tasks

  


    {% if tasks %}

      



        {% for task in tasks %}

          {{ task }}

        {% endfor %}

      

    {% else %}

      No tasks 🎉

    {% endif %}

  



```

```python

# 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](https://www.django-unicorn.com/docs/validation/)

- [Redirection](https://www.django-unicorn.com/docs/redirecting/)

- [Loading States](https://www.django-unicorn.com/docs/loading-states/)

- [Dirty States](https://www.django-unicorn.com/docs/dirty-states/)

- [Partial Updates](https://www.django-unicorn.com/docs/partial-updates/)

- [Polling](https://www.django-unicorn.com/docs/polling/)

- [Scroll Triggering](https://www.django-unicorn.com/docs/visibility/)

- [Messages](https://www.django-unicorn.com/docs/messages/)

- [Javascript Integration](https://www.django-unicorn.com/docs/advanced/)

## 📖 Dig In

- [Documentation](https://www.django-unicorn.com/docs/)

- [Examples](https://www.django-unicorn.com/examples/todo)

- [Screencasts](https://www.django-unicorn.com/screencasts/installation)

- [Changelog](https://www.django-unicorn.com/docs/changelog/)

## ❤️ Support

This project is supported by GitHub [Sponsors](https://github.com/sponsors/adamghill) and [Digital Ocean](https://m.do.co/c/617d629f56c0).



  

    

  



## 🔧 Contributors

Check out [this guide](DEVELOPING.md) for more details on how to contribute.

Thanks to the following wonderful people ([emoji key](https://allcontributors.org/docs/en/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](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!