Repository files navigation

django-components is a modular and extensible UI framework for Django.

It combines Django's templating system with the modularity seenin modern frontend frameworks like Vue or React.

Withdjango-components you can support Django projects small and large without leaving the Django ecosystem.

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

{# components/calendar/calendar.html #}<divclass="calendar">  Today's date is <span>{{ date }}</span></div>

# components/calendar/calendar.pyfromdjango_componentsimportComponent,register@register("calendar")classCalendar(Component):template_file="calendar.html"

Or a combination of Django template, Python, CSS, and #"auto" data-snippet-clipboard-copy-content="{# components/calendar/calendar.html #}<div class="calendar"> Today's date is <span>{{ date }}</span></div>">

{# components/calendar/calendar.html #}<divclass="calendar">  Today's date is <span>{{ date }}</span></div>

/* components/calendar/calendar.css */.calendar {width:200px;background: pink;}

/* components/calendar/calendar.js */document.querySelector(".calendar").onclick=()=>{alert("Clicked calendar!");};

# components/calendar/calendar.pyfromdjango_componentsimportComponent,register@register("calendar")classCalendar(Component):template_file="calendar.html"js_file="calendar.js"css_file="calendar.css"defget_template_data(self,args,kwargs,slots,context):return {"date":kwargs["date"]}

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

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

Features

Modern and modular UI

fromdjango_componentsimportComponent@register("calendar")classCalendar(Component):template="""        <div>            Today's date is            <span>{{ date }}</span>        </div>    """css="""        .calendar {            width: 200px;            background: pink;        }    """js="""        document.querySelector(".calendar")            .addEventListener("click", () => {                alert("Clicked calendar!");            });    """# Additional JS and CSSclassMedia:js= ["https://cdn.jsdelivr.net/npm/htmx.org@2/dist/htmx.min.js"]css= ["bootstrap/dist/css/bootstrap.min.css"]# Variables available in the templatedefget_template_data(self,args,kwargs,slots,context):return {"date":kwargs["date"]        }

Composition with slots

{%component"Layout"bookmarks=bookmarksbreadcrumbs=breadcrumbs%}{%fill"header"%}        <divclass="flex justify-between gap-x-12">            <divclass="prose">                <h3>{{ project.name }}</h3>            </div>            <divclass="font-semibold text-gray-500">                {{ project.start_date }} - {{ project.end_date }}            </div>        </div>{%endfill%}{# Access data passed to `{% slot %}` with `data` #}{%fill"tabs"data="tabs_data"%}{%component"TabItem"header="Project Info"%}{%component"ProjectInfo"project=projectproject_tags=project_tagsattrs:class="py-5"attrs:width=tabs_data.width            /%}{%endcomponent%}{%endfill%}{%endcomponent%}

Extended template tags

{%component"table"    ...default_attrstitle="Friend list for {{ user.name }}"headers=["Name","Age","Email"]data=[        {"name":"John"|upper,"age": 30|add:1,"email":"john@example.com","hobbies": ["reading"],        },        {"name":"Jane"|upper,"age": 25|add:1,"email":"jane@example.com","hobbies": ["reading","coding"],        },    ],attrs:class="py-4 ma-2 border-2 border-gray-300 rounded-md"/%}

Full programmatic access

classTable(Component):js_file="table.js"css_file="table.css"template="""        <div>            <span>{{ variable }}</span>        </div>    """defget_template_data(self,args,kwargs,slots,context):# Access component's IDassertself.id=="djc1A2b3c"# Access component's inputs and slotsassertself.args== [123,"str"]assertself.kwargs== {"variable":"test","another":1}footer_slot=self.slots["footer"]some_var=self.context["some_var"]# Access the request object and Django's context processors, if availableassertself.request.GET== {"query":"something"}assertself.context_processors_data['user'].username=="admin"return {"variable":kwargs["variable"],        }# Access component's HTML / JS / CSSTable.templateTable.jsTable.css# Render the componentrendered=Table.render(kwargs={"variable":"test","another":1},args=(123,"str"),slots={"footer":"MY_FOOTER"},)

Granular HTML attributes

<div{%html_attrsattrsdefaults:class="default-class"class="extra-class"%}>

{%html_attrsclass="foo bar"class={"baz":True,"foo":False,    }class="extra"%}

{%html_attrsstyle="text-align: center; background-color: blue;"style={"background-color":"green","color":None,"width":False,    }style="position: absolute; height: 12px;"%}

HTML fragment support

# components/calendar/calendar.py@register("calendar")classCalendar(Component):template_file="calendar.html"classView:# Define handlersdefget(self,request,*args,**kwargs):page=request.GET.get("page",1)returnCalendar.render_to_response(request=request,kwargs={"page":page,                },            )defget_template_data(self,args,kwargs,slots,context):return {"page":kwargs["page"],        }# Get auto-generated URL for the componenturl=get_component_url(Calendar)# Or define explicit URL in urls.pypath("calendar/",Calendar.as_view())

Provide / Inject

<body>{%provide"theme"variant="light"%}{%component"header" /%}{%endprovide%}</body>

@register("header")class Header(Component):    template = "..."    def get_template_data(self, args, kwargs, slots, context):        theme = self.inject("theme").variant        return {            "theme": theme,        }

Input validation and static type hints

fromtypingimportOptionalfromdjango.templateimportContextfromdjango_componentsimportComponent,Slot,SlotInputclassButton(Component):classArgs:size:inttext:strclassKwargs:variable:stranother:intmaybe_var:Optional[int]=None# May be omittedclassSlots:my_slot:Optional[SlotInput]=Noneanother_slot:SlotInputdefget_template_data(self,args:Args,kwargs:Kwargs,slots:Slots,context:Context):args.size# intkwargs.variable# strslots.my_slot# Slot[MySlotData]

Button.render(# Error: First arg must be `int`, got `float`args=Button.Args(size=1.25,text="abc",    ),# Error: Key "another" is missingkwargs=Button.Kwargs(variable="text",    ),)

Extensions

Caching

fromdjango_componentsimportComponentclassMyComponent(Component):classCache:enabled=Truettl=60*60*24# 1 daydefhash(self,*args,**kwargs):returnhash(f"{json.dumps(args)}:{json.dumps(kwargs)}")

Simple testing

fromdjango_components.testingimportdjc_testfromcomponents.my_tableimportMyTable@djc_testdeftest_my_table():rendered=MyTable.render(kwargs={"title":"My table",        },    )assertrendered=="<table>My table</table>"

Debugging features

Sharing components

Documentation

Performance

Release notes

Community examples

Contributing and development