ui

func ApplySSRStateUpdate ¶

func ApplySSRStateUpdate(parseBootstrap *SSRBootstrap, parseUpdate SSRStateUpdate) error

ApplySSRStateUpdate merges a text or binary update envelope into a bootstrap payload snapshot.

func Await ¶

func Await[T any](parseValue SuspenseValue[T]) T

Await returns a ready value or suspends the current render until it is ready.

func BuildParallelRegionSourceIDs ¶

func BuildParallelRegionSourceIDs(parseSources ...ReactiveSource) ([]string, error)

BuildParallelRegionSourceIDs flattens declared reactive sources into a stable public source-ID list.

func CSSEscape ¶

func CSSEscape(parseValue string) string

CSSEscape escapes a string for safe use as a CSS identifier, implementing the WHATWG CSS.escape algorithm (https://drafts.csswg.org/cssom/#serialize-an-identifier).

Element ids returned by UseId are already CSS-safe by construction (see G29), so escaping them is unnecessary. CSSEscape exists for the general case: any id derived from user data, external systems, or string concatenation that is then fed into a CSS selector. Use it together with SelectorID:

node := document.Call("querySelector", ui.SelectorID(userProvidedID))

Passing an un-escaped arbitrary string to querySelector("#"+id) can throw a SyntaxError (and, in a wasm callback, panic the page) when the id contains a colon, space, or other CSS metacharacter.

func ConfigureBootstrapCorrelation ¶

func ConfigureBootstrapCorrelation(parseCtx context.Context, parseBootstrap *SSRBootstrap)

ConfigureBootstrapCorrelation embeds the correlation ID from ctx into the bootstrap payload so the client can auto-adopt it during hydration without manual threading.

ui.ConfigureBootstrapCorrelation(r.Context(), &bootstrap)

func ConfigureHydrationIslandBudget ¶

func ConfigureHydrationIslandBudget(parseBudget HydrationIslandBudget)

ConfigureHydrationIslandBudget is a browser-only runtime setting. Native SSR can still validate plans with InspectHydrationIslandBudget.

func CorrelationIDFromContext ¶

func CorrelationIDFromContext(parseCtx context.Context) string

CorrelationIDFromContext returns the correlation ID stored by WithCorrelationID or WrapSSRCorrelation, or an empty string if none is present.

func CurrentTheme ¶

func CurrentTheme() string

CurrentTheme returns the active theme name without subscribing (safe to call outside a render). Returns "" when no theme has been set.

func Download ¶

func Download(parseData []byte, parseName, parseMime string)

Download saves bytes as a file with the given name and MIME type. No-op on the native/SSR build.

func GetSSRObservationAttributes ¶

func GetSSRObservationAttributes(parseObservation SSRObservation) map[string]string

GetSSRObservationAttributes maps one SSRObservation to OTel-compatible span attribute key-value pairs.

The returned map uses stable "gwc.*" attribute keys following OpenTelemetry naming conventions. Pass them to your OTel SDK with SetAttributes or equivalent:

attrs := ui.GetSSRObservationAttributes(event)
for k, v := range attrs {
    span.SetAttributes(attribute.String(k, v))
}

Keys are guaranteed stable across patch releases once the observability surface is marked stable.

func HydrateIsland ¶

func HydrateIsland(parseRoot Node, parseOptions HydrationIslandOptions) (func(), error)

HydrateIsland is browser-only. Server builds can render HydrationIsland wrappers and validate their budget plan before emitting HTML.

func MarshalSSRBootstrap ¶

func MarshalSSRBootstrap(parsePayload SSRBootstrap) ([]byte, error)

MarshalSSRBootstrap serializes a bootstrap payload to safe inline JSON.

func MarshalSSRBootstrapBinary ¶

func MarshalSSRBootstrapBinary(parsePayload SSRBootstrap) ([]byte, error)

MarshalSSRBootstrapBinary serializes a bootstrap payload to CBOR.

func MarshalSSRBootstrapBinaryObserved ¶

func MarshalSSRBootstrapBinaryObserved(parsePayload SSRBootstrap, parseOptions SSRObservabilityOptions) ([]byte, error)

MarshalSSRBootstrapBinaryObserved serializes a bootstrap payload to CBOR and emits size metrics.

func MarshalSSRBootstrapObserved ¶

func MarshalSSRBootstrapObserved(parsePayload SSRBootstrap, parseOptions SSRObservabilityOptions) ([]byte, error)

MarshalSSRBootstrapObserved serializes a bootstrap payload and emits size metrics.

func MarshalSSRStateUpdateBinary ¶

func MarshalSSRStateUpdateBinary(parseUpdate SSRStateUpdate) ([]byte, error)

MarshalSSRStateUpdateBinary encodes a state-update envelope as CBOR.

func MarshalSSRStateUpdateText ¶

func MarshalSSRStateUpdateText(parseUpdate SSRStateUpdate) ([]byte, error)

MarshalSSRStateUpdateText encodes a state-update envelope as JSON text.

func OnReady ¶

func OnReady(parseFn func())

OnReady registers fn to run once, right after the first render commits (the initial UI is on screen and its effects have run). If the app has already rendered, fn runs immediately. Use it to drop a loading splash, kick off post-mount work, or signal readiness — instead of guessing with timeouts.

ui.OnReady(func() { /* hide splash, start telemetry, … */ })

On wasm the runtime additionally dispatches a "gwc:ready" event on document, so a plain host page can drop its splash without any Go glue:

document.addEventListener("gwc:ready", () => splash.remove())

func PickFile ¶

func PickFile(parseAccept string, parseOnPick func(PickedFile))

PickFile opens the OS file picker (filtered by accept, e.g. "image/*" or ".csv") and calls onPick with the chosen file. No-op on native/SSR. onPick runs asynchronously after the user selects a file.

func RegisterBootstrapPayload ¶

func RegisterBootstrapPayload[T any](parseBootstrap *SSRBootstrap, parseKey string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterBootstrapPayload stores one typed payload entry under SSRBootstrap.Data.

func RegisterCacheBootstrapSeed ¶

func RegisterCacheBootstrapSeed[T any](parseBootstrap *SSRBootstrap, cacheKey string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterCacheBootstrapSeed stores a typed cache seed under a cache-scoped payload key.

func RegisterFormBootstrapDefaults ¶

func RegisterFormBootstrapDefaults[T any](parseBootstrap *SSRBootstrap, parseFormID string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterFormBootstrapDefaults stores typed form defaults under a form-scoped payload key.

func RegisterParallelRegion ¶

func RegisterParallelRegion[Props any](parseRendererID string, parseRender func(Props) Node) error

RegisterParallelRegion registers one public parallel-region renderer and bridges it into the runtime2 registry.

func RegisterRouteBootstrapData ¶

func RegisterRouteBootstrapData[T any](parseBootstrap *SSRBootstrap, parseKey string, parseRoutePath string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterRouteBootstrapData stores typed route data under a route-scoped payload key.

func RegisterSessionBootstrapHint ¶

func RegisterSessionBootstrapHint[T any](parseBootstrap *SSRBootstrap, parseHintKey string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterSessionBootstrapHint stores a typed session hint under an app-scoped payload key.

func RegisterStateUpdatePayload ¶

func RegisterStateUpdatePayload[T any](parseUpdate *SSRStateUpdate, parseKey string, parseValue T, parseOptions ...SSRPayloadOptions) error

RegisterStateUpdatePayload stores one typed payload upsert in a state-update envelope.

func Render ¶

func Render(parseRoot Node, parseSelector string)

Render is browser-only; the native SSR slice exposes RenderToString instead.

func RenderBootstrapReferenceScript ¶

func RenderBootstrapReferenceScript(parseRef SSRBootstrapReference, parseScriptID string) (string, error)

RenderBootstrapReferenceScript renders an inline script tag that points at an external bootstrap payload.

func RenderBootstrapReferenceScriptWithOptions ¶

func RenderBootstrapReferenceScriptWithOptions(parseRef SSRBootstrapReference, parseScriptID string, parseScriptOptions SSRScriptOptions) (string, error)

func RenderBootstrapScript ¶

func RenderBootstrapScript(parsePayload SSRBootstrap, parseScriptID string) (string, error)

RenderBootstrapScript renders an inline bootstrap script tag.

func RenderBootstrapScriptObserved ¶

func RenderBootstrapScriptObserved(parsePayload SSRBootstrap, parseScriptID string, parseOptions SSRObservabilityOptions) (string, error)

RenderBootstrapScriptObserved renders an inline bootstrap script tag and emits size metrics.

func RenderBootstrapScriptWithOptions ¶

func RenderBootstrapScriptWithOptions(parsePayload SSRBootstrap, parseScriptID string, parseScriptOptions SSRScriptOptions) (string, error)

func RenderInto ¶

func RenderInto(parseRoot Node, parseTarget any) error

RenderInto is a non-browser stub that returns an UnsupportedOnServer error.

func RenderToStream ¶

func RenderToStream(parseCtx context.Context, parseWriter io.Writer, parseRoot Node, parseOptions ...SSRStreamOptions) error

RenderToStream writes an SSR shell immediately and then streams async boundary replacements as render-time suspensions resolve.

func RenderToStreamObserved ¶

func RenderToStreamObserved(parseCtx context.Context, parseWriter io.Writer, parseRoot Node, parseObservability SSRObservabilityOptions, parseOptions ...SSRStreamOptions) error

RenderToStreamObserved streams an SSR tree and emits SSR render metrics.

func RenderToString ¶

func RenderToString(parseRoot Node) (string, error)

RenderToString renders a ui.Node tree to HTML on non-browser targets.

func RenderToStringObserved ¶

func RenderToStringObserved(parseRoot Node, parseOptions SSRObservabilityOptions) (string, error)

RenderToStringObserved renders a ui.Node tree to HTML and emits SSR metrics.

func ResetWASMStackFrameMapper ¶

func ResetWASMStackFrameMapper()

ResetWASMStackFrameMapper clears the installed wasm stack-frame mapper.

func Run ¶

func Run(parseSelector string, parseComponent any, parseProps ...any)

Run is browser-only; on the native/SSR slice it panics like Render. Server-side code should call RenderToString (or the SSR streaming APIs) instead of mounting and blocking.

func SafeGo ¶

func SafeGo(parseSubject string, parseFn func())

SafeGo starts fn on a new goroutine with framework crash containment. In wasm a panic that escapes any goroutine exits the whole Go program and leaves the page dead; SafeGo recovers the panic, prints the structured agent-readable crash report to the console, and lets the rest of the app keep running. Use it instead of the bare go statement for application background work. The subject names the task in the crash report.

func SelectorID ¶

func SelectorID(parseID string) string

SelectorID returns a CSS id selector ("#" + escaped id) for the given element id, safe to pass to querySelector/querySelectorAll for an id from any source.

el := document.Call("querySelector", ui.SelectorID(id))

For ids generated by UseId the escaping is a no-op, but using SelectorID everywhere keeps call sites uniformly safe.

func SetInspectSink ¶

func SetInspectSink(parseSink func(string)) func()

SetInspectSink redirects UseInspect output (e.g. to the devtools bridge or a test buffer) and returns a function that restores the previous sink. Pass a no-op to silence inspection in production builds.

func SetParallelRegionWorkerRenderer ¶

func SetParallelRegionWorkerRenderer(parseRendererID string, parseRender runtime2.WorkerRegionRenderer) error

SetParallelRegionWorkerRenderer registers one explicit worker-native renderer for an already-registered public parallel region.

func SetParallelRegionWorkerRendererWithConfig ¶

func SetParallelRegionWorkerRendererWithConfig(
	parseRendererID string,
	parseRender runtime2.WorkerRegionRenderer,
	parseConfig ParallelRegionWorkerRendererConfig,
) error

SetParallelRegionWorkerRendererWithConfig registers one explicit worker-native renderer with optional trust and validation settings.

func SetTheme ¶

func SetTheme(parseName string)

SetTheme switches the active theme from anywhere — including outside a render (a global hotkey handler, the OS theme-change listener, a goroutine). It re-renders all UseTheme subscribers and applies <html data-theme="...">. Passing "" clears the attribute (revert to default/unthemed).

func SetWASMStackFrameMapper ¶

func SetWASMStackFrameMapper(parseMapper func(WASMStackFrame) (WASMStackFrame, bool))

SetWASMStackFrameMapper installs a mapper that translates an observed wasm/browser panic frame back to a higher-signal application Go source location. The runtime threads every panic frame through it before the in-page error overlay and the devtools panel render it, so a panic shows your Go function/file/line instead of an opaque wasm offset.

This is the public C4 "stack-correlation workaround" — the supported bridge until the Go toolchain emits browser-consumable source maps for js/wasm natively. Install one at startup (sourced from your build's symbol dump or a hand-maintained table for hot paths).

func StartTransition ¶

func StartTransition(parseFn func())

StartTransition runs fn immediately on non-browser targets.

func SuspendUntil ¶

func SuspendUntil(parseDone <-chan struct{}, parseReason ...string)

SuspendUntil interrupts the current render until done closes.

func Typed ¶ added in v4.2.0

func Typed[P any](parseComponent func(P) Node) func(P) Node

Typed registers a props-taking component once and returns a constructor that creates its elements without any reflection on the render path.

A component passed to CreateElement with a custom props struct renders through a reflect.Value.Call trampoline on every render — measurable overhead in wasm, where reflection is expensive. Typed builds a statically dispatched renderer instead:

var HookCell = ui.Typed(renderHookCell) // package level, once
...
HookCell(HookCellProps{Index: i})       // in render bodies

The returned constructor is equivalent to ui.CreateElement(component, props): same component identity (handle cache), same reconciliation, hooks work unchanged. Mixing is safe — plain CreateElement calls for the same function value keep the static renderer (the implementation-identity guard skips re-registration).

func UnsupportedOnServer ¶

func UnsupportedOnServer(parseName string) error

UnsupportedOnServer explains the current SSR limitation for hook-based components.

func UseAction ¶

func UseAction[T any](parseCache *query.Cache, parseKey string) (query.Result[T], func(parseOptimistic T, parseFn func() (T, error)))

UseAction binds a server action to key in the cache: it returns the current result and a run function that fires the action with an optimistic value and reconciles in the background (commit or rollback), re-rendering on settle. Pair run's fn with serverfn.Call to make a one-call optimistic server action.

res, runLike := ui.UseAction[int](appCache, "post/"+id+"/likes")
onClick := func() { runLike(res.Data+1, func() (int, error) { return serverfn.Call(...) }) }

func UseAnimationRestart ¶

func UseAnimationRestart(parseRef DOMRef, parseClassName string, parseDeps ...any)

UseAnimationRestart is a no-op on native/SSR.

func UseAsyncMutation ¶

func UseAsyncMutation[T any](parseCache *query.Cache, parseKey string) func(parseOptimistic T, parseFn func() (T, error))

UseAsyncMutation is the async sibling of UseMutation: the returned function applies the optimistic value immediately (re-rendering now) and reconciles in the background — committing the server result or rolling back on error and re-rendering again when it settles. This is the fire-and-forget optimistic action; UseMutation wraps the *blocking* query.Mutate, this one wraps query.MutateAsync.

func UseAutoFocus ¶

func UseAutoFocus(parseRef DOMRef, parseDeps ...any)

UseAutoFocus moves keyboard focus to a referenced element after it mounts (G22).

The HTML autofocus attribute (html.AutoFocus) only fires on the initial page load, not when an element is mounted later in a single-page app — so inline editors, dialogs, and revealed fields never receive focus from it. UseAutoFocus closes that gap without the focusByID/getElementById workaround: pair it with a DOM ref and the element is focused once it is live.

r := ui.UseDOMRef()
ui.UseAutoFocus(r)                    // focus once, on mount
return shorthand.Input(shorthand.Ref(r))

Pass deps to re-focus when they change (focus-follows-reveal):

ui.UseAutoFocus(r, isEditing)         // focus each time isEditing flips true-with-mount

With no deps it runs exactly once on mount (it must not run every render, or it would steal focus continuously). Focusing is a no-op before mount, after unmount, and on the native/SSR build.

func UseCallback ¶

func UseCallback[T any](parseFn T, parseDeps ...any) T

UseCallback returns fn unchanged on non-browser targets.

func UseContext ¶

func UseContext[T any](parseContext *Context[T]) T

UseContext is a core package helper.

func UseDefer ¶

func UseDefer(parseTriggered bool) bool

UseDefer latches a deferred view: it returns false until triggered first becomes true, then stays true for the rest of the component's lifetime (mount-once). Feed it a trigger derived from component state — `UseIntersection` (viewport), `UseIdle` (browser idle), or `UseTimerTrigger` (after a delay) — so that when the trigger flips, the component re-renders and the deferred subtree mounts for good (it will not flicker back to the placeholder if the trigger later goes false).

visible := UseIntersection(ref)          // a state-backed browser trigger
if ui.UseDefer(visible) { /* render heavy view */ } else { /* render placeholder */ }

This defers RENDER work (the subtree is not constructed until shown). It does not lazy-load a separate wasm *chunk* per view — Go compiles to a single wasm binary, so all code is already present; "deferrable views" here means deferred construction/mount, not code splitting.

func UseDeferredValue ¶

func UseDeferredValue[T any](parseValue T) T

UseDeferredValue returns value unchanged on non-browser targets.

func UseDocumentEvent ¶

func UseDocumentEvent(eventType string, handler func(Event), deps ...any)

UseDocumentEvent subscribes the calling component to a document-level event for as long as it is mounted.

func UseEffect ¶

func UseEffect(parseEffect func() func(), parseDeps ...any)

UseEffect is a no-op on non-browser targets.

func UseEffectOf ¶ added in v4.2.0

func UseEffectOf[D comparable](parseEffect func() func(), parseDep D)

UseEffectOf is a no-op on non-browser targets (native UseEffect parity).

func UseElementGeometry ¶

func UseElementGeometry(parseRef DOMRef) interop.Rect

UseElementGeometry returns the zero Rect on native/SSR.

func UseFocusTrap ¶

func UseFocusTrap(parseOptions FocusTrapOptions)

UseFocusTrap is a no-op for non-browser targets.

func UseForceUpdate ¶

func UseForceUpdate() func()

UseForceUpdate returns a function that triggers a re-render of the calling component (G5). Use it after a mutation that does not change a subscribed value — an in-place edit or an external store write — instead of bumping a dummy "version" state by hand.

rerender := ui.UseForceUpdate()
... onExternalChange: rerender()

func UseGlobalKey ¶

func UseGlobalKey(handler func(KeyboardEvent), deps ...any)

UseGlobalKey subscribes to document keydown — app-wide keyboard shortcuts. To ignore keystrokes while the user is typing, check the event target in the handler (e.g. skip when document.activeElement is an input/textarea).

func UseId ¶

func UseId() string

UseId returns a stable generated identifier for the current component instance.

func UseIdle ¶

func UseIdle() bool

UseIdle returns true once the browser has reached an idle point after mount — the idle trigger (`@defer (on idle)`). It is approximated with a deferred (next-task) timeout, which schedules after the current render/commit work, where a true requestIdleCallback is unavailable.

func UseInspect ¶

func UseInspect[T any](parseLabel string, parseValue T)

UseInspect logs a labeled value whenever it changes between renders — GoWebComponents' answer to Svelte's $inspect. It records the initial value on mount and, on each subsequent render, logs an "old -> new" line when the value changed (by structural equality), routed through the current inspect sink. A pure dev aid: leave it in during development and silence it in production either at runtime with SetInspectSink(func(string){}) or, at zero per-call cost, by building with the gwcsilent tag (`go build -tags gwcsilent`), which wires the sink to a no-op.

count := ui.UseState(0)
ui.UseInspect("count", count.Get()) // logs each time count changes

func UseInteraction ¶

func UseInteraction(parseRef DOMRef) bool

UseInteraction returns true after the first pointer interaction with the referenced element — the interaction trigger (`@defer (on interaction)`), for deferring a heavy view until the user actually touches it.

func UseIntersection ¶

func UseIntersection(parseRef DOMRef, parseOptions ...interop.IntersectionObserverOptions) bool

UseIntersection returns false on native/SSR.

func UseInterval ¶

func UseInterval(parseFn func(), parseInterval time.Duration, parseDeps ...any)

UseInterval runs fn every interval while the component is mounted; cancelled on unmount or when deps change.

func UseLayoutEffect ¶

func UseLayoutEffect(parseEffect func() func(), parseDeps ...any)

UseLayoutEffect is a no-op on non-browser targets (G36).

func UseMediaQuery ¶

func UseMediaQuery(parseQuery string) bool

UseMediaQuery reports whether the given CSS media query currently matches, and re-renders the component when it changes (G20). It reflects the query at mount, updates live via the MediaQueryList change event, and releases its listener on unmount. On builds without media-query support it returns false.

wide := ui.UseMediaQuery("(min-width: 768px)")

func UseMemo ¶

func UseMemo[T any](parseCompute func() T, parseDeps ...any) T

UseMemo computes value immediately on non-browser targets.

func UseMemoOf ¶ added in v4.2.0

func UseMemoOf[T any, D comparable](parseCompute func(D) T, parseDep D) T

UseMemoOf computes directly on non-browser targets (native UseMemo parity).

func UseMount ¶

func UseMount(parseFn func() func())

UseMount runs fn once after the component first mounts and runs the returned cleanup (if any) on unmount (G38). It is the self-documenting form of the "run once" effect — clearer and safer than the UseEffect(fn, true) constant-dep idiom, which silently changes behavior if dep-equality is ever refactored.

ui.UseMount(func() func() {
    sub := subscribe()
    return func() { sub.Close() }   // cleanup on unmount
})

On the native/SSR build effects do not run, so UseMount is a no-op there (matching UseEffect).

func UseMutation ¶

func UseMutation[T any](parseCache *query.Cache, parseKey string) func(parseOptimistic T, parseFn func() (T, error)) query.Result[T]

UseMutation returns a typed mutate function bound to key in a query.Cache. Calling it applies the optimistic value to the cache immediately, runs fn, commits fn's result on success or rolls back to the exact prior state on error, then re-renders the component with the outcome. This is the one-call optimistic-update path.

like := ui.UseMutation[int](appCache, "post/"+id+"/likes")
onClick := func() {
    like(current+1, func() (int, error) { return api.Like(id) }) // optimistic +1, auto-rollback
}

func UseNetworkStatus ¶

func UseNetworkStatus() bool

UseNetworkStatus reports whether the browser is currently online and re-renders the component when connectivity changes (G32). It seeds from navigator.onLine and stays live via the window online/offline events, with the listeners released on unmount. On native/SSR builds it reports true (assume connectivity) and never changes.

online := ui.UseNetworkStatus()

func UseOptimistic ¶

func UseOptimistic[T any](parseCache *query.Cache, parseKey string) (query.Result[T], func(T))

UseOptimistic returns the current value for key plus a setter that applies an optimistic value immediately and re-renders — GoWebComponents' answer to React's useOptimistic, backed by the query cache. The optimistic value is superseded by the next authoritative write (a mutation result or a query refresh) for the same key.

value, setOptimistic := ui.UseOptimistic[int](appCache, "likes")
onClick := func() {
    setOptimistic(value.Data + 1)                       // UI updates now
    go ui.UseAsyncMutation[int](appCache, "likes")(...) // server reconciles
}

func UsePointerEvents ¶

func UsePointerEvents(parseRef DOMRef, parseHandlers PointerHandlers)

UsePointerEvents is a no-op on native/SSR.

func UsePrefersReducedMotion ¶

func UsePrefersReducedMotion() bool

UsePrefersReducedMotion reports whether the user has requested reduced motion. It reflects the media query at mount and updates live when the emulated or OS preference flips, unsubscribing on unmount (the underlying js.Func handle is released). On builds without media-query support it returns false.

func UseQuery ¶

func UseQuery[T any](parseCache *query.Cache, parseKey string, parseFetcher func() (T, error), parseDeps ...any) query.Result[T]

UseQuery subscribes the calling component to a key in a query.Cache and returns the current result. It renders cached data immediately (a pure, no-fetch read) and, after commit, revalidates in the background via stale-while-revalidate — re-rendering the component when fresh data lands. Re-subscribes whenever key (or any extra dep) changes.

The fetcher is an ordinary func() (T, error): no special async plumbing, and the same call works against a server-seeded cache during SSR.

func UserCard(props UserProps) ui.Node {
    res := ui.UseQuery(appCache, "user/"+props.ID, func() (User, error) {
        return api.GetUser(props.ID)
    })
    if res.Status == query.StatusLoading {
        return Spinner()
    }
    return Text(res.Data.Name) // updates in place when the background refresh resolves
}

When the fetcher closes over values that change independently of key (auth headers, a current user ID, filters), pass them as deps so the subscription re-runs with the fresh closure instead of silently using the stale one:

res := ui.UseQuery(appCache, "feed", func() (Feed, error) {
    return api.GetFeed(token) // token captured by the closure
}, token) // re-subscribe when token changes

func UseRevalidateOnFocus ¶

func UseRevalidateOnFocus(parseCache *query.Cache)

UseRevalidateOnFocus wires the standard SWR freshness triggers: when the tab regains focus or the browser comes back online, every cached query is marked stale and the component re-renders, so its UseQuery hooks revalidate against the server. Mount it once near the app root. It is a no-op on native/SSR (no window).

func App(props AppProps) ui.Node {
    ui.UseRevalidateOnFocus(appCache) // refetch stale data on focus / reconnect
    ...
}

func UseSpring ¶

func UseSpring(parseTarget float64, parseConfig anim.SpringConfig) float64

UseSpring animates a float64 value toward parseTarget using a damped harmonic spring. It returns the current animated position, which updates each animation frame via requestAnimationFrame until the spring settles. It honors prefers-reduced-motion by default: when the user requests reduced motion the value snaps to the target instead of animating, with no requestAnimationFrame loop.

func UseSuspenseQuery ¶

func UseSuspenseQuery[T any](parseCache *query.Cache, parseKey string, parseFetcher func() (T, error), parseDeps ...any) T

UseSuspenseQuery is the suspending sibling of UseQuery: instead of returning a Result the caller must switch on, it returns the data directly, suspending the render until the data is ready and throwing the error to the nearest ErrorBoundary on failure. Wrap the subtree in an AsyncBoundary (for the loading fallback) and an ErrorBoundary (for failures); the component body then reads the value unconditionally — the React use(promise) / Solid createResource shape.

func UserCard(props UserProps) ui.Node {
    user := ui.UseSuspenseQuery(appCache, "user/"+props.ID, func() (User, error) {
        return api.GetUser(props.ID)
    })
    return Text(user.Name) // no Status switch — AsyncBoundary shows the fallback while loading
}

Like UseQuery, pass deps when the fetcher closes over values that change independently of key; changing key or any dep starts a fresh load (and re-suspends until it resolves).

func UseTheme ¶

func UseTheme(parseDefault string) (string, func(string))

UseTheme subscribes the calling component to the active theme name and returns it together with a setter. Switching the theme (via the returned setter or SetTheme) re-renders every UseTheme subscriber and applies the name to <html data-theme="..."> so `[data-theme="..."]` CSS rules and :root token overrides take effect. It is the reactive capstone over the typed-CSS token system (css.Theme.RootRules / css.Var): style with tokens, switch with UseTheme.

theme, setTheme := ui.UseTheme("dark")
onClick := ui.UseEvent(func() {
    if theme == "dark" { setTheme("light") } else { setTheme("dark") }
})

Seed from the OS preference by passing it as the default:

theme, setTheme := ui.UseTheme(string(ui.UsePrefersColorScheme()))

func UseTimeout ¶

func UseTimeout(parseFn func(), parseDelay time.Duration, parseDeps ...any)

UseTimeout runs fn once after delay while the component is mounted; it is cancelled (and its js.Func released) on unmount or when deps change.

func UseTimerTrigger ¶

func UseTimerTrigger(parseDelay time.Duration) bool

UseTimerTrigger returns true once delay has elapsed since mount — the timer trigger for a deferred view (Angular `@defer (on timer(...))`).

func UseWheel ¶

func UseWheel(parseRef DOMRef, parseHandler func(Event))

UseWheel is a no-op on native/SSR.

func UseWindowEvent ¶

func UseWindowEvent(eventType string, handler func(Event), deps ...any)

UseWindowEvent subscribes the calling component to a window-level event (resize, scroll, hashchange, …) for as long as it is mounted.

func ViewTransition ¶

func ViewTransition(parseApply func())

ViewTransition calls apply directly on non-browser builds (no View Transitions API). See the wasm implementation for the animated path.

func WithCorrelationID ¶

func WithCorrelationID(parseCtx context.Context, parseId string) context.Context

WithCorrelationID stores a correlation ID in the request context. Retrieve it later with CorrelationIDFromContext.

func WithW3CTraceContext ¶

func WithW3CTraceContext(parseCtx context.Context, parseTc W3CTraceContext) context.Context

WithW3CTraceContext stores a W3CTraceContext in ctx. WrapSSRCorrelation calls this automatically when a valid traceparent is present.

func WrapSSRCorrelation ¶

func WrapSSRCorrelation(parseNext http.Handler) http.Handler

WrapSSRCorrelation is an HTTP middleware that propagates per-request trace context following W3C Trace Context (https://www.w3.org/TR/trace-context/) and common correlation ID conventions.

Resolution order:

1. W3C traceparent header — trace-id used as the correlation ID; a new span ID is generated for this server operation; traceparent is written to the response.
2. X-Correlation-ID, X-Request-ID, X-Trace-ID — used as-is; a synthetic W3CTraceContext is generated using the value as the trace ID.
3. Generated — a fresh OTel-compatible 128-bit trace ID and 64-bit span ID are generated using crypto/rand.

For every request the middleware:

• stores the correlation ID in ctx (retrieve with CorrelationIDFromContext)
• stores W3CTraceContext in ctx (retrieve with TraceContextFromContext)
• writes X-Correlation-ID and Traceparent to the response
• forwards the incoming Tracestate header unchanged

Security note: correlation IDs must not encode user IDs, session tokens, or sensitive metadata. The middleware does not validate incoming header values beyond structural format — callers are responsible for ensuring IDs are opaque.