Welcome to Django Components

django-components introduces component-based architecture to Django's server-side rendering. It combines Django's templating system with the modularity seen in modern frontend frameworks like Vue or React.

A component in django-components can be as simple as a Django template and Python code to declare the component:

<div class="calendar">
  Today's date is <span>{{ date }}</span>
</div>

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"

Or a combination of Django template, Python, CSS, and Javascript:

<div class="calendar">
  Today's date is <span>{{ date }}</span>
</div>

.calendar {
  width: 200px;
  background: pink;
}

document.querySelector(".calendar").onclick = function () {
  alert("Clicked calendar!");
};

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"
    js_file = "calendar.js"
    css_file = "calendar.css"

Alternatively, you can "inline" HTML, JS, and CSS right into the component class:

from django_components import Component

class Calendar(Component):
    template = """
      <div class="calendar">
        Today's date is <span>{{ date }}</span>
      </div>
    """

    css = """
      .calendar {
        width: 200px;
        background: pink;
      }
    """

    js = """
      document.querySelector(".calendar").onclick = function () {
        alert("Clicked calendar!");
      };
    """

Features¤

1. 🧩 Reusability: Allows creation of self-contained, reusable UI elements.
2. 📦 Encapsulation: Each component can include its own HTML, CSS, and JavaScript.
3. 🚀 Server-side rendering: Components render on the server, improving initial load times and SEO.
4. 🐍 Django integration: Works within the Django ecosystem, using familiar concepts like template tags.
5. ⚡ Asynchronous loading: Components can render independently opening up for integration with JS frameworks like HTMX or AlpineJS.

Potential benefits:

• 🔄 Reduced code duplication
• 🛠️ Improved maintainability through modular design
• 🧠 Easier management of complex UIs
• 🤝 Enhanced collaboration between frontend and backend developers

Django-components can be particularly useful for larger Django projects that require a more structured approach to UI development, without necessitating a shift to a separate frontend framework.

Quickstart¤

django-components lets you create reusable blocks of code needed to generate the front end code you need for a modern app.

Define a component in components/calendar/calendar.py like this:

@register("calendar")
class Calendar(Component):
    template_file = "template.html"

    def get_context_data(self, date):
        return {"date": date}

With this template.html file:

<div class="calendar-component">Today's date is <span>{{ date }}</span></div>

Use the component like this:

{% component "calendar" date="2024-11-06" %}{% endcomponent %}

And this is what gets rendered:

<div class="calendar-component">Today's date is <span>2024-11-06</span></div>

Read on to learn about all the exciting details and configuration possibilities!

(If you instead prefer to jump right into the code, check out the example project)

Release notes¤

Read the Release Notes to see the latest features and fixes.

Community examples¤

One of our goals with django-components is to make it easy to share components between projects. If you have a set of components that you think would be useful to others, please open a pull request to add them to the list below.

• django-htmx-components: A set of components for use with htmx. Try out the live demo.

Contributing and development¤

Get involved or sponsor this project - See here

Running django-components locally for development - See here