Datastar

Datastar 1.0 compatibility

The stario.datastar helpers target Datastar version 1.0: attribute names, action strings, signal JSON on the wire, and SSE framing match that release line. Use a 1.0-compatible browser bundle in the page; the default ModuleScript() URL pins v1.0.1 (getting started)—override src= when you load a different build.

The stario.datastar submodule builds data-* attributes, declarative @… action strings, signal payloads, and server-sent events aligned with the upstream Datastar reference. This page is the Python API surface only.

For how this fits hypermedia, CQRS-shaped command/read splits, and Relay fan-out in real apps, read The go-to architecture.

In application code, prefer from stario import datastar as ds (same module as stario.datastar). Apidoc blocks below use the fully qualified stario.datastar.… paths.

The sections below are laid out in roughly that order: Runtime helpers (load Datastar in the document, read signals on the wire, FileSignal), Attributes (dict fragments for data-* on elements), Actions (@get, @post, @peek, … strings on data-on:*), and SSE events (writing Datastar’s event stream through a Writer from your handlers).

The package also re-exports Case, js, and s from stario.datastar.format and JSEvent from the attributes layer. Use them when you build custom attribute values or event payloads; most apps stick to the helpers below and only reach for these when the typed builders are not enough.

Runtime helpers

A small trio on top of the rest of the module. ModuleScript() emits the type="module" <script> that loads Datastar (typically in the document head). read_signals() reads the JSON signals blob Datastar sends on each request (GET and DELETE use the datastar query param; other methods use the body, per Datastar #1146). FileSignal is a typing.TypedDict that describes one nested file object inside that payload when you want static typing (see below)—not a substitute for validation.

ModuleScript(src='https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.1/bundles/datastar.js')

Load the Datastar client (type="module"). Override src only if you self-host.

python

from stario import datastar as ds

from stario.html import HtmlDocument, Head, Body, P

HtmlDocument(Head(ds.ModuleScript()), Body(P("Hello")))

# <!doctype html><html><head><script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.1/bundles/datastar.js"></script></head><body><p>Hello</p></body></html>

async read_signals(req)

Parse the JSON signals blob Datastar sends.

Raises

TypeError: If the decoded JSON value is not an object. json.JSONDecodeError: If the query string or body is not valid JSON.

GET and DELETE use the datastar query parameter; all other methods use the request body, matching upstream Datastar after https://github.com/starfederation/datastar/pull/1146.

Convenience only: this uses the stdlib json module on the raw bytes or query string. Incoming signals are untrusted; validate types, sizes, and nested shapes (Pydantic, msgspec, cattrs, hand-rolled checks, …). We recommend reading await req.body() or req.query.get("datastar", "") directly when you want a schema library to decode and validate from bytes in one step; that is often faster than json.loads into a plain dict through this helper.

python

@app.post("/action")

async def action(c, w):

    sig = await ds.read_signals(c.req)

    n = int(sig.get("n", 0))

    ds.sse.patch_signals(w, {"n": n + 1})

Signal JSON from the client is untrusted. read_signals is only a thin json.loads wrapper over the bytes or query string Stario already exposes—you remain responsible for validating shape, sizes, and file payloads.

Prefer await req.body() or the datastar query value directly when you want decoding and validation in one pass with Pydantic, msgspec, cattrs, or similar; that is often faster than json.loads into a plain dict via this helper.
For a step-by-step app-level pattern (typed reads, thin patch_* helpers), see Reading and writing Datastar signals and No validation layer in the framework.

`FileSignal`

How uploads land in signals is described in the File Uploads section of the Datastar attributes docs (data-bind). FileSignal is not multipart/form-data; it is the nested object (filename, base64 contents, optional mime) Datastar puts under a signal key.

After you read the payload (for example with read_signals above), you can narrow one entry for editors and type checkers. TypedDict is structural only—you still need your own checks before trusting bytes or paths:

python

from stario import Context, Writer, datastar as ds

from stario.datastar import FileSignal

async def avatar_meta(c: Context, w: Writer) -> None:

    payload = await ds.read_signals(c.req)

    f: FileSignal = payload["avatar"]

    # validate name, decode base64 contents, …

JSON shape for that key:

json

{"avatar": {"name": "photo.png", "contents": "<base64>", "mime": "image/png"}}

Attributes

Datastar’s reactive UI is driven by data-* attributes on elements (signals, bindings, event actions, and modifiers). These helpers return small dict fragments—usually dict[str, str]. Pass them as the first arguments to a Stario tag (before any children), along with any extra attribute dicts you need; the tag merges those mappings into the element so the client sees the same names and values the upstream docs describe.

Authoritative names, modifier syntax, and behavior live in the Datastar attributes reference. Helpers that target one key vs many use the singular names (attr, class_, computed, style) versus the plural ones (attrs, classes, computeds, styles). For signals, signal sets a namespaced data-signals:<key> entry; signals sets the data-signals attribute to a serialized JSON object (see stario.datastar helpers’ docstrings for __ifmissing variants).

ModuleScript() uses DATASTAR_CDN_URL as its default src (the compatibility note at the top of this page describes the pin); override src= when self-hosting.

Some helpers correspond to Datastar Pro attributes: they emit the same data-* names as upstream, but the open-source browser bundle ignores them unless Pro is enabled. Use them only when your client includes Pro.

attr(key, expression)

Set one HTML attribute from a reactive expression.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-attr>

python

h.Div(ds.attr("title", "$item.label"), {"class": "tooltip"})

# <div data-attr:title="$item.label" class="tooltip"></div>

attrs(mapping)

Set several HTML attributes at once from reactive expressions.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-attr>

python

h.Aside(ds.attrs({"open": "sidebarOpen"}), {"class": "drawer"})

# <aside data-attr="{&#x27;open&#x27;:sidebarOpen}" class="drawer"></aside>

bind(signal_name, *, case=None, prop=None, event=None)

data-bind — two-way bind a signal to an input or similar.

Uses :func:~stario.datastar.format.to_kebab_key for the attribute key. Value form is data-bind="signal"; key forms use data-bind:key...="signal" (same identifier as the value).

Official Datastar docs: <https://data-star.dev/reference/attributes#data-bind>

python

h.Input(ds.bind("email"), {"type": "email", "class": "input input-bordered"})

# <input data-bind="email" type="email" class="input input-bordered"/>

h.Input(ds.bind("isChecked", prop="checked", event="change"))

# <input data-bind:is-checked__prop.checked__event.change="isChecked" />

h.Input(ds.bind("mySignal", case="kebab"))

# <input data-bind:my-signal__case.kebab="mySignal" />

class_(name, expression)

Toggle one CSS class from a reactive expression.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-class>

python

h.Div(ds.class_("hidden", "!$expanded"))

# <div data-class:hidden="!$expanded"></div>

classes(mapping)

Toggle several CSS classes at once from reactive expressions.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-class>

python

h.Ul(ds.classes({"loading": "$pending", "text-error": "$error != null"}))

# <ul data-class="{&#x27;loading&#x27;:$pending,&#x27;text-error&#x27;:$error != null}"></ul>

computed(key, expression)

Create one computed signal from a reactive expression.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-computed>

python

h.Span(ds.computed("fullName", "$first + ' ' + $last"))

# <span data-computed:full-name="$first + &#x27; &#x27; + $last"></span>

computeds(mapping)

Create several computed signals at once from a mapping of expressions.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-computed>

python

h.Div(ds.computeds({"fullName": "$first + ' ' + $last", "initials": "$first[0]"}))

# <div data-computed:full-name="$first + &#x27; &#x27; + $last" data-computed:initials__case.kebab="$first[0]"></div>

effect(expression)

Run a client-side side effect when the element is initialized or updated.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-effect>

python

h.Div(ds.effect("el.querySelector('input')?.focus()"))

# <div data-effect="el.querySelector(&#x27;input&#x27;)?.focus()"></div>

ignore(self_only=False)

Tell Datastar to ignore this element or its whole subtree during processing.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-ignore>

python

h.Div(ds.ignore(), h.P("Third-party widget root"))

# <div data-ignore><p>Third-party widget root</p></div>

ignore_morph()

Prevent Datastar morphing from changing this element and its descendants.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-ignore-morph>

python

h.Textarea(ds.ignore_morph(), {"name": "notes"})

# <textarea data-ignore-morph name="notes"></textarea>

indicator(signal_name)

Track in-flight fetch state in a signal for loading indicators and disabled UI.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-indicator>

python

h.Span(ds.indicator("saving"), "Saving…")

# <span data-indicator="saving">Saving…</span>

init(expression, *, delay=None, viewtransition=False)

Run a client expression when the element is initialized in the DOM.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-init>

python

h.Div(ds.init("$focusFirstInput(el)"), {"id": "form-shell"})

# <div data-init="$focusFirstInput(el)" id="form-shell"></div>

h.Div(ds.init("loadMore()", delay="200ms"), {"id": "infinite-sentinel"})

# <div data-init__delay.200ms="loadMore()" id="infinite-sentinel"></div>

json_signals(*, include=None, exclude=None, terse=False)

Control how signals are serialized for inspection with optional include/exclude filters.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-json-signals>

python

h.Form(ds.json_signals(include=["email", "password"]), {"action": "/login", "method": "post"})

# <form data-json-signals="{&#x27;include&#x27;:&#x27;email|password&#x27;}" action="/login" method="post"></form>

on(event, expression, *, once=False, passive=False, capture=False, delay=None, debounce=None, throttle=None, viewtransition=False, window=False, outside=False, prevent=False, stop=False)

Listen for DOM or window events and run a Datastar expression.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-on>

python

h.Button(ds.on("click", ds.get("/cart/count")), {"type": "button", "class": "btn"})

# <button data-on:click="@get(&#x27;/cart/count&#x27;)" type="button" class="btn"></button>

h.Input(ds.on("keydown", "$query = el.value", debounce=("150ms", "leading")))

# <input data-on:keydown__debounce.150ms.leading="$query = el.value"/>

on_intersect(expression, *, threshold=None, once=False, full=False, delay=None, debounce=None, throttle=None)

data-on-intersect — Intersection Observer → expression.

Matches the data-on-intersect modifiers: __threshold, __delay, __debounce, __throttle, plus once and full as in the reference example (modifier order: threshold, then once / full, then timing modifiers).

Official Datastar docs: <https://data-star.dev/reference/attributes#data-on-intersect>

python

h.Div(ds.on_intersect("@get('/feed?cursor=' + $cursor)", once=True), {"id": "sentinel"})

# <div data-on-intersect__once="@get(&#x27;/feed?cursor=&#x27; + $cursor)" id="sentinel"></div>

h.Div(ds.on_intersect("$loaded = true", threshold=0.25, once=True, full=True))

# <div data-on-intersect__threshold.25__once__full="$loaded = true"></div>

on_interval(expression, *, duration='1s', viewtransition=False)

Run a client expression on an interval, optionally with a custom duration.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-on-interval>

python

h.Div(ds.on_interval("$pollInbox()", duration="5s"))

# <div data-on-interval__duration.5s="$pollInbox()"></div>

on_signal_patch(expression, *, delay=None, debounce=None, throttle=None, include=None, exclude=None)

React to signal patch events, optionally filtered to specific signals.

Official Datastar docs: <https://data-star.dev/reference/attributes#data-on-signal-patch>

python

h.Div(ds.on_signal_patch("@post('/autosave')", debounce="500ms", include=["draft"]))

# <div data-on-signal-patch__debounce.500ms="@post(&#x27;/autosave&#x27;)" data-on-signal-patch-filter="{&#x27;include&#x27;:&#x27;draft&#x27;}"></div>