View API reference

Signature

stream(name, items, dom_id=None, at=-1, reset=False, limit=None)

Returns

Stream

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])

Signature

stream_insert(name, item, at=-1)

Returns

None

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)

Signature

stream_delete(name, item_or_id)

Returns

None

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)

Signature

stream_reset(name, items=None)

Returns

None

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])

Signature

stream_prune(name, limit, edge='top')

Returns

None

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')

Signature

async stream_to(stream_name, target=None, html=None)

Returns

None

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')

Signature

async stream_text(name, text, mode='append', target=None)

Returns

None

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)

Signature

async stream_start(name, target=None)

Returns

None

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

Signature

async stream_done(name, target=None)

Returns

None

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

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

Signature

async stream_error(name, error, target=None)

Returns

None

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))

Signature

track_presence(meta=None)

Returns

None

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})

Signature

untrack_presence()

Returns

None

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()

Signature

list_presences()

Returns

list[dict]

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

Signature

presence_count()

Returns

int

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

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

Signature

broadcast_to_presence(event, payload=None)

Returns

None

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})

Signature

get_cursors()

Returns

dict

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

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

Signature

allow_upload(name, accept='', max_entries=1, max_file_size=10_000_000, resumable=False)

Returns

UploadConfig

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)

Signature

consume_uploaded_entries(name)

Returns

generator[UploadEntry]

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)

Signature

reset_form()

Returns

None

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

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

Signature

form_instance (property)

Returns

forms.Form

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

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

Signature

get_field_value(field_name, default='')

Returns

Any

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

email = self.get_field_value('email')

Signature

get_field_errors(field_name)

Returns

list[str]

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

errors = self.get_field_errors('email')

Signature

has_field_errors(field_name)

Returns

bool

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

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

Signature

put_flash(level, message)

Returns

None

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!')

Signature

clear_flash(level=None)

Returns

None

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

self.clear_flash('error')

Signature

push_event(event, payload=None)

Returns

None

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})

Signature

push_commands(chain)

Returns

None

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')
)

Signature

trigger_submit(selector)

Returns

None

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')

Signature

page_title (property)

Returns

str

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)'

Signature

page_meta (property)

Returns

dict

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'}

Signature

start_async(callback, *args, name=None, **kwargs)

Returns

None

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

Signature

cancel_async(name)

Returns

None

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

Signature

defer(callback, *args, **kwargs)

Returns

None

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)

Signature

handle_params(params, uri)

Returns

None

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))

Signature

live_patch(params=None, path=None, replace=False)

Returns

None

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})

Signature

live_redirect(path, params=None, replace=False)

Returns

None

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}/')

Signature

go_to_step(step_index=0)

Returns

None

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)

Signature

next_step()

Returns

None

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

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

Signature

prev_step()

Returns

None

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

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

Signature

submit_wizard()

Returns

None

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'])

Signature

JS.show(to=None, *, inner=None, closest=None, display=None, transition=None, time=None)

Returns

None

Starts (or continues) a chain that makes the target visible client-side. Optional display= sets an explicit display value; transition=/time= apply a CSS class for the duration. Dispatches a djust:show CustomEvent on each target.

self.open_modal = JS.show("#modal").add_class("open", to="#overlay").focus("#modal-title")

<button dj-click="{{ open_modal }}">Open</button>

Signature

JS.hide(to=None, *, inner=None, closest=None, transition=None, time=None)

Returns

None

The closest= targeting makes reusable close buttons: the same button works inside every modal with no per-instance IDs. Dispatches djust:hide on each target.

<div class="modal">
    <button dj-click="{{ JS.hide(closest='.modal') }}">Close</button>
</div>

Signature

JS.toggle(to=None, *, inner=None, closest=None, display=None)

Returns

None

Checks computed display (and the hidden attribute) and flips it — the one-liner dropdown.

