Components

djust provides a two-tier component system: Component for fast, stateless rendering and LiveComponent for interactive widgets with state and event handlers. Both render server-side with no JavaScript build step.

For styling, djust follows manifesto principle #7: "Strong opinions on security, state, transport. Zero opinions on CSS, markup, or design." Components output semantic HTML -- you bring your own styling via CSS custom properties, Tailwind, Bootstrap, or plain CSS. The optional djust.components template tag library and djust.theming (installed with the djust[components] and djust[theming] extras) provide a style-agnostic component library and design system powered by CSS custom properties.

Two Types of Components

Pick Component when you just need HTML output. Pick LiveComponent when the component needs to react to user interaction.

Stateless Components

Your First Component

from djust.components.base import Component

class StatusDot(Component):
    template = '<span class="dot dot-{{ color }}"></span>'

    def __init__(self, color: str = "green"):
        super().__init__(color=color)
        self.color = color

    def get_context_data(self):
        return {"color": self.color}

Use it in a LiveView:

class DashboardView(LiveView):
    template_name = "dashboard.html"

    def mount(self, request, **kwargs):
        self.status = StatusDot("green")

    def get_context_data(self, **kwargs):
        return {"status": self.status}

In the template, {{ status }} calls __str__() which calls render():

<div dj-root>
    <h1>Server Status: {{ status }}</h1>
</div>

Performance Waterfall

Every Component tries three rendering strategies in order:

1. Pure Rust (~1us) -- If _rust_impl_class is set and the Rust extension is built
2. Hybrid template (~5-10us) -- If template is set, rendered by the Rust template engine with Django fallback
3. Python _render_custom() (~50-100us) -- Full flexibility, you write the HTML string

You don't pick one -- you define as many as you want and the fastest available wins:

from djust.components.base import Component

try:
    from djust._rust import RustBadge
except ImportError:
    RustBadge = None

class Badge(Component):
    # Tier 1: Rust (if extension is built)
    _rust_impl_class = RustBadge

    # Tier 2: Hybrid template (Rust template engine + Django fallback)
    template = '<span class="badge bg-{{ variant }}">{{ text }}</span>'

    def __init__(self, text: str, variant: str = "primary"):
        super().__init__(text=text, variant=variant)
        self.text = text
        self.variant = variant

    def get_context_data(self):
        return {"text": self.text, "variant": self.variant}

    # Tier 3: Custom Python (used only when no `template` is set)
    def _render_custom(self):
        return f'<span class="badge bg-{self.variant}">{self.text}</span>'

Most components only need a template. Use _render_custom() instead of a template when you need framework-specific HTML (Bootstrap vs Tailwind). _render_custom() is reached only when the class has no template: a template that fails in the Rust engine is re-rendered by Django's engine, not by _render_custom(), so in the Badge above it never runs. Add _rust_impl_class for hot-path components rendered hundreds of times per page.

Updating a Component

Write the attribute. A plain component's constructor kwargs are its state, an attribute write goes through to that state, and change detection compares the component by it (ADR-033), so the handler below re-renders the dot:

@event_handler()
def toggle_status(self, **kwargs):
    self.status.color = "red" if self.status.color == "green" else "green"

.update(color=...) does the same for several properties at once. Only the constructor kwargs (and any declared fingerprint_fields) are state; an attribute a subclass computes for itself in __init__ is not.

The values a component emits arrive typed — a star renders dj-value-value:int="4" and the handler receives 4, not "4". When a component has to say which instance it is, give it a name:

self.ratings = [Rating(name=f"row-{row.pk}", value=row.stars) for row in rows]

@event_handler()
def set_rating(self, value, name=None, **kwargs):
    ...

Every trigger the instance renders then carries dj-value-name="row-7". (Form-field components whose constructor already takes name, such as DatePicker, use it as the HTML field name instead, and it is not stamped on triggers.) Components that render their own triggers do this through self.event_attrs(self.event, value=...), which is also what a custom component should call instead of hand-writing dj-click="…".

Component IDs

Components get a stable ID automatically:

class MyView(LiveView):
    def mount(self, request, **kwargs):
        self.user_badge = Badge("Admin")
        # user_badge.id => "badge-user_badge"

        Badge("Admin", id="custom-id")
        # .id => "custom-id"

The waterfall: explicit id= parameter > auto-generated from attribute name > class name.

Styling Components

Components are style-agnostic by default. Use CSS custom properties for themeable components:

class Alert(Component):
    template = """
        <div class="dj-alert dj-alert--{{ type }}" role="alert">
            {{ message }}
        </div>
    """

    def __init__(self, message: str, type: str = "info"):
        super().__init__(message=message, type=type)
        self.message = message
        self.type = type

    def get_context_data(self):
        return {"message": self.message, "type": self.type}

