# Components API Reference
## `class Component`
Base class for stateless components — no events, no lifecycle, just rendering.
```python
from djust.components.base import Component
```
### Methods
#### `__init__(**kwargs)`
Pass initial values as keyword arguments. Call `super().__init__(**kwargs)`.
#### `get_context_data() -> dict`
Return template context. Override to provide data to the template.
#### `render() -> str`
Renders the component to an HTML string. Called automatically by `__str__()`.
**Usage:**
```python
class Badge(Component):
template = '{{ label }}'
def __init__(self, label: str, variant: str = "primary"):
super().__init__(label=label, variant=variant)
self.label = label
self.variant = variant
def get_context_data(self):
return {"label": self.label, "variant": self.variant}
```
In a LiveView:
```python
def mount(self, request, **kwargs):
self.status_badge = Badge("Active", variant="success")
def get_context_data(self, **kwargs):
return {"status_badge": self.status_badge}
```
In the template: `{{ status_badge }}` (calls `render()` via `__str__()`). Add `|safe` (`{{ status_badge|safe }}`) until [#2501](https://github.com/djust-org/djust/issues/2501)'s escaping fix lands — without it the markup renders as literal text.
---
## `class LiveComponent`
Stateful component with its own mount/render lifecycle and event handlers.
```python
from djust.components.base import LiveComponent
```
### Class Attributes
| Attribute | Type | Description |
| --------------- | ----- | ----------------------- |
| `template` | `str` | Inline HTML template |
| `template_name` | `str` | Path to a template file |
### Abstract Methods (must implement)
#### `mount(**kwargs)`
Called once when the component is first rendered. Initialize all state here.
```python
def mount(self, **kwargs):
self.count = kwargs.get("initial", 0)
```
#### `get_context_data() -> dict`
Return template context. Called before every render.
```python
def get_context_data(self):
return {"count": self.count}
```
### Instance Methods
#### `trigger_update()`
Re-render this component and push the diff to the client. Call after changing state in an event handler.
#### `send_parent(event, data=None)`
Send an event to the parent LiveView.
**Parameters:**
- `event` (`str`) — Event name string
- `data` (`dict`, optional) — Event payload
The parent receives it via `handle_component_event()`.
### Critical Template Rule
Put `data-component-id="{{ component_id }}"` on the component's root element. The client walks up from the element that fired the event to the nearest `data-component-id`, so events from any descendant are routed to the component. Without it, events route to the parent LiveView:
```html
", "badge": "3"},
],
active="tab1",
)
# Methods:
self.tabs.activate_tab("tab2")
```
### `TableComponent`
```python
from djust.components import TableComponent
self.table = TableComponent(
columns=[
{"key": "name", "label": "Name", "sortable": True},
{"key": "email", "label": "Email"},
],
rows=[
{"name": "Alice", "email": "alice@example.com"},
],
striped=True,
hoverable=True,
)
```
A `sortable` column header carries `aria-sort` (`none` / `ascending` /
`descending`) and a visual mark in the framework's icon convention —
Bootstrap Icons classes on `bootstrap5` (`bi-arrow-down-up`, `bi-caret-up-fill`,
`bi-caret-down-fill`; load the Bootstrap Icons stylesheet), the vendored
heroicons SVG on `tailwind`, and `⇅` / `▲` / `▼` on `plain`.
`selectable=True` adds a checkbox per row and one in the header. A row is
identified by its `row_key` value (default `"id"`), stored as a string in
`selected_rows` — the same convention as `{% data_table %}`:
```python
self.table = TableComponent(columns=..., rows=..., selectable=True, row_key="id")
# after the user ticks two rows:
self.table.selected_rows # ["3", "7"]
```
The row checkbox toggles that row (`toggle_row`); the header checkbox selects
every **visible** row, or clears the selection when every visible row is
already selected (`toggle_all`).
`filterable=True` adds a global filter input above the table: rows stay visible
when **any** column's string value contains the query, case-insensitively.
`{"filterable": True}` on a column adds a filter input under that header that
narrows on that column alone. Both compose (every filter must match), and they
compose with the sort: rows are filtered, then sorted. The rows you passed are
never narrowed — clearing an input restores them. The conventions mirror
`{% data_table %}` / `DataTableMixin` (`icontains`, an empty value removes the
filter, select-all is the post-filter set):
```python
self.table = TableComponent(
columns=[
{"key": "name", "label": "Name", "sortable": True, "filterable": True},
{"key": "email", "label": "Email"},
],
rows=...,
filterable=True,
)
# after the user types:
self.table.filter_query # "ali" — the global input (filter_rows)
self.table.column_filters # {"name": "al"} — per column (filter_column)
```
The inputs are `dj-input` controls debounced at 300 ms (`dj-debounce="300"`),
routed to the component with `data-component-id`, and labelled
(`aria-label="Search table"` / `aria-label="Filter