Datastar

stario.datastar is the Python side of the Datastar browser client. You emit data-* attributes with data, write @ actions with at, read what the page sent with read_signals, and push updates with SSE. Attribute names and client behaviour are Datastar's; the upstream reference is the authority on those. This page is the Python surface.

from stario.datastar import SSE, FileSignal, ModuleScript, at, data, read_signals

Signal names use Python snake_case on the wire. Nested state goes in nested JSON objects, not dotted keys.

Loading the client#

ModuleScript() returns the <script type="module"> that loads Datastar. Put it in <head>. It defaults to a pinned CDN build. Pass src= to self-host, which you should do in production.

from stario.datastar import ModuleScript

from stario.markup import html as h

h.Head(ModuleScript())

Attributes#

data is the stock DatastarAttributes instance. Each method returns an Attrs fragment: pre-rendered attribute text you pass to a tag like any other attribute, before the children.

from stario import Route

from stario.datastar import at, data

from stario import h

ADD = Route("POST /cart")

h.Button(data.on("click", at.post(ADD.href())), "Add")

h.Input(data.bind("email"), {"type": "email"})

Singular helpers (attr, class_, style, signal, computed) set one key. Plural helpers (attrs, classes, styles, signals, computeds) set several at once. Options use None to omit a key and let the client apply its default.

A custom Datastar bundle with another prefix needs another instance: DatastarAttributes("data-star-").

Hold state#

Signals are the page's state. signals sets several, with if_missing=True to keep values the client already holds. bind ties a form field to a signal in both directions. computed derives one signal from others. ref names an element so expressions can reach it.

data.signals({"count": 0, "open": False})

# Attrs(" data-signals='{"count":0,"open":false}'")

data.signal("my_count", "0", if_missing=True)

# Attrs(' data-signals:my-count__case.snake__ifmissing="0"')

data.bind("email")

# Attrs(' data-bind="email"')

data.bind("is_checked", prop="checked", event="change")

# Attrs(' data-bind:is-checked__case.snake__prop.checked__event.change')

data.computed("full_name", "$first + $last")

# Attrs(' data-computed:full-name__case.snake="$first + $last"')

data.computeds({"full_name": "$a", "initials": "$b"})

# Attrs(' data-computed:full-name__case.snake="$a" data-computed:initials__case.snake="$b"')

data.json_signals()

# Attrs(' data-json-signals')

data.json_signals(include=["email", "password"], terse=True)

# Attrs(' data-json-signals__terse="{'include':'email|password'}"')

data.ref("search_input")

# Attrs(' data-ref="search_input"')

Show state#

These bind an element's text, visibility, classes, styles, or attributes to an expression. indicator sets a boolean signal to true while a request from this element is in flight.

data.text("$greeting")

# Attrs(' data-text="$greeting"')

data.show("$error != null")

# Attrs(' data-show="$error != null"')

data.class_("hidden", "!$expanded")

# Attrs(' data-class:hidden="!$expanded"')

data.classes({"loading": "$pending"})

# Attrs(' data-class="{'loading':$pending}"')

data.style("width", "$pct + '%'")

# Attrs(' data-style:width="$pct + '%'"')

data.styles({"opacity": "$visible ? '1' : '0'"})

# Attrs(' data-style="{'opacity':$visible ? '1' : '0'}"')

data.attr("title", "$item.label")

# Attrs(' data-attr:title="$item.label"')

data.attrs({"open": "sidebarOpen"})

# Attrs(' data-attr="{'open':sidebarOpen}"')

data.indicator("saving")

# Attrs(' data-indicator="saving"')

React to events#

on runs an expression on a DOM event; the expression is usually an at.* action. init runs once when the element mounts, which is where a page opens its subscribe stream. effect re-runs when the signals it reads change. The on_* helpers cover intersection, intervals, and signal patches.

data.on("click", "@get('/cart/count')")

# Attrs(' data-on:click="@get('/cart/count')"')

data.on("click", "$open = false", target="outside")

# Attrs(' data-on:click__outside="$open = false"')

data.init("setup()")

# Attrs(' data-init="setup()"')

data.init("setup()", delay="200ms", view_transition=True)

# Attrs(' data-init__delay.200ms__viewtransition="setup()"')

data.effect("el.focus()")

# Attrs(' data-effect="el.focus()"')

data.on_intersect("load()", threshold=0.25, once=True, view_transition=True)

# Attrs(' data-on-intersect__threshold.25__once__viewtransition="load()"')

data.on_interval("tick()")

# Attrs(' data-on-interval="tick()"')

data.on_interval("tick()", duration="2s", leading=True)

# Attrs(' data-on-interval__duration.2s.leading="tick()"')

data.on_signal_patch("save()", debounce="500ms", include=["draft"])