Then style with CSS custom properties that adapt to any theme:

.dj-alert {
    padding: var(--dj-spacing-3, 0.75rem);
    border-radius: var(--dj-radius, 8px);
    border: 1px solid var(--dj-border);
}
.dj-alert--success { background: var(--dj-success); color: white; }
.dj-alert--danger { background: var(--dj-danger); color: white; }
.dj-alert--info { background: var(--dj-info); color: white; }

This approach works with any styling system -- djust.theming presets, Tailwind, Bootstrap, or your own CSS. See Styling & Theming below for the full design system.

Note: The built-in components in djust.components.ui currently use _render_custom() with per-framework render methods (Bootstrap, Tailwind, Plain). This approach is being migrated toward CSS custom properties for true style independence. For new projects, prefer the djust.components template tag library, which is already style-agnostic.

LiveComponents (Stateful)

Your First LiveComponent

from djust.components.base import LiveComponent

class CounterWidget(LiveComponent):
    template = """
        <div>
            <button dj-click="decrement" data-component-id="{{ component_id }}">-</button>
            <span>{{ count }}</span>
            <button dj-click="increment" data-component-id="{{ component_id }}">+</button>
        </div>
    """

    def mount(self, **kwargs):
        self.count = kwargs.get("initial", 0)

    @event_handler()
    def increment(self, **kwargs):
        self.count += 1
        self.trigger_update()

    @event_handler()
    def decrement(self, **kwargs):
        self.count -= 1
        self.trigger_update()

    def get_context_data(self):
        return {"count": self.count}

Key differences from Component:

• mount() is required -- set up initial state here
• get_context_data() is required -- return template variables
• Event handlers must be decorated with @event_handler() (same as LiveView). Wire them with dj-click, dj-submit, etc.
• data-component-id="{{ component_id }}" routes events to the right component instance
• trigger_update() tells the parent LiveView to re-render

Using in a LiveView

class DashboardView(LiveView):
    template_name = "dashboard.html"

    def mount(self, request, **kwargs):
        self.counter = CounterWidget(initial=10)

    def get_context_data(self, **kwargs):
        return {"counter": self.counter}

<div dj-root>
    <h2>Counter</h2>
    {{ counter }}
</div>

{{ counter }} is the recommended spelling (see the note on component rendering below); the markup is inserted as safe HTML on every render path.

The component_id is automatically set to the attribute name ("counter") by the framework. No manual ID management needed.

Class-level components

A component can also be declared on the view class with a State class instead of mount()/get_context_data(). Each view instance gets its own state; the attribute name is the component_id (ADR-031):

from djust import LiveView
from djust.components.descriptors.base import LiveComponent, TypedState
from djust.decorators import event_handler


class Tabs(LiveComponent):
    class State(TypedState):
        active: str = "overview"

    template = """
        <nav>
          <button dj-click="select" dj-value-value="overview">Overview</button>
          <button dj-click="select" dj-value-value="billing">Billing</button>
        </nav>
        <p>{{ active }}</p>
    """

    @event_handler()
    def select(self, value: str = "", **kwargs):
        self.state.active = value


class SettingsView(LiveView):
    template = "<div dj-root>{{ nav }}</div>"

    nav = Tabs(active="overview")

What this gives you:

• view.nav is a bound component: view.nav.active reads and writes this view's state (view.nav.state is the State itself), and it is registered in view._components on first access, so it is routed, captured in time-travel snapshots and saved/restored with the session like any other component, including the signed back-navigation snapshot.
• Handlers are ordinary @event_handler methods on the component; inside one, self.state is the state of the view that received the event. Clicks inside the rendered markup carry the component_id automatically because {{ nav }} wraps the output in <div data-component-id="nav">.
• The State is the template context. {{ nav }} renders template (or template_name) with the state keys plus component_id; there is no get_context_data() on this path. A component without a template renders as its state's dict repr.
• Re-rendering is cached on the state's hash, so an unchanged component costs one hash per render. On the LiveView path {{ nav }} is the rendered HTML string, so string filters ({{ nav|length }}, |upper) act on the markup.

The eight built-in descriptors (Accordion, Tabs, Modal, ... in djust.components.descriptors) declare no template: they use the same mechanism with a Meta.event alias registered on the view, and the djust_components template tags ({% tabs %}, {% accordion %}, ...) draw their markup from the state.

Note that isinstance(view.nav, Tabs.State) is False -- the state is view.nav.state.

Scoped events: patching only the component

