View API

Sets up an efficient server-side stream; rows are emitted as insert ops instead of re-rendering the whole list, and cleared from server memory after render. at=-1 appends, at=0 prepends. Pairs with a dj-stream container. dom_id is a callable that derives each row's DOM id — if omitted, djust falls back to item.id, then item.pk, then id(item).

def mount(self, request, **kwargs):
    self.stream('messages', Message.objects.all()[:50])

Adds a single item to an initialised stream. at=-1 appends (default), at=0 prepends. The item's id/pk becomes the DOM element id.

@event_handler()
def add_message(self, text: str = "", **kwargs):
    msg = Message.objects.create(content=text)
    self.stream_insert('messages', msg)

Deletes a row from an initialised stream. Pass the item object or its id; the DOM id is derived from the stream name and item id/pk.

@event_handler()
def delete_message(self, msg_id: int = 0, **kwargs):
    Message.objects.filter(pk=msg_id).delete()
    self.stream_delete('messages', msg_id)

Clears all of a stream's DOM children. If items is given, the stream is repopulated after clearing.

@event_handler()
def refresh(self, **kwargs):
    self.stream_reset('messages', items=Message.objects.all()[:50])

Trims a stream to at most `limit` elements. edge='top' removes from the start, 'bottom' from the end. Used for infinite scroll to keep the DOM bounded.

@event_handler()
def load_more(self, **kwargs):
    self.stream('messages', next_batch, at=-1)
    self.stream_prune('messages', limit=100, edge='top')

Batched (~60fps) streaming update over the WebSocket. If html is given it is sent directly, else the target is re-rendered from context. target defaults to [dj-stream='name'].

@event_handler()
async def stream_response(self, prompt: str = "", **kwargs):
    async for token in llm_stream(prompt):
        self.output += token
        await self.stream_to('output')

Appends (or replaces / prepends) text into the stream target. target defaults to [dj-stream='name']. The workhorse for LLM token streaming.

async def stream_response(self, **kwargs):
    async for chunk in fetch_stream():
        await self.stream_text('output', chunk)

Fires a 'start' op — useful to show a spinner before tokens arrive. target defaults to [dj-stream='name'].

await self.stream_start('output')
self.streaming = True

Fires a 'done' op — useful to clear the loading state once streaming finishes.

await self.stream_done('output')
self.streaming = False

Fires an 'error' op while preserving partial content, so a failure is surfaced without wiping what was already streamed.

try:
    await self.stream_to('output')
except Exception as e:
    await self.stream_error('output', str(e))

Registers the user in the presence group identified by presence_key, with an optional meta dict (name, color, avatar…). No-op during HTTP prerender — only registers under WebSocket. Requires PresenceMixin.

def mount(self, request, **kwargs):
    self.track_presence(meta={'name': request.user.username})

Removes the user from the presence group. Called automatically on disconnect; call manually to leave a room without disconnecting.

@event_handler()
def leave_room(self, **kwargs):
    self.untrack_presence()

Returns the active presence records (each a dict of the meta passed to track_presence). Empty if presence_key isn't set or the backend is unavailable.

def get_context_data(self, **kwargs):
    ctx = super().get_context_data(**kwargs)
    ctx['presences'] = self.list_presences()
    return ctx

Imperative count of active presences. For templates prefer the auto-maintained {{ online_count }} attribute over calling this directly.

ctx['online'] = self.presence_count()

Sends a named event to all active sessions in the presence group; the payload dict is delivered as kwargs to handlers listening for that event.

@event_handler()
def announce(self, message: str = "", **kwargs):
    self.broadcast_to_presence('announcement', {'message': message})

Returns user_id -> cursor data (x, y, timestamp, meta), with stale cursors filtered. Only available on LiveCursorMixin.

ctx['cursors'] = self.get_cursors()

Declares an upload slot referenced as dj-upload='name'. accept filters extensions/MIME types; the input's accept/multiple attrs are set automatically. resumable=True survives WS reconnects. Requires UploadMixin.

def mount(self, request, **kwargs):
    self.allow_upload('avatar', accept='.jpg,.png', max_file_size=5_000_000)

Yields UploadEntry objects (client_name, client_size, file, data) for completed uploads, cleaning up temp files after iteration. Call from the handler that saves the files.