# Attrs(' data-on-signal-patch__debounce.500ms="save()" data-on-signal-patch-filter="{'include':'draft'}"')

Control the morph#

When the server patches HTML, Datastar morphs it into the live tree. These attributes tell the morph to leave an element alone or to keep one attribute as the browser has it.

data.ignore()

# Attrs(' data-ignore')

data.ignore(self_only=True)

# Attrs(' data-ignore__self')

data.ignore_morph()

# Attrs(' data-ignore-morph')

data.preserve_attr(["data-testid", "id"])

# Attrs(' data-preserve-attr="data-testid id"')

Datastar Pro#

These helpers emit the same attribute names as upstream Datastar Pro. The open-source bundle ignores them.

data.animate("$x")

# Attrs(' data-animate="$x"')

data.custom_validity("$msg")

# Attrs(' data-custom-validity="$msg"')

data.match_media("is_dark", "'prefers-color-scheme: dark'")

# Attrs(' data-match-media:is-dark__case.snake="'prefers-color-scheme: dark'"')

data.on_raf("draw()", throttle="100ms")

# Attrs(' data-on-raf__throttle.100ms="draw()"')

data.on_resize("layout()", debounce="50ms", throttle="100ms")

# Attrs(' data-on-resize__debounce.50ms__throttle.100ms="layout()"')

data.persist(include="draft", storage_key="prefs", session=True)

# Attrs(' data-persist:prefs__session="{'include':'draft'}"')

data.query_string(include="page", history=True)

# Attrs(' data-query-string__history="{'include':'page'}"')

data.replace_url("`/page/${$page}`")

# Attrs(' data-replace-url="`/page/${$page}`"')

data.scroll_into_view(behavior="smooth", vertical="center", focus=True)

# Attrs(' data-scroll-into-view__smooth__vcenter__focus')

data.view_transition("$id")

# Attrs(' data-view-transition="$id"')

Actions#

at is the stock DatastarActions instance. Each method returns an action string such as @post('/cart'), which you place inside data.on(...) or data.init(...). Build the URL with route.href(); query and fragment belong on href(), not on the action.

Requests#

get, post, put, patch, delete, and query share one set of options: which signals to send, a selector for form content, extra headers, retry, and request cancellation. The response is an SSE stream that Datastar applies to the page. Values in payload are JavaScript expressions; wrap literal text with string_literal() from stario.datastar.format.

h.Button(data.on("click", at.get("/items", {"q": "$query"})), "Search")

Signals in the browser#

These act on signals without a request.

Datastar Pro#

Reading what the page sent#

Every Datastar request carries the page's signals as one JSON object. read_signals(req) returns it as a dict. GET and DELETE carry it in the datastar query parameter; other methods carry it in the body. Treat the result as untrusted input. Parsing goes through stario.json.

A file input bound with data.bind arrives as a signal too, not as multipart/form-data. FileSignal is the TypedDict for one such value: name, base64 contents, and mime, which may be None.

from stario.datastar import FileSignal, read_signals

async def upload(c, w):

    signals = await read_signals(c.req)

    avatar: FileSignal = signals["avatar"]

from stario import Route

from stario.datastar import SSE, read_signals

ACTION = Route("POST", "/action")

async def action(c, w):

    sig = await read_signals(c.req)

    SSE(w).patch_signals({"n": int(sig.get("n", 0)) + 1})

SSE#

SSE(w) binds the Datastar event stream to one Writer. Create one per response. Each method appends one event. The first event sends the text/event-stream headers; call open() to send them earlier. Do not start an SSE stream on a writer that has already sent a response, and do not call a w.* response method after it.

from stario.datastar import SSE, read_signals

async def increment(c, w):

    signals = await read_signals(c.req)

    sse = SSE(w)

    sse.patch_signals({"count": int(signals.get("count", 0)) + 1})

patch_elements accepts bytes, text, or a markup tree. mode defaults to outer, which morphs the matched element. The others are inner, replace, prepend, append, before, and after. Without selector, elements match by id. navigate moves the browser from inside a stream by sending a short script, the same way the official Datastar client SDKs redirect. A 3xx status on a Datastar request does not navigate: fetch follows it and Datastar morphs the final page into the current one. Use w.redirect only for requests the browser itself makes, such as a plain form post. execute_script streams JavaScript you wrote; never interpolate user input into it.

By the way#

• stario.datastar.format holds the wire helpers Case, js_object, and string_literal. js_object treats string values as JavaScript expressions.

• JSEvent is a type hint for the event names data.on accepts. At runtime any string works.

• ContentType, RequestCancellation, and Retry are Literal aliases in stario.datastar.actions.

See also: the Datastar from Python how-to for the common patterns, and Live pages for why a page holds one stream open.