useStore - Metabind

useStore<T>(key: string, defaultValue: T, scope?: string): Store<StoreShape<T>>;

key

string

required

A unique identifier for this store. All components that call useStore with the same key share the same state.

defaultValue

required

The initial value for the store. Objects are stored as-is. Primitives are wrapped in { value: T } automatically.

scope

string

An optional namespace for the store key. The resolved key becomes "scope:key". Use this to isolate stores per-instance (e.g. pass a user ID or item ID as the scope).

Returns

A Store object that combines:

State fields — All properties from the default value, readable directly (e.g. store.count, store.name).
Per-field setters — Auto-generated set<FieldName>() methods for each property (e.g. store.setCount(5)). Each setter accepts a direct value or an updater function (prev) => next.
set(value) — Replaces the entire store value. Accepts a direct value or an updater function (prev) => next.
Metadata — key (the key passed to useStore), scope (the scope, if provided), and fullKey (the resolved key "scope:key" or "key").

Usage

Basic object store

const body = () => {
    const user = useStore("user", {
        name: "John",
        age: 30,
        email: "john@example.com"
    })

    return VStack([
        Text("Name: " + user.name),
        Text("Age: " + String(user.age)),
        Button("Birthday", () => user.setAge(user.age + 1)),
        Button("Rename", () => user.setName("Jane"))
    ])
}

Primitive values

Primitives are wrapped in { value: T }, so the setter is setValue:

const body = () => {
    const counter = useStore("counter", 0)

    return VStack([
        Text("Count: " + String(counter.value)),
        Button("Increment", () => counter.setValue(counter.value + 1))
    ])
}

Functional updates

All setters accept an updater function for updates based on the previous value:

const body = () => {
    const counter = useStore("counter", { count: 0 })

    return VStack([
        Text("Count: " + String(counter.count)),
        Button("Increment", () => {
            counter.setCount(prev => prev + 1)
        })
    ])
}

Scoped stores

Use the scope parameter to namespace stores per-instance:

const body = (props) => {
    const prefs = useStore("prefs", {
        theme: "light",
        fontSize: 16
    }, props.userId)

    // Full key: "userId123:prefs"
    return VStack([
        Text("Theme: " + prefs.theme),
        Button("Toggle Theme", () => {
            prefs.setTheme(prefs.theme === "light" ? "dark" : "light")
        })
    ])
}

Replacing the entire store

const body = () => {
    const profile = useStore("profile", {
        name: "John",
        bio: "Developer"
    })

    return VStack([
        Button("Reset", () => {
            profile.set({ name: "Anonymous", bio: "" })
        }),
        Button("Uppercase Name", () => {
            profile.set(prev => ({
                ...prev,
                name: prev.name.toUpperCase()
            }))
        })
    ])
}

Shared state across components

Stores are shared by key, so separate components can read and write the same state:

// Component A
const body = () => {
    const cart = useStore("cart", { items: [], total: 0 })
    return Text("Cart total: $" + String(cart.total))
}

// Component B
const body = () => {
    const cart = useStore("cart", { items: [], total: 0 })
    return Button("Add Item", () => {
        cart.setTotal(cart.total + 9.99)
    })
}

Notes

Store state is global and persists across re-renders. Any component that calls useStore with the same key (and scope) shares the same state instance.
The defaultValue is only used when the store is first created. Subsequent calls with the same key return the existing state regardless of the defaultValue passed.
Updates to the store trigger re-renders in all components that read from it.
For component-local state that does not need to be shared, use useState instead.
useStore must be called inside a component body function, not at the top level.

​Returns

​Usage

​Basic object store

​Primitive values

​Functional updates

​Scoped stores

​Replacing the entire store

​Shared state across components

​Notes