API reference

Datastar Kit exposes a small root API plus explicit subpaths for low-level protocol and JSX runtime integration.

Most application code imports response namespaces and Datastar authoring helpers from the root package:

tsx

import { event, get, js, mod, post, read, reply, state } from "datastar-kit"

TSX consumers should also set:

json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "datastar-kit"
  }
}

Datastar authoring helpers

The root package exports helpers for action expressions, signal refs, typed signal state, and expression serialization. Write Datastar attributes directly in TSX with native data-* names.

State and signals

API	Use
`state(defaults)`	Create typed leaf refs, frozen defaults, partial patches, and reset payloads.
`signal(name)`	Create a standalone typed signal ref.
`local(name)`	Create an underscore-prefixed local/private signal ref.

Actions

API	Use
`get(url, options?)`	Build `@get(...)`.
`post(url, options?)`	Build `@post(...)`.
`put(url, options?)`	Build `@put(...)`.
`patch(url, options?)`	Build `@patch(...)`.
`del(url, options?)`	Build `@delete(...)`.
`peek(callable)`	Build `@peek(...)`.
`setAll(value, filter?)`	Build `@setAll(...)`.
`toggleAll(filter?)`	Build `@toggleAll(...)`.
`queryUrl(path, params)`	Build a reactive URL expression with encoded query params.
`action(name, ...args)`	Call an app-defined or Datastar built-in browser action.
`preserve(name, ...names)`	Build a `data-preserve-attr` space-separated attribute-name list.

Fetch action options include headers, contentType, filterSignals, payload, retry settings, and request cancellation behavior.

Use mod(value, modifiers) when a value-bearing Datastar attribute needs __modifier suffixes. For valueless presence attributes, such as data-ignore__self, use the one-argument form: data-ignore={mod({ self: true })}.

Datastar attributes in TSX

Use native Datastar attributes directly:

tsx

<form
  data-signals={mod(form.defaults, { ifMissing: true })}
  data-on:submit={mod(post("/signup"), { prevent: true })}
>
  <input data-bind={form.refs.email} />
  <small
    data-show={form.refs.errors.email}
    data-text={form.refs.errors.email}
  />
</form>

When a Datastar attribute needs modifiers, wrap the value with mod(value, modifiers):

tsx

<input data-on:input={mod(get("/search"), { debounce: "200ms" })} />

Use helpers for Datastar attributes that are defined as space-separated strings. For example, data-preserve-attr={preserve("open", "class")} builds the correct "open class" value.

Expressions

API	Use
`js`	Tagged template for Datastar expressions with safe serialization of refs and literals.
`regex(...)`	Build a regular expression expression value.
`RegexExpressionError`	Thrown when regex pattern or flags cannot create a `RegExp`.

JSX attributes use semantic expression types rather than one universal expression union. Effect sites require DatastarEffectExpression; text sites use DatastarTextExpression; truthy sites use DatastarTruthyExpression; and dynamic attributes and styles use DatastarAttributeExpression and DatastarStyleExpression. Static signal filters accept structured filter objects or raw strings, not reactive expressions. Raw strings remain an escape hatch, and extracted js(...) expressions can declare their result with js<T>(...).

`read`

read contains request-boundary helpers.

API	Use
`read.signals(request)`	Decode Datastar JSON signal state from a native `Request`.
`read.SignalParseError`	Thrown when signal payload JSON cannot be parsed.
`read.SignalShapeError`	Thrown when parsed signals are not a JSON object signal tree.

GET and DELETE actions read the datastar query parameter. Other methods read the request body as JSON.

`reply`

reply returns native Response objects.

API	Status	Use
`reply.page(body, options?, init?)`	caller-defined	Render a full HTML document.
`reply.patch(elements, options?, init?)`	`200`	Return one SSE element patch.
`reply.signals(value, options?, init?)`	`200`	Return one SSE signal patch.
`reply.stream(events, options?, init?)`	`200`	Return an SSE stream from chunks, iterables, async iterables, or a `ReadableStream`.
`reply.done(init?)`	`204`	Complete a command with no body.
`reply.navigate(url, options?, init?)`	`200`	Navigate through a safe Datastar direct script response.
`reply.directHtml(html, options?, init?)`	`200`	Direct-response HTML escape hatch.
`reply.directSignals(value, options?, init?)`	`200`	Direct-response JSON signal escape hatch.
`reply.directScript(script, options?, init?)`	`200`	Trusted direct-response JavaScript escape hatch.

Datastar action response helpers own their protocol status codes, so their native init type does not accept status or statusText. Use reply.page(...) or a plain Response for ordinary HTTP status semantics.

reply.NavigationUrlError is thrown when navigation URLs are malformed, unsafe, or disallowed by the provided navigation options.

`event`

event returns framed SSE chunks for reply.stream(...).

API	Use
`event.patch(elements, options?)`	Render HTML and encode one `datastar-patch-elements` event.
`event.signals(value, options?)`	Encode one `datastar-patch-signals` event.
`event.navigate(url, options?)`	Encode a safe navigation event.
`event.script(code, options?)`	Encode trusted JavaScript execution.
`event.comment(text?)`	Encode an SSE comment chunk for manual heartbeats.

Use event.* when one response needs multiple events or a long-lived stream.

HTML helpers

API	Use
`renderToString(node)`	Serialize Datastar Kit HTML nodes and TSX output.
`unsafeHtml(html)`	Mark trusted HTML as already safe.
`dataAttrs(values)`	Type-check a primitive custom `data-*` attribute spread bag.

Types exported from the root include CustomJsxAttributes, CustomJsxElements, DataAttributes, HtmlChild, HtmlNode, HtmlProps, HtmlPropValue, SignalState, and SignalValue. Augment CustomJsxAttributes and CustomJsxElements in datastar-kit/jsx-runtime to register exact custom HTML or Datastar plugin attributes and custom-element props. Registered custom elements also retain global HTML, ARIA, children, and typed Datastar attributes. Non-data-* custom attributes must use primitive HtmlPropValue values so their static types match server-rendering behavior. Modifier wrappers remain limited to built-in Datastar attributes with modifier metadata.

Explicit subpaths

Subpath	Use
`datastar-kit/sse`	Low-level Datastar SSE encoders and comment chunks for custom integrations.
`datastar-kit/debugger`	Development-only browser entry that installs the debugger Web Component.
`datastar-kit/jsx-runtime`	TypeScript automatic JSX runtime entrypoint.
`datastar-kit/jsx-dev-runtime`	TypeScript automatic JSX development runtime entrypoint.

`datastar-kit/debugger`

Import this side-effect-only browser entry from development pages to register and add the <datastar-kit-debugger> Web Component. It inspects signals, Datastar events, and best-effort timeline snapshots. The subpath has no programmatic API.

Related guides: Actions and responses, Signals, Debugger, HTML and JSX.