The two SSE event types defined by the Datastar protocol.

Every event the server sends is one of these. EventPatchElements covers both DOM patching and script execution (the protocol encodes executeScript as a special case of element patching). EventPatchSignals updates the browser's reactive signal store.

How the patched HTML should be applied to the DOM.

The default mode is Outer, which replaces the target element (matched by its id attribute) including the element itself. This works well with Datastar's morphing algorithm, which preserves focus, scroll position, and CSS transitions during the replacement.

The XML namespace for the patched elements.

Almost all content uses HtmlNs (the default). Use SvgNs or MathmlNs when patching inline SVG or MathML elements so that Datastar creates them in the correct namespace.

Configuration for a datastar-patch-elements SSE event.

Construct values with patchElements or removeElements, then customise with record updates.

Build a PatchElements event with sensible defaults.

The HTML is sent as-is and Datastar matches target elements by their id attribute.

patchElements "<div id=\"greeting\">Hello!</div>"

Remove elements from the DOM matching a CSS selector.

removeElements "#notification"
removeElements ".stale-row"

Configuration for a datastar-patch-signals SSE event.

Construct values with patchSignals, then customise with record updates.

Build a PatchSignals event with sensible defaults.

The argument is a JSON object (as Text) describing the signals to update.

patchSignals "{\"count\": 42, \"label\": \"hello\"}"

Configuration for executing a script in the browser.

Construct values with executeScript, then customise with record updates.

Build an ExecuteScript event with sensible defaults.

The argument is the JavaScript source code to run in the browser.

executeScript "document.getElementById(\"name\").focus()"

An opaque handle for sending SSE events to the browser.

Obtain one from the callback passed to sseResponse. The handle is thread-safe — you can send events from multiple threads concurrently.

You don't construct these directly; sseResponse creates one for you.

Create a WAI Response that streams SSE events.

The callback receives a ServerSentEventGenerator for sending events. The SSE connection stays open until the callback returns.

app :: WAI.Request -> (WAI.Response -> IO b) -> IO b
app req respond =
  respond $ sseResponse $ \gen -> do
    sendPatchElements gen (patchElements "<div id=\"msg\">Hello</div>")

Send a PatchElements event, morphing HTML into the browser's DOM.

Send a PatchSignals event, updating the browser's reactive signal store.

Send an ExecuteScript event, running JavaScript in the browser.

Decode signals sent by the browser in a Datastar request.

For GET requests, signals are URL-encoded in the datastar query parameter. For POST requests (and other methods), signals are read from the request body as JSON.

Define a Haskell data type with a FromJSON instance to decode into:

data MySignals = MySignals { count :: Int, label :: Text }
  deriving (Generic)
  deriving anyclass (FromJSON)

handler :: WAI.Request -> IO ()
handler req = do
  Right signals <- readSignals req
  putStrLn $ "Count is: " <> show (count signals)

Check whether a request was initiated by Datastar.

Datastar adds a datastar-request header to its SSE requests. Use this to distinguish Datastar requests from normal page loads — for example, to serve either an SSE stream or a full HTML page from the same route.

app req respond
  | isDatastarRequest req =
      respond $ sseResponse $ \gen -> ...
  | otherwise =
      respond $ responseLBS status200 [] fullPageHtml