@event_handler()
def save_avatar(self, **kwargs):
    for entry in self.consume_uploaded_entries('avatar'):
        default_storage.save(entry.client_name, entry.file)

Clears form_data, field_errors and form_errors and resets validity. Requires FormMixin.

@event_handler()
def clear(self, **kwargs):
    self.reset_form()

Returns the bound Django form, re-creating it from serialized state when needed. Requires FormMixin.

field = self.form_instance.fields.get('email')

Returns form_data[field_name] or the default. Requires FormMixin.

email = self.get_field_value('email')

Returns the field's error messages, or an empty list. Requires FormMixin.

errors = self.get_field_errors('email')

True if the field currently has validation errors. Requires FormMixin.

{% if has_field_errors('email') %}
  <span class="error">Invalid email</span>
{% endif %}

Queues a notification; level ('success','error','info'…) becomes the CSS class dj-flash-{level}. Flushed to the client after the response. Requires FlashMixin (auto-included).

@event_handler()
def save(self, **kwargs):
    self.put_flash('success', 'Saved!')

Clears all flash messages, or only those of a given level.

self.clear_flash('error')

Dispatches to dj-hook handlers and as a CustomEvent on document; the payload dict becomes event.detail. Use for client-only side effects after a handler.

self.push_event('confetti', {'count': 50})

Runs a djust.js.JSChain on the client for DOM automation (show/hide/add_class/focus/dispatch) with no client hook needed.

from djust.js import JS

self.push_commands(
    JS.add_class('highlight', to='#btn').focus('#btn')
)

After the handler, the client calls .submit() on the matching form (which must carry dj-trigger-action). Used for OAuth or payment handoffs that need a real navigation.

@event_handler()
def checkout(self, **kwargs):
    self.trigger_submit('#payment-form')

Assigning page_title queues a title update over a side-channel — no VDOM diff required. Requires PageMetadataMixin (auto-included).

self.page_title = f'Chat ({self.unread} unread)'

Assigning a dict of name->content queues meta-tag updates (one command per key). Useful for OpenGraph/SEO on a reactive page.

self.page_meta = {'og:title': 'My Article'}

Schedules work to run after the current state flushes to the client, then re-renders on completion. Name tasks to run several concurrently. Requires AsyncWorkMixin (auto-included).

@event_handler()
def generate(self, **kwargs):
    self.generating = True
    self.start_async(self._do_generate, name='gen')

def _do_generate(self):
    self.output = expensive_call()
    self.generating = False

Cancels a scheduled task; if it's already running, its completion re-render is skipped.

@event_handler()
def cancel(self, **kwargs):
    self.cancel_async('gen')
    self.generating = False

Queues a sync callback to run after the render/patch cycle (no further re-render). Good for telemetry or cleanup that shouldn't block the response.

@event_handler()
def track(self, **kwargs):
    self.count += 1
    self.defer(self._record_metric)

Override to derive state from the URL. Called after mount, on live_patch, and on browser back/forward.

def handle_params(self, params, uri):
    self.category = params.get('category', 'all')
    self.page = int(params.get('page', 1))

Updates the browser URL via pushState (or replaceState) and re-renders — but does not remount, so state is preserved. Pairs with handle_params().

@event_handler()
def filter(self, category='all', **kwargs):
    self.category = category
    self.live_patch(params={'category': category, 'page': 1})

Navigates to a different LiveView on the same WebSocket — no full page reload. The old view unmounts and the new one mounts.

@event_handler()
def open_detail(self, item_id=0, **kwargs):
    self.live_redirect(f'/items/{item_id}/')

Navigates to a previously-completed step for editing, skipping validation on the jump. Requires WizardMixin.

@event_handler()
def edit_step(self, step_index: int = 0, **kwargs):
    self.go_to_step(step_index=step_index)

Validates the current step, marks it complete, and advances. Stops at the last step. Requires WizardMixin.

<button dj-click="next_step">Next</button>

Returns to the previous step without validation. Stops at the first step. Requires WizardMixin.

<button dj-click="prev_step">Back</button>

Re-validates every step (guarding against tampering) and calls on_wizard_complete(step_data) when all pass. Requires WizardMixin.

def on_wizard_complete(self, step_data):
    Claim.objects.create(**step_data['personal'])