<div>
    <button dj-click="{{ JS.toggle(inner='.menu') }}">Menu</button>
    <nav class="menu" style="display:none">…</nav>
</div>

Signature

JS.add_class(names, *, to=None, inner=None, closest=None)

Returns

None

Pairs with JS.remove_class() for manual class control; for timed classes use JS.transition().

self.mark = JS.add_class("selected ring-2", closest=".card")

Signature

JS.remove_class(names, *, to=None, inner=None, closest=None)

Returns

None

The inverse of JS.add_class(); chain both to move a class between elements in one click.

self.activate = JS.remove_class("active", to=".tab").add_class("active")

Signature

JS.transition(names, *, to=None, inner=None, closest=None, time=200)

Returns

None

The animation primitive: add the class, wait time= ms for the CSS animation, remove it again.

self.saved = JS.transition("flash-green", time=400, to="#status")

Signature

JS.set_attr(name, value, *, to=None, inner=None, closest=None)

Returns

None

Useful for ARIA state that should update at click-time latency, ahead of the server render.

self.expand = JS.set_attr("aria-expanded", "true").show(inner=".panel")

Signature

JS.remove_attr(name, *, to=None, inner=None, closest=None)

Returns

None

The inverse of JS.set_attr() — e.g. drop disabled the instant the user acts.

self.unlock = JS.remove_attr("disabled", to="#submit")

Signature

JS.focus(to=None, *, inner=None, closest=None)

Returns

None

Focuses the first matched target; chain it after JS.show() so the revealed input is ready to type into.

self.search = JS.show("#search").focus("#search-input")

Signature

JS.dispatch(event, *, to=None, inner=None, closest=None, detail=None, bubbles=True)

Returns

None

The bridge to any third-party code already listening for DOM events — pass a payload via detail=.

self.notify = JS.dispatch("cart:updated", to="#cart", detail={"count": 3})

Signature

JS.push(event, *, value=None, target=None, page_loading=False)

Returns

None

The escape hatch back to the server: rides the normal event pipeline (debouncing, rate limiting, WebSocket/HTTP fallback). Enables optimistic UI — do the instant DOM work client-side, then tell the server. page_loading=True drives the page loading bar while the event is in flight.

self.place_order = (JS.hide("#checkout-modal")
                      .push("submit_order", value={"cart_id": self.cart_id}))

Signature

JS.ext.<name>(to=None, *, inner=None, closest=None, **params)

Returns

None

Opens the command set (djust 1.1+): any snake_case name under JS.ext serializes as a namespaced ext.<name> op and dispatches to the matching window.djust.commands.register() implementation — clipboard, scroll, confetti, or a wrapper around any third-party library action. Chainable with built-ins, same targeting kwargs, structurally collision-proof against future built-ins. Built-ins stay strict (JS.shwo raises AttributeError at mount); an unregistered custom command fails loud on first use (DEBUG error overlay with a did-you-mean hint).

self.copy_link = (JS.ext.clipboard_copy(text=self.share_url)
                    .add_class("copied")
                    .transition("pulse", time=400))

<button dj-click="{{ copy_link }}">Copy link</button>

Signature

register(name, fn) // fn(targets, args, originEl)

Returns

None

The client half of JS.ext (djust 1.1+): register once in your own static JS — no build step, CSP-safe (no eval). The implementation receives the already-resolved target element list (same to/inner/closest rules as built-ins), the op args, and the origin element; a returned Promise is awaited before the next op in the chain runs. Registering a name that collides with a built-in throws immediately.

window.djust.commands.register('clipboard_copy', (targets, args) => {
    navigator.clipboard.writeText(args.text);
});

window.djust.commands.register('fade_out', (targets) =>
    Promise.all(targets.map(el =>
        el.animate({opacity: [1, 0]}, 250).finished))
);
// Python: JS.ext.fade_out(closest='.row').hide(closest='.row').push('dismiss')
// the fade COMPLETES before the hide and the server push run