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, 5.2

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. 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.