SSE Events

Responses to backend actions with a content type of text/event-stream can contain zero or more Datastar SSE events.

The backend SDKs can handle the formatting of SSE events for you, or you can format them yourself.

Event Types #

datastar-patch-elements #

Patches one or more elements in the DOM. By default, Datastar morphs elements by matching top-level elements based on their ID.

1event: datastar-patch-elements
2data: elements <div id="foo">Hello world!</div>
3

In the example above, the element <div id="foo">Hello world!</div> will be morphed into the target element with ID foo.

Be sure to place IDs on top-level elements to be morphed, as well as on elements within them that you’d like to preserve state on (event listeners, CSS transitions, etc.).

Morphing elements within SVG elements requires special handling due to XML namespaces. See the SVG morphing example.

Additional data lines can be added to the response to override the default behavior.

KeyDescription
data: selector #fooSelects the target element of the patch using a CSS selector. Not required when using the outer or replace modes.
data: mode outerMorphs the outer HTML of the elements. This is the default (and recommended) mode.
data: mode innerMorphs the inner HTML of the elements.
data: mode replaceReplaces the outer HTML of the elements.
data: mode prependPrepends the elements to the target’s children.
data: mode appendAppends the elements to the target’s children.
data: mode beforeInserts the elements before the target as siblings.
data: mode afterInserts the elements after the target as siblings.
data: mode removeRemoves the target elements from DOM.
data: namespace svgPatch elements into the DOM using an svg namespace.
data: namespace mathmlPatch elements into the DOM using a mathml namespace.
data: useViewTransition trueWhether to use view transitions when patching elements. Defaults to false.
data: elementsThe HTML elements to patch.
1event: datastar-patch-elements
2data: elements <div id="foo">Hello world!</div>
3

Elements can be removed using the remove mode and providing a selector.

1event: datastar-patch-elements
2data: selector #foo
3data: mode remove
4

Elements can span multiple lines. Sample output showing non-default options:

1event: datastar-patch-elements
2data: selector #foo
3data: mode inner
4data: useViewTransition true
5data: elements <div>
6data: elements        Hello world!
7data: elements </div>
8

Elements can be patched using svg and mathml namespaces by specifying the namespace data line.

1event: datastar-patch-elements
2data: namespace svg
3data: elements <circle id="circle" cx="100" r="50" cy="75"></circle>
4

datastar-patch-signals #

Patches signals into the existing signals on the page. The onlyIfMissing line determines whether to update each signal with the new value only if a signal with that name does not yet exist. The signals line should be a valid data-signals attribute.

1event: datastar-patch-signals
2data: signals {foo: 1, bar: 2}
3

Signals can be removed by setting their values to null.

1event: datastar-patch-signals
2data: signals {foo: null, bar: null}
3

Sample output showing non-default options:

1event: datastar-patch-signals
2data: onlyIfMissing true
3data: signals {foo: 1, bar: 2}
4