django-bird

High-flying components for perfectionists with deadlines.

Requirements

• Python 3.10, 3.11, 3.12, 3.13

• Django 4.2, 5.0, 5.1

Installation

1. Install the package from PyPI:

   python -m pip install django-bird
   
   # 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. django-bird will automatically configure the necessary settings in your project.

   If you need to customize the configuration or prefer to set up django-bird manually, you can set DJANGO_BIRD["ENABLE_AUTO_CONFIG"] = False in your settings.

   For detailed instructions, please refer to the Manual Setup section within the Configuration documentation.

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.