An event that changes only a class-level component's state does not re-render the page (ADR-032). After the handler runs, the runtime compares the view's assigns before and after; if the component's slot is the one thing that changed and the view's template is component-opaque for it, only the component is rendered and its subtree is diffed and spliced into the page's VDOM. The client receives the same patch frame it always did (the debug panel and benchmark_event see timing.scope == "component" when timing is exposed), recovery and versions stay consistent, and nothing changes in client.js. Whenever any condition fails, the page renders as before -- the scoped path is exact or not taken.

A template is component-opaque for nav when every reference to it is the bare {{ nav }}:

{# scoped: the only read is the bare variable #}
<div dj-root><h1>{{ title }}</h1>{{ nav }}</div>

{# page render: another read of the component's state #}
<div dj-root>{{ nav }} <small>{{ nav.active }}</small></div>
<div dj-root>{{ nav|length }}</div>
<div dj-root>{% if nav %}{{ nav }}{% endif %}</div>

Also page-rendered: any other context value that changed with the event -- a view @property, a get_context_data override or a @computed that derives something from self.nav.active is seen because the runtime compares the render context, key by key, against the last render before it takes the scoped path; an unresolved {% include %} / {% extends %} (the partial could read the state); a handler that changes any other assign in the same event; self._force_full_html = True; a pending push_event; and {{ nav }} rendered more than once or inside a dj-update="ignore" / dj-virtual region.

Lifecycle

__init__(**kwargs)
    └─> mount(**kwargs)      # Set initial state
        └─> _mounted = True

render()                     # Called on each parent re-render
    └─> get_context_data()   # Provide template vars

unmount()                    # Cleanup when removed
    └─> _mounted = False

Parent-Child Communication

Props down: Pass data to components via constructor kwargs or .update().

Events up: Components send events to their parent LiveView with send_parent().

class TodoItem(LiveComponent):
    template = """
        <div dj-click="toggle" data-component-id="{{ component_id }}">
            <input type="checkbox" {% if completed %}checked{% endif %}>
            {{ text }}
        </div>
    """

    def mount(self, **kwargs):
        self.text = kwargs.get("text", "")
        self.completed = kwargs.get("completed", False)
        self.todo_id = kwargs.get("todo_id")

    @event_handler()
    def toggle(self, **kwargs):
        self.completed = not self.completed
        # Notify parent
        self.send_parent("todo_toggled", {
            "id": self.todo_id,
            "completed": self.completed,
        })

    def get_context_data(self):
        return {"text": self.text, "completed": self.completed}

The parent LiveView handles it:

class TodoView(LiveView):
    def mount(self, request, **kwargs):
        self.todos = [
            {"id": 1, "text": "Buy milk", "completed": False},
            {"id": 2, "text": "Write docs", "completed": True},
        ]

    def handle_component_event(self, component_id, event, data):
        if event == "todo_toggled":
            for todo in self.todos:
                if todo["id"] == data["id"]:
                    todo["completed"] = data["completed"]

File-Based Templates

For complex HTML, use template_name instead of inline template:

class UserCard(LiveComponent):
    template_name = "components/user_card.html"

    def mount(self, **kwargs):
        self.user = kwargs.get("user")
        self.show_actions = kwargs.get("show_actions", True)

    def get_context_data(self):
        return {
            "user": self.user,
            "show_actions": self.show_actions,
            "component_id": self.component_id,
        }

<!-- templates/components/user_card.html -->
<div class="card" data-component-id="{{ component_id }}">
    <div class="card-body">
        <h5>{{ user.name }}</h5>
        <p>{{ user.email }}</p>
        {% if show_actions %}
        <button dj-click="edit_user"
                data-component-id="{{ component_id }}">Edit</button>
        {% endif %}
    </div>
</div>

Note: When using template_name, the component ID wrapper <div data-component-id="..."> is not added automatically. Include data-component-id="{{ component_id }}" in your template root element.

Built-in Components

djust ships with a library of ready-to-use components. All adapt to your CSS framework automatically.

Browsing the catalogue

Every component has a page that renders it live, on your own server, in your own theme. Include the theming URLs and open /theme/components/:

# urls.py
path("theme/", include("djust.theming.urls")),

Each page shows the component running, the option chips you can flip to see the variants, the two files you would write to use it (the view and the template line), its parameters, the events it sends to your view, its accessibility rules and where to override its styles. / focuses the search box. The pages are LiveViews, so the previews are the real component on a real server rather than a screenshot.

The catalogue is gated like the theme gallery: DEBUG, or a staff user, or DJUST_THEMING_GALLERY_PUBLIC = True for a site that publishes it. The theme presets live beside it at /theme/themes/.

Prefer to read rather than click? The same components are written up at docs.djust.org/reference/components/, generated from the same registry, and every catalogue page links to its entry there.

Link to the catalogue with a plain href, never dj-navigate: these pages bring their own stylesheet and script in <head>, and a dj-root-only SPA swap would drop the reader on unstyled markup (why).

Hosting the catalogue inside your own site. The pages render inside djust_theming/catalogue/_document.html. Ship a template at that path from an app listed before djust.theming in INSTALLED_APPS and yours wins: put your own navigation in it, include {% include "djust_theming/catalogue/_assets.html" %} in the <head>, load djust_theming/js/catalogue.js, and render {% block body %} — that block is where the catalogue puts its mount root, sidebar and content, all of which must stay inside it. Everything else in the file is the framework's own chrome, so replacing the file replaces the topbar too and your page renders one navigation rather than two.

UI Components

Layout Components

Data Components

Form Components

Usage Examples

Alert:

def mount(self, request, **kwargs):
    self.alert = AlertComponent(
        message="Changes saved!",
        type="success",
        dismissible=True,
    )

@event_handler()
def save(self, **kwargs):
    # ... save logic ...
    self.alert.show("Changes saved!", "success")

@event_handler()
def on_error(self, **kwargs):
    self.alert.show("Something went wrong", "danger")

Modal:

def mount(self, request, **kwargs):
    self.confirm_modal = ModalComponent(
        title="Confirm Delete",
        body="This action cannot be undone.",
        show=False,
        size="md",  # sm, md, lg, xl
    )

@event_handler()
def delete_clicked(self, **kwargs):
    self.confirm_modal.show()

@event_handler()
def dismiss(self, **kwargs):
    self.confirm_modal.hide()

Tabs:

from djust.components.layout import TabsComponent

def mount(self, request, **kwargs):
    self.tabs = TabsComponent(
        tabs=[
            {"id": "overview", "label": "Overview", "content": "..."},
            {"id": "settings", "label": "Settings", "content": "..."},
            {"id": "logs", "label": "Logs", "content": "...", "badge": "3"},
        ],
        active="overview",
        variant="tabs",  # "tabs" or "pills"
    )

Data Table:

from djust.components import TableComponent

def mount(self, request, **kwargs):
    self.users_table = TableComponent(
        columns=[
            {"key": "name", "label": "Name", "sortable": True},
            {"key": "email", "label": "Email"},
            {"key": "role", "label": "Role", "sortable": True},
        ],
        rows=list(User.objects.values("name", "email", "role")),
        striped=True,
        hoverable=True,
    )

ForeignKey Select:

from djust.components.forms import ForeignKeySelect

def mount(self, request, **kwargs):
    self.category = ForeignKeySelect(
        name="category",
        queryset=Category.objects.all(),
        label_field="name",
        label="Category",
        required=True,
        searchable=True,
        search_fields=["name"],
    )

Component Registry

LiveComponent classes can be registered by name for dynamic lookup (register_component rejects plain Component subclasses with TypeError):

from djust.components import register_component, get_component, list_components

# Register a custom LiveComponent (CounterWidget from above)
register_component("counter", CounterWidget)

# Look up by name
cls = get_component("counter")

# List all registered components
for name, cls in list_components().items():
    print(f"{name}: {cls.__name__}")

All built-in LiveComponents are auto-registered: alert, badge, button, card, dropdown, modal, progress, spinner, tabs, table, pagination.

Writing Custom Components

Stateless: Extend Component

Use when you need fast rendering with no interaction:

from djust.components.base import Component

class PriceBadge(Component):
    template = """
        <span class="price {% if on_sale %}price--sale{% endif %}">
            {% if on_sale %}<s>{{ original }}</s> {% endif %}
            {{ current }}
        </span>
    """

    def __init__(self, current: str, original: str = "", on_sale: bool = False):
        super().__init__(current=current, original=original, on_sale=on_sale)
        self.current = current
        self.original = original
        self.on_sale = on_sale

    def get_context_data(self):
        return {
            "current": self.current,
            "original": self.original,
            "on_sale": self.on_sale,
        }

Stateful: Extend LiveComponent

Use when the component needs to handle events or manage state:

from djust.components.base import LiveComponent

class SearchBox(LiveComponent):
    template = """
        <div data-component-id="{{ component_id }}">
            <input type="text" dj-input="on_search"
                   data-component-id="{{ component_id }}"
                   value="{{ query }}" placeholder="Search...">
            {% if loading %}
                <span class="spinner-border spinner-border-sm"></span>
            {% endif %}
            <ul>
            {% for result in results %}
                <li dj-click="select_result"
                    data-component-id="{{ component_id }}"
                    data-id="{{ result.id }}">
                    {{ result.name }}
                </li>
            {% endfor %}
            </ul>
        </div>
    """

    def mount(self, **kwargs):
        self.query = ""
        self.results = []
        self.loading = False
        self.search_fn = kwargs.get("search_fn")  # Callable for searching

    @event_handler()
    def on_search(self, value="", **kwargs):
        self.query = value
        if len(value) >= 2 and self.search_fn:
            self.loading = True
            self.results = self.search_fn(value)
            self.loading = False
        else:
            self.results = []
        self.trigger_update()

    @event_handler()
    def select_result(self, id=None, **kwargs):
        self.send_parent("result_selected", {"id": id})

    def get_context_data(self):
        return {
            "query": self.query,
            "results": self.results,
            "loading": self.loading,
        }

Checklist

When building a custom component:

• @event_handler() on every method wired to a dj-* event
• **kwargs in every event handler signature
• data-component-id="{{ component_id }}" on every element with dj-* events
• trigger_update() after state changes that should re-render
• send_parent() for events the parent needs to know about
• get_context_data() returns all variables used in the template
• mount() initializes all state -- don't rely on class-level defaults for mutable objects

Template Tips

Inline vs file-based templates:

• Use inline template = "..." for small components (< 20 lines of HTML)
• Use template_name = "components/my_widget.html" for complex HTML
• Both inline template and file-based template_name render through djust's Rust engine. A template_name that uses {% extends %} falls back to Django's engine.
• {% if %} / {% elif %} / {% else %} chains are supported in both.

Components in templates render via {{ component }} -- the __str__ method calls render() automatically, and this is the canonical spelling for both Component and LiveComponent; every example in these docs uses it (#2634). {{ component.render }} still resolves (it's the same underlying call) but isn't preferred: it depends on Django's nullary auto-call, which LIVEVIEW_CONFIG['template_auto_call'] = False switches off -- {{ component }} then still renders, while {{ component.render }} prints a bound-method repr. As of #2503, the two spellings render identical output on every render path -- verified directly, not assumed.

A component's markup is inserted unescaped on all four render paths (DjustTemplateBackend, the two standalone render_template entry points, and the LiveView path) -- no |safe needed. An earlier version of this note said the opposite while #2501 was open; it is closed, and the four paths were re-measured for ADR-031.

djust-components (Template Tag Library)

The djust.components app ships a library of style-agnostic UI components as Django template tags. Unlike the Python component classes in djust.components.ui, these use CSS custom properties for all styling -- no hardcoded Bootstrap or Tailwind classes.

Installation

pip install "djust[components]"

# settings.py
INSTALLED_APPS = [
    "djust.components",
    # ...
]

<!-- base template -->
<link rel="stylesheet" href="{% static 'djust_components/components.css' %}">

Usage

{% load djust_components %}

{% modal id="confirm" title="Are you sure?" open=modal_open %}
  <p>This action cannot be undone.</p>
  <button dj-click="confirm_delete">Delete</button>
  <button dj-click="close_modal">Cancel</button>
{% endmodal %}

{% tabs id="settings" active=active_tab event="set_tab" %}
  {% tab id="general" label="General" %}
    General settings content
  {% endtab %}
  {% tab id="security" label="Security" icon="🔒" %}
    Security settings content
  {% endtab %}
{% endtabs %}

{% card title="Dashboard" variant="elevated" %}
  Card content here
{% endcard %}

{% badge label="Online" status="online" pulse=True %}

{% progress value=75 label="Upload" color="success" %}

{% data_table rows=rows columns=columns sort_by=sort_by sort_desc=sort_desc %}

{% toast_container toasts dismiss_event="dismiss_toast" %}

Available Components

Styles for {% badge %}, {% avatar %}, {% progress %} and {% toast_container %}

These tags render BEM class names, styled in djust_components/components.css (the file the <link> above loads, and the one {% theme_head %} links whenever djust.components is installed). The rules are on the active theme's tokens, so the components follow light and dark mode. The status colour goes on the fill, border, dot or bar, and every label stays on --foreground, so no label's contrast depends on a status hue.

<span class="dj-badge dj-badge--error">
  <span class="dj-badge__dot dj-badge__dot--pulse" aria-hidden="true"></span>
  <span class="sr-only">Status: error</span>
  <span class="dj-badge__label">Failed</span>
</span>

To restyle one, write a rule for the same class after the stylesheet. The similarly named .badge-online / .badge-pulse rules belong to other badge markup, and .dj-badge-danger (single dash) to the Badge Python class. The Toast Python class renders single-dash names (dj-toast-<type>, dj-toast-message, dj-toast-dismiss), styled in the same file, which also reads the --dj-toast-* properties its docstring lists (--dj-toast-bg, --dj-toast-success-border, …), each falling back to a theme token. {% toast_container %} toasts read only the six base properties (--dj-toast-bg, -fg, -border, -radius, -padding, -shadow), not the per-type ones.

{% data_table %} row-level navigation (#1111)

Two ways to make whole rows clickable for navigation. Both render role="button", tabindex="0", and cursor:pointer on every row, and both respect Enter / Space for keyboard activation. Clicks inside nested interactive descendants (<a>, <button>, <input>, <label>, <select>, <textarea>) are short-circuited so they never trigger row navigation.

Option B — row_click_event (preferred, LiveView-idiomatic): each <tr> fires a djust event with data-value=row[row_click_value_key]. Your @event_handler receives the row's value via **kwargs and can self.redirect(...) (or do anything else):

from djust import LiveView
from djust.decorators import event_handler
from django.urls import reverse

class ClaimsListView(LiveView):
    template_name = "claims/list.html"

    def mount(self, request, **kwargs):
        self.rows = list(Claim.objects.values("id", "claim_number", "status"))
        self.columns = [
            {"key": "claim_number", "label": "Claim #"},
            {"key": "status", "label": "Status"},
        ]

    @event_handler()
    def open_claim(self, value: str = "", **kwargs):
        self.redirect(reverse("claims:detail", kwargs={"claim_id": value}))

{% data_table rows=rows columns=columns
              row_click_event="open_claim"
              row_click_value_key="id" %}

row_click_value_key defaults to "id"; override for slug-based routing (e.g. "uuid", "slug").

Option A — row_url (static-URL fallback): each <tr> gets data-href from a row dict key; the component JS module navigates via window.location.assign(href) on click / Enter / Space. Use when the target URL is computed once in the view and doesn't need a server round-trip:

def get_context_data(self, **kwargs):
    ctx = super().get_context_data(**kwargs)
    ctx["rows"] = [
        {"claim_number": "C-001", "claim_url": reverse("claims:detail", args=[1])},
    ]
    ctx["columns"] = [{"key": "claim_number", "label": "Claim #"}]
    return ctx

{% data_table rows=rows columns=columns row_url="claim_url" %}

row_click_event takes precedence when both are set.

Accessibility: row-clickable <tr>s are focusable (tabindex="0"), announce as buttons (role="button"), and activate on Enter or Space. Screen reader users get the same affordance as mouse / touch users.

CSP-strict friendly: no inline event handlers, no eval, no nonce plumbing required. Both options work under Content-Security-Policy: script-src 'self' once the component JS module is served as a static asset (no 'unsafe-inline').

Composition with selectable=True: per-row checkbox cells are <input> elements, which are in the nested-control guard's protected list. Clicking the checkbox fires the existing select_event and does not also fire row navigation.

Composition with cell-level link columns (#1110): cell <a> tags also "win" — clicking a cell link follows the link without firing the row event.

Static-URL safety: Option A's data-href value is regex-validated (/^(https?:|\/|\.)/) before navigation, so a hostile javascript: URI cannot execute even if it sneaks into the row dict. Always prefer URLs computed from reverse() in your view; never assign user-controlled strings to row_url data.

Customization

All components use CSS custom properties. Override them to match any theme:

:root {
  --dj-primary: #6366f1;
  --dj-success: #22c55e;
  --dj-warning: #eab308;
  --dj-danger: #ef4444;
  --dj-text: #e2e8f0;
  --dj-bg: #0f172a;
  --dj-bg-subtle: #1e293b;
  --dj-border: rgba(99, 102, 241, 0.15);
  --dj-radius: 8px;
}

This is what makes them style-agnostic: change the variables, and every component adapts. Works standalone or with djust.theming for full design system support.

Styles for the Alert, Progress and Avatar classes

The djust.components classes Alert, Progress and Avatar are styled in the same djust_components/components.css, on the theme's tokens. Each reads its own custom properties first, so you can restyle one component without touching the theme:

The {% theme_alert %} / {% theme_progress %} / {% theme_avatar %} tags from djust.theming render the same components with the theming package's own class names.

djust-theming

djust.theming is a production-ready theming system inspired by shadcn/ui, shipped in core. It provides CSS custom properties-based theming with light/dark mode, 12 design systems × 68 color presets, and reactive theme switching via djust LiveViews.

Installation

pip install "djust[theming]"

# settings.py
INSTALLED_APPS = [
    "djust.theming",
    # ...
]

TEMPLATES = [{
    "OPTIONS": {
        "context_processors": [
            "djust.theming.context_processors.theme_context",
        ],
    },
}]

# Choose a design system + color preset
LIVEVIEW_CONFIG = {
    "theme": {
        "theme": "material",       # Design system (12 options)
        "preset": "blue",          # Color preset (68 options)
        "default_mode": "system",  # light, dark, or system
    }
}

Design Systems + Color Presets

Mix any design system with any color preset (12 design systems × 68 color presets):

Design systems control typography, spacing, radius, shadows, and animations: Material, iOS, Fluent, Minimalist, Playful, Corporate, Retro, Elegant, Neo-Brutalist, Organic, Dense, djust

Color presets control the palette. A few of the 68: Default, Shadcn, Blue, Green, Purple, Orange, Rose, Cyberpunk, Forest, Nord, Dracula, Ocean Deep, Sunrise. Run python manage.py djust_theme list-presets for the full list.

# Material Design + Cyberpunk colors
LIVEVIEW_CONFIG = {"theme": {"theme": "material", "preset": "cyberpunk"}}

# iOS + Forest green palette
LIVEVIEW_CONFIG = {"theme": {"theme": "ios", "preset": "forest"}}

Template Integration

{% load theme_tags static %}
<!DOCTYPE html>
<html>
<head>
    {% theme_head link_css=True %}
    <link href="{% static 'djust_theming/css/base.css' %}" rel="stylesheet">
</head>
<body>
    {% theme_switcher %}          {# Full theme switcher UI #}
    {% theme_mode_toggle %}       {# Light/dark toggle #}
    {% theme_preset_selector %}   {# Preset picker #}

    <div class="card">
        <div class="card-header">Dashboard</div>
        <div class="card-body">
            <button class="btn btn-primary">Get Started</button>
        </div>
    </div>
</body>
</html>

The {% theme_X %} tags above work in both template engines — Django's and djust's Rust engine (the one that renders LiveView templates). They are also available as context-string variables ({{ theme_head }}, {{ theme_switcher }}, {{ theme_panel }}, {{ theme_mode_toggle }}, {{ theme_preset_selector }}) for the default-args case. Prefer the {{ ... }} form when a tag appears multiple times on a page (it pre-renders once per request); use the {% theme_X %} tag form when you need customization-with-args, e.g. {% theme_panel show_packs=False %} or {% theme_preset_selector layout="grid" %}.

Reactive Theme Switching with LiveView

from djust import LiveView
from djust.theming import ThemeMixin

class DashboardView(ThemeMixin, LiveView):
    template_name = "dashboard.html"

    def mount(self, request, **kwargs):
        super().mount(request, **kwargs)
        # theme_head, theme_switcher, theme_preset, theme_mode
        # are automatically available in the template context

Theme changes happen instantly over WebSocket -- no page reload.

shadcn/ui Compatibility

Import themes from themes.shadcn.com or export djust presets to share:

python manage.py djust_theme shadcn-import my-theme.json
python manage.py djust_theme shadcn-export --preset blue --output blue-theme.json

Tailwind Integration

python manage.py djust_theme tailwind-config --preset blue --output tailwind.config.js

Then use theme colors in Tailwind classes:

<button class="bg-primary text-primary-foreground hover:bg-primary/90 px-4 py-2 rounded-md">
  Primary Button
</button>

Cross-project cookie isolation (cookie_namespace)

If you run two or more djust projects on the same domain (e.g. localhost:8001, localhost:8002, etc.), browsers scope cookies by domain only — not by port. Without isolation, the four theming cookies (djust_theme, djust_theme_preset, djust_theme_pack, djust_theme_layout) leak across projects, so picking the "Cyberpunk" pack in project A pins it for project B too.

For sites without a user-facing theme switcher, the simpler fix is enable_client_override: False (introduced in v0.8.2 / #1013), which makes the server ignore client cookies entirely.

For sites with a user-facing switcher — where cookie writes must stay on — set a per-project namespace:

LIVEVIEW_CONFIG = {
    "theme": {
        "cookie_namespace": "djust_org",   # any unique-per-project string
    },
}

When set, theming cookies are read and written under <ns>_djust_theme, <ns>_djust_theme_preset, <ns>_djust_theme_pack, and <ns>_djust_theme_layout, so each project gets its own slot in the shared cookie jar.

The read path tries the namespaced cookie first and falls back to the legacy unprefixed cookie whenever the namespaced one is absent (until the next theme write creates it) — users keep their existing theme choice. After the user clicks the switcher (or any other path that calls setPreset / setPack / setTheme / setLayout), only the namespaced cookie is written.

When cookie_namespace is unset (default), the unprefixed names are used — existing deployments don't lose their theme on upgrade.

Choosing a Styling Approach

Function Components (v0.5.0+)

For the ~80% of UI pieces that are stateless — buttons, cards, badges, icons, alert boxes — function components close the gap between raw HTML and a full LiveComponent. They are plain Python functions registered via the @component decorator and invokable from templates with {% call %} or {% component %}.

from djust import component, Assign

@component
def badge(assigns):
    variant = assigns.get("variant", "default")
    return f'<span class="badge bg-{variant}">{assigns["children"]}</span>'

@component(
    name="primary_button",
    assigns=[
        Assign("label", type=str, required=True),
        Assign("size", type=str, default="md", values=["sm", "md", "lg"]),
    ],
)
def button(assigns):
    return f'<button class="btn btn-{assigns["size"]}">{assigns["label"]}</button>'

Usage in templates:

{% call "badge" variant="primary" %}New{% endcall %}

{% component "primary_button" label="Save" size="lg" %}{% endcomponent %}

Both tags are synonyms — pick whichever reads best at the call site. The body of the tag (everything between {% call %} / {% endcall %}) becomes assigns["children"] and assigns["inner_block"] (Phoenix parity). The body always wins over any children=/inner_block= kwarg passed at the call site — the block body is authoritative.

⚠ Escape user-controlled strings. The examples above f-string-interpolate variant / label directly into HTML. That's safe when the values come from your own code (literals, enum values), but if a kwarg originates from user input — e.g. {% call badge variant=user_selected_variant %} where user_selected_variant is a form field — you must escape it. Prefer html.escape(variant) or use format_html(...) from django.utils.html. The function's return value is treated as trusted HTML by the template engine (no auto-escape), which is what makes components expressive — but also means XSS is the component author's responsibility, not the template engine's.

Declarative Assigns

Declare the expected inputs with Assign(...) to get runtime validation, type coercion, and self-documenting components. Available on both LiveComponent subclasses (via class attribute) and function components (via @component(assigns=[...])).

assigns on a LiveComponent are validated whenever the class is constructed. slots are different: they are enforced only when the class is registered with @component and invoked through {% call %} / {% component %}. A Card(title=...) built in mount() never has its required=True slot checked. When invoked through {% call %}, the slot content reaches the instance as self._slots / self._children, which your get_context_data() must expose to the template itself.

from djust import LiveComponent, Assign, Slot

class Card(LiveComponent):
    template_name = "components/card.html"
    assigns = [
        Assign("title", type=str, required=True),
        Assign("variant", type=str, default="default",
               values=["default", "primary", "danger"]),
        Assign("padding", type=int, default=4),   # str "8" -> int 8 auto-coercion
        Assign("dismissable", type=bool, default=False),  # "true"/"yes"/"1" accepted
    ]
    slots = [Slot("inner_block", required=True)]

Validation behaviour:

• Required missing, bad coercion, value outside values=[...] — all are validation failures.
• Type coercion — str → int, str → float, str → bool (case-insensitive true/yes/1/on; false/no/0/off/empty).
• Where failures go — for a LiveComponent, any validation failure raises AssignValidationError when settings.DEBUG=True and logs a warning otherwise (the raw kwargs are kept). For a function component invoked with {% call %} / {% component %}, any failure raises RuntimeError("Component '<name>' validation failed: …") in every mode.
• Inheritance — child-class assigns extend parent's; same-name entries override.

Named Slots

Pass multiple named content blocks (with attributes) into a component. Perfect for tables where the parent defines columns, or any layout where content has distinct regions.

{% call "card" %}
  {% slot header label="Dashboard" %}
    <h3>Today's Metrics</h3>
  {% endslot %}
  {% slot footer %}
    <button>Close</button>
  {% endslot %}
  Main body content here.
{% endcall %}

Inside the component, slots are available as a dict:

@component
def card(assigns):
    header = assigns["slots"].get("header", [{"content": ""}])[0]["content"]
    footer = assigns["slots"].get("footer", [{"content": ""}])[0]["content"]
    body = assigns["children"]  # Non-slot content
    return f"<div class='card'><header>{header}</header>{body}<footer>{footer}</footer></div>"

assigns["slots"] is {name: [slot_dict, ...]} where each slot_dict carries {"attrs": {...}, "content": "..."}. Multiple same-name slots collect into a list. If you declare the slot, declare it Slot("col", multiple=True): a declared slot is single by default, and repeating it raises.

{% slot col label="Name" %}{{ row.name }}{% endslot %}
{% slot col label="Email" %}{{ row.email }}{% endslot %}
{% slot col label="Joined" %}{{ row.joined }}{% endslot %}

yields assigns["slots"]["col"] as a 3-element list. The inline tag {% render_slot slots.col.0 %} emits the content of a slot at a given path — useful when you need to reference a slot inside a rendered loop. {% render_slot slots.col.0.content %} names the body directly and emits the same markup; both are the parent's already-rendered output, so both are emitted live rather than escaped a second time. Any OTHER path — a plain context variable, or a content key on a dict that is not a slot entry — is escaped, because nothing has vouched for it.

Markdown editor

See the Markdown Editor guide for optional Visual/Markdown editing, native form integration, asset loading, theme variables and editing limitations.