Using Datastar

Overview

Datastar is a hypermedia framework (10KB) combining frontend reactivity (like Alpine) with backend-driven updates (like HTMX) via Server-Sent Events. Key insight: the server pushes DOM updates through SSE streams, not request/response JSON.

Installation

<script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/[email protected]/bundles/datastar.js"></script>

Core Syntax

Signals (State)

Prefix with $ in expressions. Define with data-signals:

<div data-signals:count="0">
  <span data-text="$count"></span>
  <button data-on:click="$count++">+1</button>
</div>

Nested: data-signals:user.name="''" or data-signals="{user: {name: '', age: 0}}".

Actions (Backend Calls)

Use @verb(url) syntax:

<button data-on:click="@get('/api/data')">Load</button>
<button data-on:click="@post('/api/save')">Save</button>
<button data-on:click="@delete('/api/item')">Delete</button>

All signals automatically sent. Filter with options: @get('/api', {filterSignals: {include: /^form/}}).

Event Modifiers

Double-underscore syntax with dot parameters:

<input data-on:input__debounce.300ms="@get('/search')">
<button data-on:click__once="@post('/submit')">
<div data-on:click__outside="$open = false">

Common: __debounce.Xms, __throttle.Xms, __once, __prevent, __stop, __window, __outside.

Attributes Quick Reference

SSE Response Format (Critical)

Datastar expects text/event-stream, not HTML or JSON. Server pushes events:

Patch elements:

event: datastar-patch-elements
data: elements <div id="results">New content</div>

Patch signals:

event: datastar-patch-signals
data: signals {"count": 5}

Remove elements:

event: datastar-patch-elements
data: mode remove
data: selector #old-item

Patch modes: morph (default), inner, outer, prepend, append, before, after, remove.

Note: blank line after each event block.

Go SDK

import "github.com/starfederation/datastar-go/datastar"

func handler(w http.ResponseWriter, r *http.Request) {
    // Read signals from request
    var store MyStore
    if err := datastar.ReadSignals(r, &store); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Create SSE writer
    sse := datastar.NewSSE(w, r)

    // Send HTML fragment (patches by ID match)
    sse.PatchElements(`<div id="result">Updated!</div>`)

    // Update signals
    sse.MarshalAndPatchSignals(map[string]any{"count": 42})

    // Execute script
    sse.ExecuteScript(`console.log('done')`)
}

With Templ

func handler(w http.ResponseWriter, r *http.Request) {
    sse := datastar.NewSSE(w, r)
    sse.PatchElementTempl(MyComponent(data))
}

Complete Example: Counter

HTML:

<div data-signals:count="0">
  <p>Count: <span data-text="$count"></span></p>
  <button data-on:click="@post('/increment')">+1</button>
</div>

Go:

type Store struct {
    Count int `json:"count"`
}

func incrementHandler(w http.ResponseWriter, r *http.Request) {
    var store Store
    datastar.ReadSignals(r, &store)
    store.Count++

    sse := datastar.NewSSE(w, r)
    sse.MarshalAndPatchSignals(store)
}

Complete Example: Search with Debounce

HTML:

<div data-signals:query="''">
  <input
    data-bind:query
    data-on:input__debounce.300ms="@get('/search')"
    data-indicator:searching
  >
  <span data-show="$searching">Loading...</span>
  <div id="results"></div>
</div>

Go:

func searchHandler(w http.ResponseWriter, r *http.Request) {
    var store struct {
        Query string `json:"query"`
    }
    datastar.ReadSignals(r, &store)

    results := search(store.Query)

    sse := datastar.NewSSE(w, r)
    sse.PatchElements(renderResults(results))
}

Common Mistakes