datastar

func DatastarVersionIsValid ¶

func DatastarVersionIsValid(v DatastarVersion) bool

DatastarVersionIsValid reports whether v is one of the defined DatastarVersion constants.

func Delete ¶

func Delete(url string) string

Delete returns a Datastar @delete('url') action expression.

func Get ¶

func Get(url string) string

Get returns a Datastar @get('url') action expression for use in data-on:* or data-init attributes. The response should be an SSE stream.

data-on:click={ datastar.Get("/api/search") }

func Indicator ¶

func Indicator(props IndicatorProps) templ.Component

Indicator renders a loading indicator that shows/hides based on a Datastar indicator signal. Place data-indicator:<name> on the element that triggers a backend action, then render an Indicator wherever you want the spinner.

This is the Datastar equivalent of htmx.LoadingIndicator.

<button data-on:click="@post('/save')" data-indicator:saving>Save</button>
@datastar.Indicator(datastar.IndicatorProps{Signal: "saving"})

With a custom spinner:

@datastar.Indicator(datastar.IndicatorProps{
    Signal:  "saving",
    Spinner: feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerSM}),
})

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.Indicator(datastar.DefaultIndicatorProps())
}

Output:

func LivePolitenessIsValid ¶

func LivePolitenessIsValid(v LivePoliteness) bool

LivePolitenessIsValid reports whether v is one of the defined LivePoliteness constants.

func LiveRegion ¶

func LiveRegion(props LiveRegionProps) templ.Component

LiveRegion renders a container that auto-connects to an SSE endpoint and receives server-patched updates. This is the Datastar equivalent of htmx.PolledRegion — but instead of polling on an interval, the server pushes patches over a single long-lived connection.

An empty URL degrades to a plain container (no data-init) — the runtime throws FetchNoUrlProvided for @get(”). Wire the stream via data-on:* on a trigger element instead.// The server endpoint must return a text/event-stream response. Use go-datastar (github.com/larsartmann/go-datastar) to patch elements or signals. Target a child element of the region with WithSelector — patch modes other than the default (outer) require one, and the default outer mode matches incoming root elements by their id (id-less fragments are dropped with a console warning):

func streamHandler(w http.ResponseWriter, r *http.Request) {
    stream := sse.NewStream(w, r)
    defer func() { _ = stream.Close() }()
    resp := datastar.NewResponse(stream)
    _ = resp.PatchElementsTempl(metricsCardContent(),
        datastar.WithSelector("#metrics"), datastar.WithModeInner())
}

@datastar.LiveRegion(datastar.LiveRegionProps{
    URL:       "/stream/metrics",
    AutoStart: true,
}) {
    @display.StatCard(display.StatCardProps{
        BaseProps: utils.BaseProps{ID: "metrics"},
        Label:     "Active Users",
        Value:     "—",
    })
}

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.LiveRegion(datastar.DefaultLiveRegionProps())
}

Output:

func LoadingButton ¶ added in v1.20.0

func LoadingButton(props LoadingButtonProps) templ.Component

LoadingButton renders a button label that swaps to a busy state while the enclosing button's Datastar action is in flight — the Datastar equivalent of htmx.LoadingButton, driven entirely by the runtime's indicator signal (zero component-side JavaScript).

The component renders CONTENT, not the button: place it inside a button that carries BOTH the action and the indicator marker, and pass the same signal name here. While the action is in flight the runtime sets the signal true (bundle-verified), data-show swaps the labels, and the signal clears when the response lands.

Unlike the htmx twin there is no disabled-element mechanism in the Datastar dialect; gate double submissions server-side or via data-indicator-driven UI.

<button
    data-indicator:saving
    data-on:click="@post('/save', {contentType: 'form'})"
    class="inline-flex items-center justify-center rounded-md bg-blue-600 px-4 py-2 text-white"
>
    @datastar.LoadingButton(datastar.LoadingButtonProps{
        Signal:      "saving",
        DefaultText: "Save",
        LoadingText: "Saving…",
    })
</button>

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.LoadingButton(datastar.LoadingButtonProps{
		Signal:      "saving",
		DefaultText: "Save",
		LoadingText: "Saving…",
	})
}

Output:

func Patch ¶

