reference

JS command reference

Build browser interactions in Python: signatures, targeting, and examples.

On this page

Build a chain in Python and bind it to a template event. DOM operations run in the browser; push() adds a server event to the chain.

Build and bind a command

from djust.js import JS

def mount(self, request, **kwargs):
    self.open_panel = JS.show("#panel").focus("#panel-title")

<button dj-click="{{ open_panel }}">Open panel</button>
<section id="panel" style="display: none">
  <h2 id="panel-title" tabindex="-1">Details</h2>
</section>

Targeting and chaining

For DOM commands, use one of to=, inner=, or closest= to select a target. Without a target, the event's originating element is used. push() instead accepts a server event and an optional component target.

Each operation returns a new chain, so an existing chain can be reused. The Python builder uses add_class() and set_attr(); the direct browser API uses addClass() and setAttr(). See the JS commands guide for browser calls, transitions, and extensions.

Commands

`add_class`

Add one or more space-separated CSS class names to the target.

JS.add_class(
    names: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
) -> "'JSChain'"

`dispatch`

Fire a CustomEvent with the given name on the target.

JS.dispatch(
    event: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
    detail: 'Optional[Dict[str, Any]]' = None,
    bubbles: 'bool' = True,
) -> "'JSChain'"

`ext`

Dynamic factory for user-registered custom commands (ADR-025).

chain.ext.scroll_to(to="#top", smooth=True) appends the op ["ext.scroll_to", {"to": "#top", "smooth": true}]. The command implementation is registered client-side via window.djust.commands.register('scroll_to', fn); an op whose name was never registered fails on first invocation with a DEBUG error overlay (and console.error in production).

Built-in names are blocked (JS.ext.show raises AttributeError) — use the strictly-typed built-in instead.

`focus`

Move keyboard focus to the target element.

JS.focus(
    to: 'Optional[str]' = None,
    *,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
) -> "'JSChain'"

`hide`

Set the target element's display to none.

JS.hide(
    to: 'Optional[str]' = None,
    *,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
    transition: 'Optional[str]' = None,
    time: 'Optional[int]' = None,
) -> "'JSChain'"

`push`

Send a server event as part of a JS command chain.

This is the bridge between client-only JS Commands (fast, local) and server round-trips — use it when you need to mix "optimistically close the modal, then tell the server the user saved the form" in a single click handler.

page_loading=True shows the navigation-level loading bar (dj-page-loading elements) while the event is in flight.

JS.push(
    event: 'str',
    *,
    value: 'Optional[Dict[str, Any]]' = None,
    target: 'Optional[str]' = None,
    page_loading: 'bool' = False,
) -> "'JSChain'"

`remove_attr`

Remove an HTML attribute from the target element.

JS.remove_attr(
    name: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
) -> "'JSChain'"

`remove_class`

Remove one or more space-separated CSS class names from the target.

JS.remove_class(
    names: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
) -> "'JSChain'"

`set_attr`

Set an HTML attribute on the target element.

JS.set_attr(
    name: 'str',
    value: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
) -> "'JSChain'"

`show`

Set the target element's display to display (default block).

JS.show(
    to: 'Optional[str]' = None,
    *,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
    display: 'Optional[str]' = None,
    transition: 'Optional[str]' = None,
    time: 'Optional[int]' = None,
) -> "'JSChain'"

`toggle`

Toggle the target element between hidden and shown.

JS.toggle(
    to: 'Optional[str]' = None,
    *,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
    display: 'Optional[str]' = None,
) -> "'JSChain'"

`transition`

Apply names as CSS classes for time ms, then remove them.

Used to trigger CSS transitions — e.g. JS.transition("fade-in", time=300) adds the fade-in class, waits 300 ms for the animation, then removes it again.

JS.transition(
    names: 'str',
    *,
    to: 'Optional[str]' = None,
    inner: 'Optional[str]' = None,
    closest: 'Optional[str]' = None,
    time: 'int' = 200,
) -> "'JSChain'"