django-components

0.149.0 verified Fri May 01 auth: no python

A library to create simple reusable template components in Django. Current version is 0.149.0, with active development and frequent releases (multiple per month). It supports Django 4.2+ and Python 3.10+. Key features include component slots, dynamic CSS/JS, and component nesting.

pip install django-components

Common errors

error TemplateSyntaxError: 'django_components' is not a registered tag library ↓

cause Forgetting to add 'django_components' to INSTALLED_APPS or not running migrate.

fix

Add 'django_components' to INSTALLED_APPS in settings.py and run python manage.py migrate.

error KeyError: 'component_name' ↓

cause Using the deprecated {% component_block %} syntax without registering the component.

fix

error ImportError: cannot import name 'Component' from 'django_components' ↓

cause Outdated version or incorrect import path.

fix

Upgrade to latest: pip install -U django-components; use from django_components import Component.

Warnings

gotcha Component templates are cached. If you modify a template file, you must restart the server or clear Django's template cache to see changes. Use a cache backend with auto-reload in development. ↓

fix Set django.template.backends.django.TEMPLATES loaders to cached.Loader only if you understand the caching; use FileSystemLoader for development.

deprecated Component.Kwargs is now the preferred way to define input defaults instead of a separate Component.Defaults class. Component.Defaults still works but may be removed in the future. ↓

fix Migrate defaults to Kwargs: class Kwargs: show_details: bool = True

breaking Dropped support for Python 3.8 and 3.9, and Django 5.1 in version 0.147.0. Older releases may have security issues. ↓

fix Use Python 3.10+ and Django 4.2+ or 5.0+.

gotcha Global JavaScript object renamed from `Components` to `DjangoComponents` in v0.146.0. Old object still available but deprecated. ↓

fix Update any JavaScript code referencing `window.Components` to `window.DjangoComponents`.

Imports

Component

wrong

from django_components.component import Component

correct

from django_components import Component

Old import path (pre-v0.100) breaks; use top-level import.

render_to_response

wrong

from django_components.library import render_to_response

correct

from django_components import render_to_response

Incorrect submodule path.

Quickstart

Define a simple component and render it in a Django template using the component_tags library.

from django_components import Component

class Greeting(Component):
    template = """<div>Hello {{ name }}!</div>"""
    
    def get_context_data(self, name, **kwargs):
        return {"name": name}

# Render in template:
# {% load component_tags %}
# {% component "greeting" name="World" / %}