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>

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.).

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

KeyDescription
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: selector #fooSelects the target element of the patch using a CSS selector. Not required when using the outer or inner modes.
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>

Elements can be removed using the remove mode and providing either an explicit selector or elements with an ID.

1event: datastar-patch-elements
2data: mode remove
3data: selector #foo
1event: datastar-patch-elements
2data: mode remove
3data: elements <div id="foo"></div>

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

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

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}

Signals can be removed by setting their values to null.

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

Sample output showing non-default options:

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