Documentation
¶
Overview ¶
Package datastar provides templ components and helpers for integrating Datastar — a ~12 KiB zero-dependency frontend framework that unifies HTMX-style backend reactivity with Alpine.js-style frontend reactivity via Server-Sent Events (SSE) and reactive signals.
This package mirrors the htmx package: it emits data-* attributes and injects the Datastar runtime <script> tag without importing the datastar-go SDK. Consumers who want SSE streaming add github.com/starfederation/datastar-go to their own go.mod.
Quick start ¶
Inject the runtime once per page (in your layout, alongside or instead of the HTMX script):
@datastar.SDKScript(datastar.DefaultSDKScriptProps())
Establish an SSE-powered live region:
@datastar.LiveRegion(datastar.LiveRegionProps{
URL: "/stream/metrics",
AutoStart: true,
}) {
@display.StatCard(display.StatCardProps{Label: "Active Users", Value: "—"})
}
The server endpoint streams patches using the datastar-go SDK:
func streamHandler(w http.ResponseWriter, r *http.Request) {
sse := datastar.NewSSE(w, r)
for {
sse.PatchElementTempl(metricsCard(currentMetrics()))
time.Sleep(time.Second)
}
}
When to choose Datastar over HTMX ¶
See docs/research/datastar-integration-analysis.md for the full analysis. Briefly: HTMX is the default (zero JS dependency). Datastar is opt-in for real-time streaming, reactive client-side state, or when the consumer's app already uses Datastar.
templ: version: v0.3.1020
templ: version: v0.3.1020
templ: version: v0.3.1020
Index ¶
- func DatastarVersionIsValid(v DatastarVersion) bool
- func Delete(url string) string
- func Get(url string) string
- func Indicator(props IndicatorProps) templ.Component
- func LivePolitenessIsValid(v LivePoliteness) bool
- func LiveRegion(props LiveRegionProps) templ.Component
- func Patch(url string) string
- func Post(url string) string
- func Put(url string) string
- func SDKScript(props SDKScriptProps) templ.Component
- type DatastarVersion
- type IndicatorProps
- type LivePoliteness
- type LiveRegionProps
- type SDKScriptProps
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DatastarVersionIsValid ¶
func DatastarVersionIsValid(v DatastarVersion) bool
DatastarVersionIsValid reports whether v is one of the defined DatastarVersion constants.
func Get ¶
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}),
})
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.
The server endpoint must return a text/event-stream response. Use the datastar-go SDK to patch elements or signals:
func streamHandler(w http.ResponseWriter, r *http.Request) {
sse := datastar.NewSSE(w, r)
for {
sse.PatchElementTempl(metricsCard(currentMetrics()))
time.Sleep(time.Second)
}
}
@datastar.LiveRegion(datastar.LiveRegionProps{
URL: "/stream/metrics",
AutoStart: true,
}) {
@display.StatCard(display.StatCardProps{Label: "Active Users", Value: "—"})
}
func Post ¶
Post returns a Datastar @post('url') action expression. Sends all signals as the request body.
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).
@datastar.SDKScript(datastar.DefaultSDKScriptProps())
Self-hosting:
@datastar.SDKScript(datastar.SDKScriptProps{Src: "/static/datastar.js", Nonce: nonce})
Types ¶
type DatastarVersion ¶
type DatastarVersion string
DatastarVersion is a pinned Datastar runtime version. Use the exported constants (e.g. DatastarVersion1_0_2) for compile-time safety; custom versions can be constructed via DatastarVersion("x.y.z") but will render without SRI (no integrity hash — Datastar does not publish official SRI hashes; self-host and compute your own if integrity is required).
const ( // DatastarVersion1_0_2 is the Datastar runtime version this package pins. DatastarVersion1_0_2 DatastarVersion = "1.0.2" )
type IndicatorProps ¶
type IndicatorProps struct {
utils.BaseProps
// Signal is the indicator signal name (without the $ prefix).
// Must match the data-indicator:<name> on the triggering element.
Signal string
// Spinner is the loading animation to display while the signal is true.
// Typically feedback.Spinner(...). When nil, a CSS pulse is shown.
Spinner templ.Component
}
IndicatorProps configures 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 to appear.
This is the Datastar equivalent of htmx.LoadingIndicator / InlineLoadingOverlay.
<button data-on:click="@post('/save')" data-indicator:saving>Save</button>
@datastar.Indicator(datastar.IndicatorProps{Signal: "saving"})
func DefaultIndicatorProps ¶
func DefaultIndicatorProps() IndicatorProps
DefaultIndicatorProps returns sensible defaults for an indicator.
type LivePoliteness ¶
type LivePoliteness string
LivePoliteness is the aria-live politeness setting for a live region. Controls how screen readers announce streamed content updates.
const ( // LivePolite announces updates after the current speech finishes (default). LivePolite LivePoliteness = "polite" // LiveAssertive announces updates immediately, interrupting current speech. // Use sparingly — only for critical alerts. LiveAssertive LivePoliteness = "assertive" // LiveOff disables screen-reader announcements for this region. LiveOff LivePoliteness = "off" )
type LiveRegionProps ¶
type LiveRegionProps struct {
utils.BaseProps
// URL is the SSE endpoint that streams element/signal patches.
// The server opens a long-lived connection and pushes updates.
URL string
// AutoStart opens the SSE connection on page load via data-init.
// When false, the consumer triggers the stream manually (e.g. via a
// button with data-on:click="@get('/stream')").
AutoStart bool
// Live sets the aria-live politeness for screen-reader announcements.
// Defaults to LivePolite.
Live LivePoliteness
}
LiveRegionProps configures an SSE-powered auto-updating region. This is the Datastar equivalent of htmx.PolledRegion — but instead of polling on an interval, the server pushes patches via a long-lived SSE connection.
The URL endpoint should return a text/event-stream response. The server patches the region's children (or signals) using the datastar-go SDK.
@datastar.LiveRegion(datastar.LiveRegionProps{
URL: "/stream/metrics",
AutoStart: true,
}) {
@display.StatCard(display.StatCardProps{Label: "Users", Value: "—"})
}
func DefaultLiveRegionProps ¶
func DefaultLiveRegionProps() LiveRegionProps
DefaultLiveRegionProps returns sensible defaults for a live region.
type SDKScriptProps ¶
type SDKScriptProps struct {
utils.BaseProps
// Version pins the Datastar runtime version. Defaults to DatastarVersion1_0_2.
// Set to "" to use the default.
Version DatastarVersion
// CDN overrides the CDN base URL. Defaults to the jsDelivr GitHub CDN.
// Consumers can point this at their own origin or npm mirror.
CDN string
// Src overrides the full script URL — use for self-hosting.
// When set, Version and CDN are ignored.
Src string
}
SDKScriptProps configures injection of the Datastar runtime <script> tag. Include this once per page in your layout, alongside or instead of the HTMX script. Datastar loads as an ES module (deferred by default).
@datastar.SDKScript(datastar.DefaultSDKScriptProps())
func DefaultSDKScriptProps ¶
func DefaultSDKScriptProps() SDKScriptProps
DefaultSDKScriptProps returns sensible defaults for the Datastar runtime script.
Source Files