func Patch(url string) string

Patch returns a Datastar @patch('url') action expression.

func PolledRegion ¶ added in v1.20.0

func PolledRegion(props PolledRegionProps) templ.Component

PolledRegion renders a div that auto-refreshes its content via Datastar interval polling (data-on-interval). This is the Datastar twin of htmx.PolledRegion: the region fetches its own URL on an interval and the endpoint responds with a fragment whose root id matches the region id, so the runtime's default outer-mode patch replaces the region (self-patch). The runtime re-initializes the patched-in element, so polling continues with a fresh interval — and because this component never emits the leading flag, a self-patch CANNOT loop eagerly (leading + outer self-patch would refetch immediately forever; that combination stays out of the API on purpose — the same hazard class as htmx's forbidden "load, every" trigger on a self-replacing region).

Initial content belongs in the children slot (server-rendered), so the region never shows an empty state and needs no eager-fetch mechanism.

Polling busy state: the runtime wraps every tick in its fetching markers — attach data-indicator:<name> consumers via datastar.Indicator for spinners (see the Indicator docs). This component intentionally does not render aria-busy: there is no "waiting for first load" window to announce.

@datastar.PolledRegion(datastar.PolledRegionProps{
    BaseProps: utils.BaseProps{ID: "stats"},
    URL:       "/partials/stats",
    Every:     "10s",
}) {
    @display.StatCard(display.StatCardProps{Label: "Messages", Value: "1,234"})
}

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.PolledRegion(datastar.PolledRegionProps{
		ID:    "stats",
		URL:   "/partials/stats",
		Every: "10s",
	})
}

Output:

func Post ¶

func Post(url string) string

Post returns a Datastar @post('url') action expression. Sends all signals as the request body.

func Put ¶

func Put(url string) string

Put returns a Datastar @put('url') action expression.

func RetryModeIsValid ¶ added in v1.9.0

func RetryModeIsValid(v RetryMode) bool

RetryModeIsValid reports whether v is one of the defined RetryMode constants.

func SDKScript ¶

func SDKScript(props SDKScriptProps) templ.Component

SDKScript injects the Datastar runtime as an ES module. Include this once per page in your layout, alongside or instead of the HTMX script.

Datastar loads as type="module" (deferred by default — no render-blocking). When loading from a CDN, a <link rel="preconnect"> to the CDN origin is emitted first so the module fetch skips DNS + TLS on the critical path.

@datastar.SDKScript(datastar.DefaultSDKScriptProps())

Self-hosting:

@datastar.SDKScript(datastar.SDKScriptProps{Src: "/static/datastar.js", Nonce: nonce})

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.SDKScript(datastar.DefaultSDKScriptProps())
}

Output:

func SSEErrorHandling ¶

func SSEErrorHandling(cfg SSEErrorHandlingConfig) templ.Component

SSEErrorHandling renders a global listener for DataStar stream failures and surfaces them as accessible toasts so streaming errors are never silent. This is the DataStar counterpart to htmx.GlobalErrorHandling, which covers HTMX request errors.

The DataStar runtime (v1.x) reports the fetch/SSE lifecycle on the document-level "datastar-fetch" event. detail.type is one of "started", "finished", "error", "retrying", or "retries-failed" (plus the applied patch event names for successful SSE messages). This handler reports the two terminal failure states:

• "error": the endpoint answered with an HTTP error (status >= 400). Toasted with the status code from detail.argsRaw.status.
• "retries-failed": the connection dropped and automatic reconnection exhausted its retries (default: 10 attempts, exponential backoff). Toasted; the stream stays dead until its action re-runs.

Transient "retrying" events are logged to the console only — the runtime keeps reconnecting on its own, and toasting each attempt would spam.

Requires feedback.ToastContainer on the page for toast feedback (it provides the global tcShowToast function). Without it, errors are still logged to the console and announced via the aria-live region.

Typical layout wiring:

@feedback.ToastContainer("")
@datastar.SSEErrorHandling(datastar.DefaultSSEErrorHandlingConfig())

package main

import (
	"github.com/larsartmann/templ-components/datastar"
)

func main() {
	_ = datastar.SSEErrorHandling(datastar.DefaultSSEErrorHandlingConfig())
}

Output: