state

func UseAtom ¶

func UseAtom[T any](parseId string, parseInitialValue T) Atom[T]

UseAtom provides shared global atoms with subscription-scoped rerenders. Atoms are accessible from anywhere in the component tree by ID and automatically trigger re-renders in all subscribed components when updated.

The first component to call UseAtom with a specific ID initializes the atom with the provided initial value. Subsequent calls from other components will use the existing value and subscribe to updates.

Type parameter T can be any Go type. The hook uses generic type parameters for type safety.

Returns an Atom[T] handle with Get, Set, and Update methods.

Example - Theme Management:

// In a theme-switcher component
theme := state.UseAtom("appTheme", "light")

toggle := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
    if theme.Get() == "light" {
        theme.Set("dark")
    } else {
        theme.Set("light")
    }
    return nil
})

// In a header component — re-renders automatically when theme changes
theme := state.UseAtom("appTheme", "light")
bgColor := "white"
if theme.Get() == "dark" {
    bgColor = "#333"
}

Example - User Authentication:

type User struct {
    ID       int
    Username string
    Email    string
}

user := state.UseAtom("currentUser", User{})

login := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
    user.Set(User{ID: 1, Username: "johndoe", Email: "john@example.com"})
    return nil
})

if user.Get().ID == 0 {
    // render login button
} else {
    // render welcome message using user.Get().Username
}

Thread Safety: UseAtom is thread-safe and can be safely called from multiple goroutines. The internal atom registry uses mutex-based synchronization.

Cleanup: When a component unmounts, it is automatically unsubscribed from all atoms to prevent memory leaks and unnecessary updates.

Best Practices:

• Use descriptive atom IDs (e.g., "currentUser", "appTheme", "shoppingCart")
• Initialize atoms with appropriate default values
• Use structured types (structs) for complex state
• Avoid storing large amounts of data in atoms (use for coordination, not caching)

package main

import (
	"github.com/monstercameron/GoWebComponents/v4/state"
)

func main() {
	parseCount := state.UseAtom("counter", 0)
	parseDoubled := state.UseComputed(func() int { return parseCount.Get() * 2 })
	// Both update together when the atom changes.
	_ = parseDoubled
}

Output:

func UseAtomKey ¶

func UseAtomKey[T any](parseKey AtomKey[T]) Atom[T]

UseAtomKey subscribes the current component to a typed atom key — the typed sibling of UseAtom. Prefer it over UseAtom for any atom shared across components or packages, so the id, type, and default are declared once and can't drift between call sites.

func NewAtomKey ¶

func NewAtomKey[T any](parseID string, parseInitial T) AtomKey[T]

NewAtomKey declares a typed atom key. Call it once at package scope and reuse the returned value.

func NewAutoComputed ¶

func NewAutoComputed[T any](parseCompute func() T) ComputedSignal[T]

NewAutoComputed derives a value from compute, AUTO-DISCOVERING its reactive sources by running compute once with read-tracking on and recording which signals it read (Solid-style auto-tracking). It is the opt-in sibling of NewComputed; explicit dependency declaration (NewComputed) remains the default and recommended path per GWC's no-hidden-graph design, so auto-tracking is a convenience, not a replacement.

a := state.NewSignal(2)
b := state.NewSignal(3)
sum := state.NewAutoComputed(func() int { return a.Get() + b.Get() }) // a, b discovered

func NewComputed ¶

func NewComputed[T any](parseCompute func() T, parseSources ...reactiveSource) ComputedSignal[T]

NewComputed derives a value from compute, declaring the reactive sources it depends on. Dependencies are explicit by design: only changes to the named sources are guaranteed to refresh consumers bound through ui.ReactiveRegion.

first := state.NewSignal("Ada")
last := state.NewSignal("Lovelace")
full := state.NewComputed(func() string { return first.Get() + " " + last.Get() }, first, last)

func UseDerived ¶

func UseDerived[T any](parseId string, parseCompute func() T, parseDeps ...string) Derived[T]

UseDerived registers and subscribes to a read-only derived atom.

Derived atoms are shared state values keyed by id. They recompute when one of the named source atom IDs changes and expose a typed read-only handle to the current derived value. Dependency tracking is explicit through atom IDs so recomputation remains predictable and avoids hidden runtime graph discovery.

The id is GLOBAL and shared — this is intentional and is the whole point: two components that pass the same id share one derived atom (the same model as UseAtom). That deliberately differs from UseSelector, whose id is auto-scoped to the calling component because a selector is a component-local projection, not shared state. So: pick a unique, descriptive id for a UseDerived you intend to share, exactly as you would for a UseAtom; reach for UseSelector when you want a local, collision-free projection instead.

func UseSelector ¶

func UseSelector[T any, U any](parseId string, parseSource selectorSource[T], parseProject func(T) U) Derived[U]

UseSelector creates a read-only projected shared value from an atom or derived source.

The selector remains explicit: callers provide the derived ID to register and the source handle to project from. When the projected value is unchanged, subscribers are not notified, which makes it suitable for fine-grained hot-value paths.

func NewGlobalAtom ¶

func NewGlobalAtom[T any](parseID string, parseDefault T) GlobalAtom[T]

NewGlobalAtom returns a handle for the atom identified by id and seeds the registry with defaultValue if (and only if) the atom has no value yet. Seeding never notifies subscribers and never clobbers an existing value, so it is safe to construct at package-init time or after an external write.

func NewKeyedSignal ¶

func NewKeyedSignal[T any](parseID string, parseInitial T) Signal[T]

NewKeyedSignal creates a signal with an explicit, shared id, so independent call sites can address the same reactive value (the way UseAtom does). Prefer NewSignal unless the shared identity is the point. Call sites sharing an id must agree on the initial value.

func NewSignal ¶

func NewSignal[T any](parseInitial T) Signal[T]

NewSignal creates a fine-grained reactive value seeded with initial.

It may be called anywhere — including outside a component render (package init, event handlers, goroutines) — because, unlike a hook, it does not depend on call order within a render. Each call mints a fresh, process-unique identity; use NewKeyedSignal when several call sites must address the same signal.

func GetSnapshot ¶

func GetSnapshot() (Snapshot, error)

GetSnapshot returns a copy of all atoms currently registered in the global runtime.

The returned snapshot preserves in-memory Go values exactly for same-process restore via ApplySnapshot. When serializing to JSON or browser storage, only JSON-compatible atom values should be relied on as stable persisted data.

func LoadPersistentSnapshot ¶

func LoadPersistentSnapshot(parseCtx context.Context, parseKey string, parseOptions ...PersistentSnapshotOptions) (Snapshot, bool, error)

LoadPersistentSnapshot reads and decodes a snapshot from IndexedDB-first durable browser storage.

If parseCtx is nil it is replaced with context.Background(). If parseCtx is already cancelled the underlying store resolver will receive a cancelled context and is expected to return an error, which is propagated to the caller.

func LoadSnapshot ¶

func LoadSnapshot(parseKey string, parseArea StorageArea) (Snapshot, bool, error)

LoadSnapshot reads and decodes a snapshot from browser storage.

func UnmarshalSnapshotJSON ¶

func UnmarshalSnapshotJSON(parseData []byte) (Snapshot, error)

UnmarshalSnapshotJSON decodes a JSON snapshot produced by MarshalSnapshotJSON.