django-bird

High-flying components for perfectionists with deadlines.

[!IMPORTANT] This library is in active development. Breaking changes may occur before v1.0.0. Use caution in production - pin your dependencies and test thoroughly. All changes, including breaking changes, are documented in the CHANGELOG.

Requirements

• Python 3.10, 3.11, 3.12, 3.13, 3.14
• Django 5.2, 6.0, 6.1

Installation

1. Install the package from PyPI:

   python -m pip install django-bird
   
   # optional: install dj-angles integration helpers too
   python -m pip install 'django-bird[angles]'
   
   # or if you like the new hotness
   
   uv add django-bird
   uv sync
   

2. Add the app to your Django project's INSTALLED_APPS:

   INSTALLED_APPS = [
       ...,
       "django_bird",
       ...,
   ]
   

3. Set up django-bird in your project settings:

   # Required: Add the asset finder to handle component assets
   STATICFILES_FINDERS = [
       "django.contrib.staticfiles.finders.FileSystemFinder",
       "django.contrib.staticfiles.finders.AppDirectoriesFinder",
       "django_bird.staticfiles.BirdAssetFinder",
   ]
   
   # Optional: Add templatetags to builtins for convenience
   # (otherwise you'll need to {% load django_bird %} in each template)
   TEMPLATES = [
       {
           # ... other settings ...
           "OPTIONS": {
               "builtins": [
                   "django_bird.templatetags.django_bird",
               ],
           },
       }
   ]
   

   For detailed instructions, please refer to the Configuration section in the documentation.

   [!TIP] For automatic configuration, you can use the django-bird-autoconf plugin.

Getting Started

django-bird is a library for creating reusable components in Django. Let's create a simple button component to show the basics of how to use the library.

Create a new directory named bird in your project's main templates directory. This will be the primary location for your components.

templates/
└── bird/

Inside the bird directory, create a new file named button.html. The filename determines the component's name.

templates/
└── bird/
    └── button.html

In button.html, create a simple HTML button. Use {{ slot }} to indicate where the main content will go. We will also define a component property via the {% bird:prop %} templatetag and add {{ attrs }} for passing in arbitrary HTML attributes.

{# templates/bird/button.html #}
{% bird:prop class="btn" %}
{% bird:prop data_attr="button" %}

<button class="{{ props.class }}" data-attr="{{ props.data_attr }}" {{ attrs }}>
    {{ slot }}
</button>

To use your component in a Django template, use the {% bird %} templatetag. The content between {% bird %} and {% endbird %} becomes the {{ slot }} content. Properties and attributes are set as parameters on the {% bird %} tag itself.

{% bird button class="btn-primary" disabled=True %}
    Click me!
{% endbird %}

django-bird automatically recognizes components in the bird directory, so no manual registration is needed. When Django processes the template, django-bird replaces the {% bird %} tag with the component's HTML, inserting the provided content into the slot, resulting in:

<button class="btn-primary" data-attr="button" disabled>
    Click me!
</button>

You now have a button component that can be easily reused across your Django project.

Documentation

django-bird offers features for creating flexible components, such as:

• Defining and registering components entirely within Django templates, without writing a custom templatetag
• Passing attributes and properties to components
• Named slots for organizing content within components
• Subcomponents for building complex component structures
• Automatic asset management for component CSS and JavaScript files, including explicit declarations for pre-rendered partials via {% bird:load %}
• Optional dj-angles integration for HTML-like component tags

For a full overview of the features and configuration options, please refer to the documentation.

Motivation

Several excellent libraries for creating components in Django exist:

• django-components
• django-cotton
• django-unicorn
• django-viewcomponent
• django-web-components
• slippers

[!NOTE] Also worth mentioning is django-template-partials from Carlton Gibson. While not a full component library, it allows defining reusable chunks in a Django template, providing a lightweight approach to reusability.

These libraries are excellent in their own right, each solving specific problems in innovative ways: django-components is full-featured and will take most people far with custom components, django-unicorn offers a novel approach to adding interactivity without a full JavaScript framework, and django-cotton has a new way of defining custom components that has me very excited.

So, why another Django component library?

Most of the ones above focus on defining components on the Python side, which works for many use cases. For those focusing on the HTML and Django template side, they have made significant strides in improving the developer experience. However, as a developer with strong opinions (sometimes loosely held 😄) about API design, I wanted a different approach.

After watching Caleb Porzio's 2024 Laracon US talk introducing Flux, I could not shake the desire to bring something similar to Django. While there are plenty of libraries such as Shoelace or UI kits designed for use in any web application, and tools like SaaS Pegasus for whole Django project generation, I couldn't find a well-polished component library solely dedicated to Django templates with the level of polish that Flux has for Laravel.

Initially, I considered contributing to existing libraries or wrapping one to add the functionality I wanted. However, I decided to create a new library for several reasons:

1. I wanted to respect the hard work of existing maintainers and avoid burdening them with features that may not align with their project's goals.
2. While wrapping an existing library might have been technically feasible and okay license-wise, it didn't feel right to build an entire component system on top of someone else's work, especially for a project I might want to develop independently in the future.
3. Building something new gives me the freedom to fully control the direction and architecture, without being constrained by design choices made in other libraries.
4. Healthy competition among libraries helps drive innovation, and I see this as an opportunity to contribute to the broader Django ecosystem.
5. Recent libraries like django-cotton and dj-angles are pushing Django templates in new and exciting directions and I wanted to join in on the fun. 😄

It's very early days for django-bird. What you see here is laying the foundation for a template-centric approach to Django components. The current implementation focuses on core functionality, setting the stage for future features and enhancements.

See the ROADMAP for planned features and the future direction of django-bird.

License

django-bird is licensed under the MIT license. See the LICENSE file for more information.