This is the full developer documentation for Valdres — reactive state management for React, Vue, Svelte, Solid, and Angular. Shared (core/plugin) pages are included once; they exist per framework at /react/…, /vue/…, /svelte/…, /solid/…, /angular/… with the examples adapted.
Source: https://valdres.dev/react/atom.md
# atom
Signature
`atom(defaultValue: T, options?: AtomOptions): Atom`
valdres
Creates a reactive piece of state
An atom holds a single value that can be read and written from any component or outside of React entirely.
## Usage
```ts
import { atom } from "valdres"
// Simple atom with a default value
const countAtom = atom(0)
// Atom with an async initializer
const userAtom = atom(() =>
fetch("/api/user").then(res => res.json())
)
// With a name for debugging and error messages
const nameAtom = atom("default", { name: "nameAtom" })
```
## Parameters
| Parameter | Type | Description |
| ------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultValue` | `T \| () => T \| Promise` | Initial value, or a function that returns one |
| `options.name` | `string` | Optional name for debugging, devtools, and validation error messages |
| `options.schema` | `Schema` | Schema for runtime validation and type inference. A no-op unless validation is enabled. See [Schema Validation](https://valdres.dev/guides/schema-validation). |
| `options.schemaValidation` | `boolean` | Per-atom override of the store's `schemaValidation` flag — `true` always validates this atom, `false` exempts it |
| `options.mutable` | `boolean` | Opt out of development/test deep-freezing. Required for mutable built-ins and host objects that cannot be frozen safely. |
| `options.maxAge` | `Reactive` | Re-fetch interval in milliseconds (requires async default). Accepts a number, atom, or selector. |
| `options.staleWhileRevalidate` | `Reactive` | Serve stale data for this many ms while re-fetching. Accepts a number, atom, or selector. |
| `options.staleIfError` | `Reactive` | Serve stale data for this many ms after re-fetch errors. Accepts a number, atom, or selector. |
## Immutability and exotic values
In development mode, Valdres deep-freezes immutable values on every accepted
write so accidental in-place changes fail immediately. This includes plain
object and array atom values; Error objects and Promise handles remain usable
while their object surface is frozen. Production builds skip this development
check.
In runtimes with `process.env`, `NODE_ENV` selects the mode. Process-less CDN
and edge runtimes default to production. To select the process-less debugging
entry and retain development-only deep-freeze, validation diagnostics, warnings,
and instrumentation, enable the package's `development` export condition in the
bundler consistently across the entire application, including framework
adapters. Do not mix default and development entrypoints: they intentionally
use isolated runtime graphs.
No-build CDN users can request the published `dist/development/index.js` file
directly. That raw entry must not be combined with an adapter resolved from the
default package entry; adapter applications should use the bundler condition so
both the public and adapter-internals entrypoints select the development graph.
Bun's bundler enables the `development` export condition by default. Use
`bun build --production` when building a production process-less or edge app;
adding only `--conditions=production` does not disable Bun's development
condition.
`Object.freeze` cannot make mutable built-ins or host objects reliably
immutable. This includes `Map`, `Set`, `WeakMap`, `WeakSet`, `Date`,
`ArrayBuffer`, `SharedArrayBuffer`, `DataView`, typed arrays, browser API
objects, and other branded exotic values. Valdres rejects such values with an
actionable error instead of storing something that only appears frozen.
Ordinary class instances have their own property graph frozen, like plain
objects. Store an immutable plain-data representation when possible, or opt out
explicitly:
```ts
const bytesAtom = atom(new Uint8Array(), { mutable: true })
```
With `mutable: true`, Valdres does not protect the value from in-place changes.
Use replacement updates (or an appropriate custom `equal` function) so writes
still produce notifications. The default equality function compares binary
buffers and views by their visible bytes.
It compares every own enumerable property, including symbol-keyed ones and
properties set alongside the contents of an array, `Map`, or `Set`, so a write
that changes only one of those is still a change. A custom `valueOf` or
`toString` narrows the comparison but never replaces it — two values that
stringify alike but hold different properties are different values.
Binary buffers and views are the one exception: they are compared by their
bytes alone. Enumerating the keys of a typed array costs time proportional to
its length, so properties attached beside the bytes are not compared — keep
such metadata in a separate atom.
## Async atoms
> **Tip**
>
>
> When you pass a function as the default value, it becomes an async atom. The function is called lazily — only when the atom is first read.
In React, async atoms work seamlessly with `Suspense`:
```ts
const dataAtom = atom(async () => {
const res = await fetch("/api/data")
return res.json()
})
```
## Caching & revalidation
Async atoms support built-in stale-while-revalidate caching via `maxAge`, `staleWhileRevalidate`, and `staleIfError`. This is useful for data that should periodically refresh from an API while keeping the UI responsive.
### maxAge
Sets how often the atom re-fetches its data (in milliseconds). Revalidation only happens while the atom has active subscribers.
```ts
const pricesAtom = atom(
async () => {
const res = await fetch("/api/prices")
return res.json()
},
{ maxAge: 30_000 }, // Re-fetch every 30 seconds
)
```
When `maxAge` expires, the atom calls its default function again. Without `staleWhileRevalidate`, the atom immediately enters a loading state (returns a pending promise), which triggers `Suspense` in React.
### staleWhileRevalidate
Keeps serving the previous value while the re-fetch is in progress, instead of showing a loading state. The value updates seamlessly once the new data resolves.
```ts
const pricesAtom = atom(
async () => {
const res = await fetch("/api/prices")
return res.json()
},
{
maxAge: 30_000, // Re-fetch every 30s
staleWhileRevalidate: 60_000, // Serve stale data for up to 60s while fetching
},
)
```
This means your UI never shows a loading spinner on re-fetches — users see the previous data until the fresh data arrives.
### staleIfError
Extends the stale window when re-fetches fail. Instead of surfacing an error to the UI, the atom keeps serving the last successful value for the specified duration.
```ts
const pricesAtom = atom(
async () => {
const res = await fetch("/api/prices")
if (!res.ok) throw new Error("API error")
return res.json()
},
{
maxAge: 30_000,
staleWhileRevalidate: 60_000,
staleIfError: 300_000, // Keep stale data for up to 5 minutes on errors
},
)
```
If the re-fetch fails within the `staleIfError` window (measured from the last successful fetch), the previous value is preserved. Once the window expires, the rejected promise is surfaced so error boundaries can handle it.
### Example: API response with caching
```ts
import { atom } from "valdres"
type User = { id: string; name: string; email: string }
const currentUserAtom = atom(
async () => {
const res = await fetch("/api/me", {
headers: { Authorization: `Bearer ${getToken()}` },
})
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
return res.json()
},
{
maxAge: 60_000, // Refresh every minute
staleWhileRevalidate: 120_000, // Show stale for 2 min while fetching
staleIfError: 300_000, // Tolerate errors for 5 min
},
)
```
**Timeline of behavior:**
| Time | Event | What the UI sees |
| ------- | ----------------------------------- | ----------------------------------- |
| 0s | First read, fetch starts | Suspense loading state |
| \~200ms | Fetch resolves | User data |
| 60s | `maxAge` expires, re-fetch starts | Previous user data (SWR) |
| \~60.2s | Re-fetch resolves | Updated user data |
| 120s | `maxAge` expires, re-fetch fails | Previous user data (`staleIfError`) |
| 180s | `maxAge` expires, re-fetch succeeds | Fresh user data |
> **Note**
>
>
> Revalidation is only active while the atom has subscribers. When all components unsubscribe, the interval is cleared. The next subscription triggers a fresh fetch.
### Reactive cache configuration
Cache options can be dynamic by passing an atom or selector instead of a static number. When the config value changes, the revalidation interval automatically restarts with the new timing.
```ts
import { atom, selector } from "valdres"
const refreshIntervalAtom = atom(30_000)
const pricesAtom = atom(
async () => {
const res = await fetch("/api/prices")
return res.json()
},
{ maxAge: refreshIntervalAtom },
)
// Changing the interval updates the revalidation schedule
store.set(refreshIntervalAtom, 5_000) // now refreshes every 5 seconds
```
You can also use a selector to derive the interval from other state:
```ts
const realtimeModeAtom = atom(false)
const maxAgeSelector = selector(get =>
get(realtimeModeAtom) ? 1_000 : 30_000
)
const dataAtom = atom(
async () => fetch("/api/data").then(r => r.json()),
{ maxAge: maxAgeSelector },
)
```
### cacheMeta
Use `cacheMeta()` to get a reactive selector that exposes the caching state of an atom. This is useful for showing loading indicators during revalidation or displaying when data was last refreshed.
```ts
import { atom, cacheMeta } from "valdres"
const dataAtom = atom(
async () => fetch("/api/data").then(r => r.json()),
{ maxAge: 30_000, staleWhileRevalidate: 60_000 },
)
const meta = store.get(cacheMeta(dataAtom))
// {
// isRevalidating: false,
// lastSuccessAt: 1713100800000,
// maxAge: 30000,
// staleWhileRevalidate: 60000,
// staleIfError: undefined,
// }
```
`cacheMeta()` returns a selector, so you can subscribe to it reactively:
```ts
const dataMeta = cacheMeta(dataAtom)
store.sub(dataMeta, () => {
const meta = store.get(dataMeta)
console.log(meta?.isRevalidating) // true when re-fetching
console.log(meta?.lastSuccessAt) // timestamp of last success
})
```
Returns `null` for atoms that don't have `maxAge` configured.
## Schema validation
Pass a `schema` — any [Standard Schema](https://standard-schema.dev) (Zod,
Valibot, ArkType, …) or `parse()`-style validator — to validate the atom's
values at runtime and infer its type without a generic:
```ts
import { atom, store } from "valdres"
import { z } from "zod"
// Typed Atom from the schema — no generic needed
const nameAtom = atom(undefined, { name: "nameAtom", schema: z.string() })
// Validation is opt-in per store (off by default)
const s = store({ schemaValidation: true })
s.set(nameAtom, 42) // throws SchemaValidationError naming 'nameAtom'
```
Validation is validate-only (the original value is stored unchanged) and can be
overridden per atom via `schemaValidation: true | false`. See the
[Schema Validation guide](https://valdres.dev/guides/schema-validation) for error handling, async
behavior, and limitations.
## See also
- [globalAtom](https://valdres.dev/valdres/globalAtom) — share a single atom's value across every store
- [atomFamily](https://valdres.dev/valdres/atomFamily) — create a collection of atoms keyed by a parameter
- [selector](https://valdres.dev/valdres/selector) — derive computed state from atoms
- [Schema Validation](https://valdres.dev/guides/schema-validation) — runtime validation and type inference
- [useAtom](https://valdres.dev/react/useAtom) — read and write an atom in your components
---
Source: https://valdres.dev/react/atomFamily.md
# atomFamily
Signature
`atomFamily(defaultFactory?: (key: K) => T, options?: AtomFamilyOptions): AtomFamily`
valdres
Create a keyed collection of atoms
Creates a family of atoms keyed by a parameter. Useful for collections of entities like users, todos, or items where each instance needs its own piece of state.
## Usage
```ts
import { atomFamily } from "valdres"
// Simple family with no default
const todoAtom = atomFamily()
store.set(todoAtom("abc-123"), { title: "Buy milk", done: false })
store.get(todoAtom("abc-123")) // { title: "Buy milk", done: false }
```
## With a default value factory
Pass a function that receives the key and returns the default value:
```ts
const userAtom = atomFamily(id => ({
id,
name: "",
email: "",
}))
// The default is generated when first accessed
store.get(userAtom("user-1")) // { id: "user-1", name: "", email: "" }
```
## Global families
Use [`globalAtomFamily`](https://valdres.dev/valdres/globalAtomFamily) to share each member's value
across stores. `options.name` is required — a global family is addressed by
it, so omitting it is a type error and remains a runtime error for untyped
JavaScript.
```ts
import { globalAtomFamily } from "valdres"
const featureFlagAtom = globalAtomFamily((key: string) => false, {
name: "app/feature-flags",
})
```
Re-defining a family under the same name returns the existing family instead of
creating a second one. Selectors do not have a global counterpart.
## Key identity
Family calls are keyed by a deterministic structural encoding. Primitive types,
argument count, Arrays, plain Objects, Dates, Maps, and Sets remain distinct;
object property order and Map/Set insertion order do not affect identity.
`BigInt` is supported too.
Values without deterministic structural semantics—such as Symbols, functions,
Promises, class instances, accessor properties, and cyclic structures—throw a
`TypeError`. Use `keyOf` to derive a supported identity for those arguments, or
to intentionally group multiple arguments:
```ts
type Entity = { id: string; self?: Entity }
const entityAtom = atomFamily(entity => entity, {
keyOf: entity => entity.id,
})
```
`keyOf` receives the same argument tuple as the family factory. Its result is
run through the same canonical codec.
> **Transferred families need JSON-safe args**
>
>
> Key identity is wider than JSON on purpose — it is a local, in-process
> concern. But `dehydrate` emits family args raw (schemas encode _values_, not
> keys) and `hydrate` re-derives each member with `family(...args)` from the
> parsed payload. A `Date`, `Map`, `Set`, `BigInt`, `NaN` or `undefined`
> argument does not survive that round-trip, so the value would land on a
> phantom member while the real one keeps its default. Dev builds throw from
> `dehydrate`, naming the family and the argument path. Key transferred
> families by strings and numbers (`user(id)`, `day(date.toISOString())`) —
> `keyOf` does not help here, since the raw args are what crosses the wire.
>
> For the same reason, a named family's `keyOf` must derive its key from the
> arguments' JSON **data** (`entity => entity.id`). JSON carries no property
> descriptors, no frozen/sealed flag, and no object identity — two references
> to one object arrive as two objects — so a `keyOf` reading any of those
> returns a different key after hydration. `dehydrate` cannot detect this and
> does not try.
The legacy `release(...args)` method is deprecated and has no effect. Family
members leave the weak identity cache automatically once no caller or store can
reach them. Manual eviction could otherwise create two live member objects for
the same arguments and split their values across stores.
## Subscribing to a family
> **Tip**
>
>
> Subscribe to an entire family to be notified when any member changes. The callback receives that member's family arguments.
```ts
store.sub(todoAtom, id => {
console.log("Changed todo ID:", id)
})
```
## In React
```tsx
import { useValue } from "valdres-react"
function UserProfile({ userId }) {
const user = useValue(userAtom(userId))
return
{user.name}
}
```
## See also
- [atom](https://valdres.dev/valdres/atom) — create a single atom
- [globalAtomFamily](https://valdres.dev/valdres/globalAtomFamily) — share each member's value across every store
- [selectorFamily](https://valdres.dev/valdres/selectorFamily) — derive state from a family of atoms
- [index](https://valdres.dev/valdres/index) — reactively filter family members by a term
---
Source: https://valdres.dev/react/globalAtom.md
# globalAtom
Signature
`globalAtom(defaultValue: T, options: GlobalAtomOptions): GlobalAtom`
valdres
Creates a cross-store singleton atom
A global atom is a single shared value that stays in sync across every store
that touches it — writing in one store is immediately visible from any other.
This is the mechanism behind Valdres' `@valdres/*` browser-API packages: each
wraps one global atom around a browser subscription, so any store in the app
sees the same `online` status, `geolocation` position, and so on.
`options.name` is required — it is the atom's global address. Re-using a name
that's already registered throws.
## Usage
```ts
import { globalAtom } from "valdres"
const onlineAtom = globalAtom(navigator.onLine, { name: "app/online" })
```
Same call shape as [`atom`](https://valdres.dev/valdres/atom) — the only difference is that
`options.name` is required instead of optional.
## The self-accessors
A global atom carries three extra methods beyond the ordinary atom surface,
for reading and writing it without a `Store` handle:
```ts
onlineAtom.getSelf() // read the current value
onlineAtom.setSelf(false) // write — fans out to every store
onlineAtom.resetSelf() // restore the default value everywhere
```
These are what a browser-API package's `onMount` uses to push external events
(a `navigator.onLine` change, a geolocation update, …) into the shared value:
```ts
const onlineAtom = globalAtom(navigator.onLine, {
name: "app/online",
onMount: () => {
const update = () => onlineAtom.setSelf(navigator.onLine)
window.addEventListener("online", update)
window.addEventListener("offline", update)
return () => {
window.removeEventListener("online", update)
window.removeEventListener("offline", update)
}
},
})
```
`onMount` fires once, when the FIRST subscriber across ANY store attaches, and
its cleanup fires once, when the LAST subscriber across ALL stores detaches —
so the underlying browser subscription is shared, not duplicated per store.
## Parameters
`globalAtom` accepts the same options as [`atom`](https://valdres.dev/valdres/atom) (`schema`,
`schemaValidation`, `onSet`, `onMount`, `maxAge`, `mutable`,
`staleWhileRevalidate`, `staleIfError`) as `GlobalAtomOptions` — identical to
`AtomOptions`, except `name` is required instead of optional.
## See also
- [atom](https://valdres.dev/valdres/atom) — create a single, per-store atom
- [globalAtomFamily](https://valdres.dev/valdres/globalAtomFamily) — a keyed collection of global atoms
---
Source: https://valdres.dev/react/globalAtomFamily.md
# globalAtomFamily
Signature
`globalAtomFamily(defaultFactory: (key: K) => T, options: GlobalAtomFamilyOptions): GlobalAtomFamily`
valdres
Creates a keyed collection of cross-store singleton atoms
Combines [`atomFamily`](https://valdres.dev/valdres/atomFamily) and [`globalAtom`](https://valdres.dev/valdres/globalAtom):
each member is keyed by a parameter, and each member's value is shared across
every store that touches it.
`options.name` is required — it is the family's global address. Re-defining a
family under the same name returns the existing family instead of creating a
second one. The first definition wins: its default and options remain active,
and a development build warns that the later definition was ignored. This makes
hot-module re-evaluation safe without silently changing live global state. A
detectable contract mismatch, such as reusing an atom's name or changing the
detectable `keyOf` arity, throws instead.
## Usage
```ts
import { globalAtomFamily } from "valdres"
const featureFlagAtom = globalAtomFamily((key: string) => false, {
name: "app/feature-flags",
})
featureFlagAtom("dark-mode").setSelf(true)
```
Same call shape as [`atomFamily`](https://valdres.dev/valdres/atomFamily) — the only difference
is that `options.name` is required instead of optional.
Each member carries the same `getSelf` / `setSelf` / `resetSelf` accessors as
a plain [`globalAtom`](https://valdres.dev/valdres/globalAtom#the-self-accessors):
```ts
const flag = featureFlagAtom("dark-mode")
flag.getSelf() // read without a Store handle
flag.setSelf(true)
```
## Parameters
`globalAtomFamily` accepts the same options as
[`atomFamily`](https://valdres.dev/valdres/atomFamily) (`keyOf`, plus every `AtomOptions` field)
as `GlobalAtomFamilyOptions` — identical to `AtomFamilyOptions`, except `name`
is required instead of optional.
## See also
- [globalAtom](https://valdres.dev/valdres/globalAtom) — a single cross-store atom
- [atomFamily](https://valdres.dev/valdres/atomFamily) — a per-store keyed collection of atoms
---
Source: https://valdres.dev/react/index.md
# index
Signature
`index(family: AtomFamily, predicate: (value: Value, term: Term) => boolean, options?: IndexOptions): (term: Term) => Selector[]>`
valdres
Create memoized reactive family filters
`index` creates a memoized selector for each search term. Each selector returns
the atoms in an `atomFamily` whose current values satisfy the predicate.
```ts
import { atomFamily, index, store } from "valdres"
const post = atomFamily<{ title: string; tags: string[] }, [string]>(null)
const postsByTag = index(
post,
(value, tag: string) => value.tags.includes(tag),
{ name: "postsByTag" },
)
const app = store()
app.set(post("one"), { title: "First post", tags: ["news"] })
app.get(postsByTag("news")) // [post("one")]
```
## Reactive-filter semantics
Despite its name, `index` is a reactive filter rather than a materialized
database index. The first read for a term is O(n) in the number of family
members. After a member changes, its predicate selector is the only predicate
that recomputes. If its boolean result is unchanged, equality pruning stops
there in O(1). If the result flips, the term selector walks the family to
preserve the ordered array result, so a membership-changing update is O(n).
This is a good fit for modest collections and for queries whose predicate is
more expensive than walking the family. For large, frequently updated
collections that require sublinear writes, maintain a lookup structure in store
state as part of the same transaction that changes the source family.
Term selectors are cached weakly. Repeated calls return the same selector while
a caller or live store dependency graph retains it, but querying many one-off
terms does not retain every selector and term for the lifetime of the `index`
function.
## Term identity and `keyOf`
Terms use the same collision-safe structural key codec as `atomFamily` and
`selectorFamily`. Primitive types remain distinct, while plain Object property
order and Map/Set insertion order do not affect identity. Symbols, functions,
Promises, class instances, accessor properties, and cyclic structures are not
supported by default.
Use `keyOf` to derive supported identity for one of those terms, or to
intentionally group multiple term objects:
```ts
type Query = { tag: string; uiState: Map }
const postsByQuery = index(
post,
(value, query: Query) => value.tags.includes(query.tag),
{ keyOf: query => query.tag },
)
```
`keyOf` receives the term and its result is encoded by the canonical family-key
codec.
## See also
- [atomFamily](https://valdres.dev/valdres/atomFamily) — create the source collection
- [selectorFamily](https://valdres.dev/valdres/selectorFamily) — create arbitrary keyed derivations
- [selector](https://valdres.dev/valdres/selector) — derive a single value
---
Source: https://valdres.dev/react/plugins/bandwidth.md
# bandwidth
Download/upload speed, latency, and jitter from a live measurement, as async global atoms.
> **Runs a measurement**
>
>
> Reading a measured atom triggers a download/upload test on first subscribe. Call `invalidateMeasurement()` to discard the result and re-run.
## Install
```bash
bun add @valdres/bandwidth
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/bandwidth](https://valdres.dev/react/plugins/bandwidth)
## Usage
```tsx
import { Suspense } from "react"
import { useValue } from "valdres-react"
import { downloadSpeedAtom, latencyAtom } from "@valdres/bandwidth"
function Speed() {
const download = useValue(downloadSpeedAtom)
const latency = useValue(latencyAtom)
return {download.toFixed(1)} Mbps · {latency.toFixed(0)} ms
}
// The measured atoms suspend until the test resolves
export function App() {
return (
)
}
```
## Exports
| Export | Kind | Type |
| ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `downloadSpeedAtom` | atom (read-only, async) | `number` — Mbps |
| `uploadSpeedAtom` | atom (read-only, async) | `number` — Mbps |
| `latencyAtom` | atom (read-only, async) | `number` — ms |
| `jitterAtom` | atom (read-only, async) | `number` — ms |
| `measurementStatusAtom` | atom (settable) | `MeasurementStatus` |
| `lastMeasurementAtom` | atom (settable) | `number \| null` — timestamp |
| `invalidateOnAtom` | atom (settable) | `GlobalAtom[]` |
| `measureBandwidth` | util fn | `(options?: MeasureBandwidthOptions) => Promise` |
| `invalidateMeasurement` | util fn | `() => void` |
| `MeasurementStatus` | type | `"idle" \| "measuring-latency" \| "measuring-download" \| "measuring-upload" \| "complete" \| "error"` |
| `BandwidthResult` | type | `{ downloadMbps, uploadMbps, latencyMs, jitterMs, timestamp: number }` |
| `MeasureBandwidthOptions` | type | `{ latencySamples?, maxDurationMs?, minDurationMs?, warmupMs?, startStreams?, maxStreams?, stabilityThreshold?: number; signal?: AbortSignal; fresh?: boolean }` |
## Cross-framework
One in-flight measurement is shared across every store and framework. `invalidateMeasurement()` clears the result and, if anything is subscribed, kicks off a fresh run.
---
Source: https://valdres.dev/react/plugins/browser-color-scheme.md
# browser-color-scheme
Reads the user's OS-level `prefers-color-scheme` preference and keeps it in sync via a media-query listener. Exposes the raw value plus boolean selectors.
## Install
```bash
bun add @valdres/browser-color-scheme
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-color-scheme](https://valdres.dev/react/plugins/browser-color-scheme)
## Usage
```tsx
import { useValue } from "valdres-react"
import { colorSchemeAtom, isDarkSelector } from "@valdres/browser-color-scheme"
function Theme() {
const scheme = useValue(colorSchemeAtom) // "dark" | "light"
const isDark = useValue(isDarkSelector)
return {scheme}
}
```
## Exports
| Export | Kind | Type |
| ----------------- | ---------------- | ------------------- |
| `colorSchemeAtom` | atom (read-only) | `"dark" \| "light"` |
| `isDarkSelector` | selector | `boolean` |
| `isLightSelector` | selector | `boolean` |
## Cross-framework
A global atom plus derived selectors — works in every framework. For full theme management (system preference + user override + persistence), use `@valdres/color-mode`, which builds on top of this.
---
Source: https://valdres.dev/react/plugins/browser-contrast.md
# browser-contrast
Wraps the `prefers-contrast` media query as a global atom (`"no-preference" | "more" | "less" | "custom"`), plus boolean selectors for the `more`/`less` cases.
## Install
```bash
bun add @valdres/browser-contrast
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-contrast](https://valdres.dev/react/plugins/browser-contrast)
## Usage
```tsx
import { useValue } from "valdres-react"
import { contrastAtom, prefersMoreContrastSelector } from "@valdres/browser-contrast"
function ContrastBadge() {
const contrast = useValue(contrastAtom)
const more = useValue(prefersMoreContrastSelector)
return {contrast}
}
```
## Exports
| Export | Kind | Type |
| ----------------------------- | ---------------- | ------------------------------------------------- |
| `contrastAtom` | atom (read-only) | `Contrast` |
| `prefersMoreContrastSelector` | selector | `boolean` |
| `prefersLessContrastSelector` | selector | `boolean` |
| `Contrast` | type | `"no-preference" \| "more" \| "less" \| "custom"` |
## Cross-framework
`contrastAtom` is global: identical in every framework, only the read primitive's name changes (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` / `store.sub` in plain JS). The browser subscription starts on the first subscriber across all stores and stops when the last leaves.
---
Source: https://valdres.dev/react/plugins/browser-device-motion.md
# browser-device-motion
Wraps the `devicemotion` event as global atoms — linear acceleration and rotation rate, plus derived selectors. Values are usually `null` on desktop.
> **Permission**
>
>
> iOS gates motion behind a user gesture — call `requestMotionPermission()` from a click before subscribing.
## Install
```bash
bun add @valdres/browser-device-motion
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-device-motion](https://valdres.dev/react/plugins/browser-device-motion)
## Usage
```tsx
import { useValue } from "valdres-react"
import {
accelerationSelector,
rotationRateSelector,
requestMotionPermission,
} from "@valdres/browser-device-motion"
function Motion() {
const accel = useValue(accelerationSelector) // Vector3 | null
const rot = useValue(rotationRateSelector) // RotationRateSnapshot | null
return (
{JSON.stringify({ accel, rot }, null, 2)}
)
}
```
## Exports
| Export | Kind | Type |
| -------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `motionAtom` | atom (read-only) | `MotionSnapshot \| null` |
| `permissionAtom` | atom (read-only) | `PermissionValue` |
| `motionStatusAtom` | atom (read-only) | `MotionStatus` |
| `accelerationSelector` | selector | `Vector3 \| null` |
| `accelerationIncludingGravitySelector` | selector | `Vector3 \| null` |
| `accelerationMagnitudeSelector` | selector | `number \| null` |
| `rotationRateSelector` | selector | `RotationRateSnapshot \| null` |
| `intervalSelector` | selector | `number \| null` |
| `requestMotionPermission` | util fn | `() => Promise` |
| `MotionSnapshot` | type | `{ acceleration, accelerationIncludingGravity, rotationRate: ... \| null; interval: number; timeStamp: number }` |
| `Vector3` | type | `{ x, y, z: number \| null }` |
| `RotationRateSnapshot` | type | `{ alpha, beta, gamma: number \| null }` |
| `MotionStatus` | type | `"unsupported" \| "idle" \| "active"` |
| `PermissionValue` | type | `"granted" \| "denied" \| "prompt" \| "unsupported"` |
## Cross-framework
The `devicemotion` subscription starts on the first subscriber across all stores and stops when the last one leaves. Read primitive per framework: `useValue` (React/Vue), `createValue` (Solid), `injectValue` (Angular), `watch` (Svelte), or `store.get` / `store.sub`.
---
Source: https://valdres.dev/react/plugins/browser-device-orientation.md
# browser-device-orientation
Wraps `DeviceOrientationEvent` as global atoms, exposing the raw tilt snapshot plus `alpha` / `beta` / `gamma` and a compass-heading selector.
> **Permission**
>
>
> iOS requires a user gesture: call `requestOrientationPermission()` from a click handler before subscribing. Other browsers grant on subscribe.
## Install
```bash
bun add @valdres/browser-device-orientation
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-device-orientation](https://valdres.dev/react/plugins/browser-device-orientation)
## Usage
```tsx
import { useValue } from "valdres-react"
import {
compassHeadingSelector,
requestOrientationPermission,
} from "@valdres/browser-device-orientation"
function Compass() {
const heading = useValue(compassHeadingSelector)
return (
<>
{heading == null ? "—" : `${Math.round(heading)}°`}
)
}
```
## Exports
| Export | Kind | Type |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `orientationAtom` | atom (read-only) | `OrientationSnapshot \| null` |
| `permissionAtom` | atom (settable) | `PermissionValue` |
| `orientationStatusAtom` | atom (read-only) | `OrientationStatus` |
| `alphaSelector` | selector | `number \| null` |
| `betaSelector` | selector | `number \| null` |
| `gammaSelector` | selector | `number \| null` |
| `absoluteSelector` | selector | `boolean \| null` |
| `compassHeadingSelector` | selector | `number \| null` |
| `requestOrientationPermission` | util fn | `() => Promise` |
| `OrientationSnapshot` | type | `{ alpha, beta, gamma: number \| null; absolute: boolean; webkitCompassHeading, webkitCompassAccuracy: number \| null; timeStamp: number }` |
| `OrientationStatus` | type | `"unsupported" \| "idle" \| "active"` |
| `PermissionValue` | type | `"granted" \| "denied" \| "prompt" \| "unsupported"` |
## Cross-framework
Global atoms/selectors — works in every framework, only the read primitive differs. The `deviceorientation` listener starts on the first subscriber and stops on the last.
---
Source: https://valdres.dev/react/plugins/browser-focus.md
# browser-focus
Wraps [`document.hasFocus()`](https://developer.mozilla.org/docs/Web/API/Document/hasFocus) plus the window `focus` / `blur` events as one global atom.
## Install
```bash
bun add @valdres/browser-focus
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-focus](https://valdres.dev/react/plugins/browser-focus)
## Usage
```tsx
import { useValue } from "valdres-react"
import { focusAtom } from "@valdres/browser-focus"
function FocusBadge() {
const focused = useValue(focusAtom)
return {focused ? "Focused" : "Blurred"}
}
```
## Exports
| Export | Kind | Type |
| ----------- | ---------------- | --------- |
| `focusAtom` | atom (read-only) | `boolean` |
## Cross-framework
A global atom — works in every framework; only the read primitive's name changes (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` in plain JS). The `focus` / `blur` listeners attach on the first subscriber and detach when the last leaves. Returns `true` during SSR. Compose with `@valdres/browser-visibility` for a "user is present" signal (see `@valdres/browser-presence`).
---
Source: https://valdres.dev/react/plugins/browser-geolocation.md
# browser-geolocation
Wraps the [Geolocation API](https://developer.mozilla.org/docs/Web/API/Geolocation_API) as reactive state: the current position, derived coordinate selectors, the permission state, and a status machine. The watch starts on the first subscriber and stops on the last.
> **Permission & HTTPS**
>
>
> Geolocation requires a secure context (HTTPS or localhost) and a user grant. Subscribing to `positionAtom` (or a coordinate selector) triggers the browser's permission prompt.
## Install
```bash
bun add @valdres/browser-geolocation
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-geolocation](https://valdres.dev/react/plugins/browser-geolocation)
## Usage
```tsx
import { useValue } from "valdres-react"
import { coordsSelector, geolocationStatusAtom } from "@valdres/browser-geolocation"
function Where() {
const coords = useValue(coordsSelector)
const status = useValue(geolocationStatusAtom)
if (!coords) return {status}
return {coords.latitude.toFixed(3)}, {coords.longitude.toFixed(3)}
}
```
## Exports
| Export | Kind | Type |
| -------------------------------------------------------- | ---------------- | ------------------------------------------------------------- |
| `positionAtom` | atom (read-only) | `GeolocationSnapshot \| null` |
| `coordsSelector` | selector | `{ latitude, longitude } \| null` |
| `accuracySelector` | selector | `number \| null` |
| `altitudeSelector` / `speedSelector` / `headingSelector` | selector | `number \| null` |
| `permissionAtom` | atom (read-only) | `"granted" \| "denied" \| "prompt" \| "unsupported"` |
| `geolocationStatusAtom` | atom (read-only) | `"idle" \| "pending" \| "active" \| "error" \| "unsupported"` |
| `geolocationErrorAtom` | atom (read-only) | `GeolocationError \| null` |
| `geolocationOptionsAtom` | atom (settable) | `PositionOptions` |
## Cross-framework
All state is global atoms/selectors, so it works in every framework — only the read primitive differs. Write `geolocationOptionsAtom` (via your framework's set hook, or `store.set`) to change accuracy/timeout options; the watch re-subscribes automatically.
---
Source: https://valdres.dev/react/plugins/browser-keyboard.md
# browser-keyboard
Tracks which keys are currently held down, from the document's `keydown` / `keyup` events. Exposes the raw pressed keys plus selectors for codes, modifiers, and per-key checks.
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-keyboard](https://valdres.dev/react/plugins/browser-keyboard)
Press and hold keys — the on-screen keyboard reflects `pressedCodesSelector` live.
## Install
```bash
bun add @valdres/browser-keyboard
```
## Usage
```tsx
import { useValue } from "valdres-react"
import { pressedCodesSelector, isCodePressedSelector } from "@valdres/browser-keyboard"
function Keys() {
const codes = useValue(pressedCodesSelector) // KeyboardCode[]
const shift = useValue(isCodePressedSelector("ShiftLeft"))
return {codes.join(" + ")}
}
```
## Exports
| Export | Kind | Type |
| ----------------------------- | ---------------------- | ---------------- |
| `pressedKeysAtom` | atom (read-only) | `PressedKey[]` |
| `pressedCodesSelector` | selector | `KeyboardCode[]` |
| `pressedKeyValuesSelector` | selector | `string[]` |
| `modifierSelector` | selector | `Modifier[]` |
| `isCodePressedSelector(code)` | selector family | `boolean` |
| `isKeyPressedSelector(key)` | selector family | `boolean` |
| `toggleKeyAtom(key)` | atom family (settable) | `boolean` |
## Cross-framework
Global atoms and selectors — works in every framework. For higher-level "press this combination → run this callback" hotkeys (rather than raw key state), use `@valdres/hotkeys`.
---
Source: https://valdres.dev/react/plugins/browser-online.md
# browser-online
Reactive online/offline status. Wraps `navigator.onLine` and the `online` / `offline` events as a single global atom that any framework can read.
## Install
```bash
bun add @valdres/browser-online
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-online](https://valdres.dev/react/plugins/browser-online)
## Usage
```tsx
import { useValue } from "valdres-react"
import { onlineAtom } from "@valdres/browser-online"
function ConnectionBadge() {
const online = useValue(onlineAtom)
return {online ? "Online" : "Offline"}
}
```
The hook reads from the store provided by your app (see [Provider](https://valdres.dev/react/Provider)); the atom's value is kept in sync across every store automatically.
## Exports
| Export | Kind | Type |
| ------------ | ---------------- | --------- |
| `onlineAtom` | atom (read-only) | `boolean` |
## Cross-framework
`onlineAtom` is a global atom, so it works identically in every framework — only the read primitive's name changes (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` / `store.sub` in plain JavaScript). The browser subscription starts on the first subscriber across all stores and stops when the last one leaves.
---
Source: https://valdres.dev/react/plugins/browser-presence.md
# browser-presence
Read-only boolean for "is the user actually here": `true` when the tab is visible **and** the window is focused. Composes [`browser-visibility`](https://valdres.dev/plugins/browser-visibility) and [`browser-focus`](https://valdres.dev/plugins/browser-focus).
## Install
```bash
bun add @valdres/browser-presence
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-presence](https://valdres.dev/react/plugins/browser-presence)
## Usage
```tsx
import { useValue } from "valdres-react"
import { presenceSelector } from "@valdres/browser-presence"
function PresenceDot() {
const present = useValue(presenceSelector)
return {present ? "Active" : "Away"}
}
```
## Exports
| Export | Kind | Type |
| ------------------ | -------------------- | --------- |
| `presenceSelector` | selector (read-only) | `boolean` |
## Cross-framework
`presenceSelector` is a global selector — read it with `store.get` / `store.sub` in plain JS. It recomputes whenever the visibility or focus subscription fires.
---
Source: https://valdres.dev/react/plugins/browser-reduced-data.md
# browser-reduced-data
Wraps the `(prefers-reduced-data: reduce)` media query as a global atom, with a boolean selector.
## Install
```bash
bun add @valdres/browser-reduced-data
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-reduced-data](https://valdres.dev/react/plugins/browser-reduced-data)
## Usage
```tsx
import { useValue } from "valdres-react"
import { prefersReducedDataSelector } from "@valdres/browser-reduced-data"
function Hero() {
const reduced = useValue(prefersReducedDataSelector)
return reduced ? :
}
```
## Exports
| Export | Kind | Type |
| ---------------------------- | ---------------- | --------------------------------------------- |
| `reducedDataAtom` | atom (read-only) | `ReducedData` (`"no-preference" \| "reduce"`) |
| `prefersReducedDataSelector` | selector | `boolean` |
| `ReducedData` | type | `"no-preference" \| "reduce"` |
## Cross-framework
`reducedDataAtom` is a global atom; only the read primitive changes per framework (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` / `store.sub`). The browser subscription starts on the first subscriber and stops when the last leaves.
---
Source: https://valdres.dev/react/plugins/browser-reduced-motion.md
# browser-reduced-motion
Reactive `(prefers-reduced-motion: reduce)` as a global atom plus a boolean selector.
## Install
```bash
bun add @valdres/browser-reduced-motion
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-reduced-motion](https://valdres.dev/react/plugins/browser-reduced-motion)
## Usage
```tsx
import { useValue } from "valdres-react"
import { prefersReducedMotionSelector } from "@valdres/browser-reduced-motion"
function Banner() {
const reduced = useValue(prefersReducedMotionSelector)
return
}
```
## Exports
| Export | Kind | Type |
| ------------------------------ | ---------------- | ----------------------------------------------- |
| `reducedMotionAtom` | atom (read-only) | `ReducedMotion` (`"no-preference" \| "reduce"`) |
| `prefersReducedMotionSelector` | selector | `boolean` |
| `ReducedMotion` | type | `"no-preference" \| "reduce"` |
## Cross-framework
The atom is global: read it with each adapter's primitive (`useValue`, `createValue`, `injectValue`, `watch`) or `store.get` / `store.sub` in plain JS. The media-query subscription starts on the first subscriber and stops when the last one leaves.
---
Source: https://valdres.dev/react/plugins/browser-reduced-transparency.md
# browser-reduced-transparency
Read-only global atom + boolean selector for the `(prefers-reduced-transparency: reduce)` media query.
## Install
```bash
bun add @valdres/browser-reduced-transparency
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-reduced-transparency](https://valdres.dev/react/plugins/browser-reduced-transparency)
Toggle "Reduce transparency" in your OS accessibility settings.
## Usage
```tsx
import { useValue } from "valdres-react"
import { prefersReducedTransparencySelector } from "@valdres/browser-reduced-transparency"
function Panel() {
const reduce = useValue(prefersReducedTransparencySelector)
return
}
```
## Exports
| Export | Kind | Type |
| ------------------------------------ | ---------------- | ----------------------------- |
| `reducedTransparencyAtom` | atom (read-only) | `"no-preference" \| "reduce"` |
| `prefersReducedTransparencySelector` | selector | `boolean` |
| `ReducedTransparency` | type | `"no-preference" \| "reduce"` |
## Cross-framework
Global state — only the read primitive's name changes per framework (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` / `store.sub` in plain JS). The media-query subscription starts on the first subscriber across all stores and stops when the last leaves.
---
Source: https://valdres.dev/react/plugins/browser-screen.md
# browser-screen
Wraps `window.screen` as one global atom, synced on `resize`, `orientationchange`, and DPR changes.
## Install
```bash
bun add @valdres/browser-screen
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-screen](https://valdres.dev/react/plugins/browser-screen)
## Usage
```tsx
import { useValue } from "valdres-react"
import { screenAtom } from "@valdres/browser-screen"
function Resolution() {
const s = useValue(screenAtom)
return {s.width} × {s.height}
}
```
## Exports
| Export | Kind | Type |
| ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `screenAtom` | atom (read-only) | `ScreenInfo` |
| `ScreenInfo` | type | `{ width, height, availWidth, availHeight, colorDepth, pixelDepth, devicePixelRatio, orientationType, orientationAngle }` |
All fields are `number` except `orientationType: OrientationType`. Outside the browser the atom returns a fallback (zeros for dimensions; `colorDepth`/`pixelDepth` 24, `devicePixelRatio` 1, `orientationType: "landscape-primary"`).
The browser subscription starts on the first subscriber across all stores and stops when the last one leaves.
---
Source: https://valdres.dev/react/plugins/browser-screen-details.md
# browser-screen-details
Wraps the [Window Management API](https://developer.mozilla.org/en-US/docs/Web/API/Window_Management_API) (`window.getScreenDetails()`) as global atoms exposing the current screen, all connected screens, and the permission state.
> **Permission required**
>
>
> Screen details are empty until you call `requestScreenDetails()`, which prompts for the `window-management` permission. Requires a secure context.
## Install
```bash
bun add @valdres/browser-screen-details
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-screen-details](https://valdres.dev/react/plugins/browser-screen-details)
## Usage
```tsx
import { useValue } from "valdres-react"
import {
currentScreenAtom,
screensAtom,
screenPermissionAtom,
requestScreenDetails,
} from "@valdres/browser-screen-details"
function Screens() {
const permission = useValue(screenPermissionAtom)
const current = useValue(currentScreenAtom)
const screens = useValue(screensAtom)
if (permission !== "granted")
return
return (
)
}
```
## Exports
| Export | Kind | Type |
| ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentScreenAtom` | atom (read-only) | `ScreenDetail \| null` |
| `screensAtom` | atom (read-only) | `ScreenDetail[]` |
| `screenPermissionAtom` | atom (read-only) | `ScreenPermissionState` |
| `requestScreenDetails` | util fn | `() => Promise` |
| `ScreenDetail` | type | `{ label, left, top, width, height, availLeft, availTop, availWidth, availHeight, colorDepth, pixelDepth, devicePixelRatio, orientationType, orientationAngle, isPrimary, isInternal }` |
| `ScreenPermissionState` | type | `"prompt" \| "granted" \| "denied" \| "unsupported"` |
## Cross-framework
All state is global atoms, so it works in every framework — only the read primitive differs. The atoms stay empty until `requestScreenDetails()` resolves; call it once from anywhere.
---
Source: https://valdres.dev/react/plugins/browser-visibility.md
# browser-visibility
Tracks the [Page Visibility API](https://developer.mozilla.org/docs/Web/API/Page_Visibility_API) — whether the tab is currently visible — via the `visibilitychange` event.
## Install
```bash
bun add @valdres/browser-visibility
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-visibility](https://valdres.dev/react/plugins/browser-visibility)
## Usage
```tsx
import { useValue } from "valdres-react"
import { visibilityAtom, isVisibleSelector } from "@valdres/browser-visibility"
function PausableVideo() {
const visible = useValue(isVisibleSelector)
// pause work when the tab is hidden
return
}
```
## Exports
| Export | Kind | Type |
| ------------------- | ---------------- | ----------------------- |
| `visibilityAtom` | atom (read-only) | `"visible" \| "hidden"` |
| `isVisibleSelector` | selector | `boolean` |
## Cross-framework
A global atom plus a boolean selector — works in every framework. Compose it with `@valdres/browser-focus` for a "user is present" signal (see `@valdres/browser-presence`).
---
Source: https://valdres.dev/react/plugins/browser-window.md
# browser-window
Tracks the browser window's inner size, updating on every `resize`. Exposed as a single global atom.
## Install
```bash
bun add @valdres/browser-window
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/browser-window](https://valdres.dev/react/plugins/browser-window)
## Usage
```tsx
import { useValue } from "valdres-react"
import { windowSizeAtom } from "@valdres/browser-window"
function Size() {
const { innerWidth, innerHeight } = useValue(windowSizeAtom)
return {innerWidth} × {innerHeight}
}
```
## Exports
| Export | Kind | Type |
| ---------------- | ---------------- | ------------------------------------------------------ |
| `windowSizeAtom` | atom (read-only) | `{ innerWidth, innerHeight, outerWidth, outerHeight }` |
## Cross-framework
A global atom — works in every framework, with the resize listener attached only while something is subscribed.
---
Source: https://valdres.dev/react/plugins/color-mode.md
# color-mode
Resolves the active color mode from the OS preference (`prefers-color-scheme`) and a user override. `userSelectedColorModeAtom` is settable (`"light" | "dark" | "system"`); `colorModeSelector` returns the resolved `"light" | "dark"`.
## Install
```bash
bun add @valdres/color-mode
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/color-mode](https://valdres.dev/react/plugins/color-mode)
## Usage
```tsx
import { useValue, useSetAtom } from "valdres-react"
import { colorModeSelector, userSelectedColorModeAtom } from "@valdres/color-mode"
function ThemeToggle() {
const mode = useValue(colorModeSelector) // "light" | "dark"
const setMode = useSetAtom(userSelectedColorModeAtom)
return (
)
}
```
Or use the convenience hooks from [`@valdres-react/color-mode`](https://www.npmjs.com/package/@valdres-react/color-mode): `useColorMode()`, `useIsDarkMode()`, `useIsLightMode()`.
## Exports
| Export | Kind | Type |
| --------------------------- | ---------------- | ------------------------------- |
| `colorModeSelector` | selector | `"light" \| "dark"` |
| `isDarkModeSelector` | selector | `boolean` |
| `isLightModeSelector` | selector | `boolean` |
| `systemColorModeAtom` | atom (read-only) | `"light" \| "dark"` |
| `userSelectedColorModeAtom` | atom (settable) | `"light" \| "dark" \| "system"` |
| `getSystemColorMode` | util fn | `() => "light" \| "dark"` |
| `ColorMode` | type | `"light" \| "dark"` |
| `UserSelectedColorMode` | type | `"light" \| "dark" \| "system"` |
## Cross-framework
Global atoms and selectors — only the read primitive's name changes per framework. The `prefers-color-scheme` listener starts on the first subscriber and stops when the last one leaves.
---
Source: https://valdres.dev/react/plugins/hotkeys.md
# hotkeys
Keyboard shortcuts from `keydown` / `keyup`. `subscribeToHotkey`/`Key`/`Code`/`Command` fire a callback on match; the live key/code combination is exposed as global atoms.
## Install
```bash
bun add @valdres/hotkeys
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/hotkeys](https://valdres.dev/react/plugins/hotkeys)
## Usage
React has a `useHotkeys` hook family. Every other framework calls `subscribeToHotkey(...)` inside its own effect primitive and returns the unsubscribe.
```tsx
import { useHotkeys } from "@valdres-react/hotkeys"
function Editor() {
useHotkeys("meta+s", () => save(), { preventDefault: true })
// also: useHotkeysKey, useHotkeysCode, useHotkeysCommand("Save", ...)
return
}
```
## Exports
| Export | Kind | Type |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |
| `currentCodeCombinationAtom` | atom (read-only) | `KeyboardCode[]` — `event.code`s currently held |
| `currentKeyCombinationAtom` | atom (read-only) | `string[]` — lowercased `event.key`s currently held |
| `eventByCodeAtom` | atomFamily | `(code: KeyboardCode[]) => Atom` |
| `eventByKeyAtom` | atomFamily | `(key: string[]) => Atom` |
| `subscribeToHotkey` | util fn | `(hotkey: string, cb: (e: KeyboardEvent) => void, options: Options, store: Store) => () => void` |
| `subscribeToKey` | util fn | `(key: string \| string[], cb, options, store) => () => void` |
| `subscribeToCode` | util fn | `(code: KeyboardCode \| KeyboardCode[], cb, options, store) => () => void` |
| `subscribeToCommand` | util fn | `(command: KeyboardCommand, cb, options, store) => () => void` |
| `registerListeners` | util fn | `() => void` — attaches the document key listeners |
| `eventHandler` | util fn | `(event: KeyboardEvent) => void` |
| `DEFAULT_OPTIONS` | const | frozen `Options` |
| `Options` | type | `{ keyup, keydown, enabled, enableOnFormTags, enableOnContentEditable, preventDefault, repeat }` |
| `KeyboardCode` | type | re-exported from `@valdres/browser-keyboard` |
| `KeyboardCommand` | type | `"Save" \| "Undo" \| "Redo" \| "Cut" \| "Copy" \| "ZoomIn" \| "ZoomOut" \| "ZoomReset"` |
`enabled` accepts a `boolean`, `() => boolean`, `Atom`, or `Selector`. `subscribeToCommand` maps a command to the OS-specific chord (e.g. `Save` → `meta+s` on Apple, `ctrl+s` elsewhere).
## Cross-framework
The combination atoms are global — read them with the framework's primitive (`useValue` / `createValue` / `injectValue` / `watch`, or `store.get` / `store.sub`). The `subscribeToX` callbacks take `store` explicitly, so they work anywhere.
---
Source: https://valdres.dev/react/plugins/public-ip.md
# public-ip
Fetches your public IP from a list of HTTP endpoints and exposes it as global atoms, with stale-while-revalidate caching. `publicIpAtom` resolves to the IP (`Promise` on first read, then `string`).
> **Async atom**
>
>
> `publicIpAtom` suspends on first read. Wrap consumers in ``, or read the non-suspending `publicIpValueAtom` / `publicIpStatusAtom` instead.
## Install
```bash
bun add @valdres/public-ip
```
## Live example
▶ Live example: [https://valdres.dev/react/plugins/public-ip](https://valdres.dev/react/plugins/public-ip)
## Usage
```tsx
import { Suspense } from "react"
import { useValue } from "valdres-react"
import { publicIpAtom } from "@valdres/public-ip"
function Ip() {
const ip = useValue(publicIpAtom) // string (suspends until resolved)
return {ip}
}
function App() {
return (
)
}
```
## Exports
| Export | Kind | Type |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| `publicIpAtom` | atom (read-only) | `Promise \| string` |
| `publicIpStatusAtom` | atom (read-only) | `PublicIpStatus` |
| `publicIpErrorAtom` | atom (read-only) | `Error \| null` |
| `publicIpValueAtom` | atom (read-only) | `string \| null` |
| `publicIpV4Atom` | atom (read-only) | `Promise \| string` |
| `publicIpV4StatusAtom` | atom (read-only) | `PublicIpStatus` |
| `publicIpV4ErrorAtom` | atom (read-only) | `Error \| null` |
| `publicIpV4ValueAtom` | atom (read-only) | `string \| null` |
| `publicIpV6Atom` | atom (read-only) | `Promise \| string` |
| `publicIpV6StatusAtom` | atom (read-only) | `PublicIpStatus` |
| `publicIpV6ErrorAtom` | atom (read-only) | `Error \| null` |
| `publicIpV6ValueAtom` | atom (read-only) | `string \| null` |
| `publicIpEndpointsAtom` | atom (settable) | `string[]` |
| `publicIpV4EndpointsAtom` | atom (settable) | `string[]` |
| `publicIpV6EndpointsAtom` | atom (settable) | `string[]` |
| `publicIpMaxAgeAtom` | atom (settable) | `number` (ms) |
| `publicIpStaleWhileRevalidateAtom` | atom (settable) | `number` (ms) |
| `publicIpStaleIfErrorAtom` | atom (settable) | `number` (ms) |
| `fetchPublicIp` | util fn | `(endpoints: string[], validate?: (v: string) => boolean, timeoutMs?: number) => Promise` |
| `PublicIpStatus` | type | `"idle" \| "loading" \| "revalidating" \| "ok" \| "error"` |
The `V4` / `V6` atoms are the same shape, fetching from IPv4- and IPv6-only endpoints. Endpoint, `maxAge`, `staleWhileRevalidate`, and `staleIfError` atoms are settable to tune fetching.
## Cross-framework
Atoms are global: the fetch starts on the first subscriber and the result is shared across every store. Only the read primitive changes per framework (`useValue`, `createValue`, `injectValue`, `watch`, or `store.get` / `store.sub` in plain JS).
---
Source: https://valdres.dev/react/plugins/redux-devtools.md
# redux-devtools
Every committed change to a named atom is sent as an action; the extension's time-travel / commit / reset controls restore state back onto the store.
> **Requires the extension**
>
>
> Install the [Redux DevTools](https://github.com/reduxjs/redux-devtools) browser extension. Without it, `connectReduxDevtools` warns once and returns a no-op handle.
## Install
```bash
bun add @valdres/redux-devtools
```
## Usage
Call `connectReduxDevtools(store)` once on mount; call `disconnect()` on teardown.
```tsx
import { useEffect } from "react"
import { useStore } from "valdres-react"
import { connectReduxDevtools } from "@valdres/redux-devtools"
function DevtoolsBridge() {
const store = useStore()
useEffect(() => connectReduxDevtools(store).disconnect, [store])
return null
}
```
Vanilla: pass the store instance directly.
```ts
import { store } from "valdres"
import { connectReduxDevtools } from "@valdres/redux-devtools"
const handle = connectReduxDevtools(store())
// handle.disconnect() to detach
```
## Options
`connectReduxDevtools(store, options?)` accepts:
| Option | Type | Default | Notes |
| ----------- | ------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | `"valdres"` | Instance name in the extension dropdown. |
| `serialize` | `(state, value) => unknown` | identity | Shape values that aren't structured-cloneable before they're sent. |
| `scopes` | `boolean` | `true` | Include scope state under `@scopes` and react to scope writes. |
| `unnamed` | `"track" \| "ignore"` | `"track"` | `track` labels unnamed atoms `unnamed_atom_N`; `ignore` omits them. |
| `exclude` | `ExcludeRule \| ExcludeRule[]` | — | Leave atoms/selectors out entirely — neither seeded nor reported. A rule is an atom/selector reference, an `atomFamily`/`selectorFamily` (all its members), a `name` string, or a predicate `(state) => boolean`. |
| `selectors` | `boolean` | `false` | Also report named selectors under `@computed` (display-only, never restored). |
### Excluding high-frequency atoms
A single atom that updates on every frame — a cursor position, pointer
coordinates, a scroll offset — floods the timeline and buries the actions you
actually care about. Pass it to `exclude` and it disappears from DevTools while
your store keeps working normally:
```ts
connectReduxDevtools(store, {
// any of: a reference, a name, an atomFamily/selectorFamily, a predicate, or a mix
exclude: [cursorPositionAtom, "pointerAtom", pointerFamily],
})
```
## Exports
| Export | Kind | Type |
| ------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `connectReduxDevtools` | util fn | `(store: Store, options?: ConnectReduxDevtoolsOptions) => ReduxDevtoolsHandle` |
| `ConnectReduxDevtoolsOptions` | type | `{ name?, serialize?, scopes?, unnamed?, exclude?, selectors? }` |
| `ExcludeOption` / `ExcludeRule` | type | atom/selector/family reference, `name` string, or `(state) => boolean` |
| `ReduxDevtoolsHandle` | type | `{ disconnect(): void }` |
| `DevtoolsSnapshot` | type | `Record & { "@scopes"?, "@computed"? }` |
| `ReduxDevtoolsConnection` | type | extension connection surface |
| `ReduxDevtoolsExtension` | type | `window.__REDUX_DEVTOOLS_EXTENSION__` surface |
| `ReduxDevtoolsMessage` | type | message from the extension |
## Notes
- A named transaction (`store.txn(fn, name)`) arrives as a single action.
- Default (non-enumerable) stores seed lazily as state first changes; only `store(id, { enumerable: true })` is seeded up front.
- Only how you obtain the `Store` differs per framework (`useStore`, `injectStore`, `getValdresContext`, or the bare instance).
---
Source: https://valdres.dev/react/Provider.md
# ProviderSignature``valdres-react
Provide a store to a React subtreeWraps a React subtree with a valdres store. Optional — without a Provider, all hooks use a default global store.## Usage```tsx
import { Provider } from "valdres-react"
function App({ children }) {
return {children}
}
```## With a custom storeCreate a store with `store()` from `valdres` and pass it to the Provider:```tsx
import { store } from "valdres"
import { Provider } from "valdres-react"
const myStore = store()
function App({ children }) {
return {children}
}
```## Multiple storesYou can nest Providers to isolate state between different parts of your app:```tsx
function App() {
return (
)
}
```## When to use a ProviderA `` is required — `useAtom`, `useValue`, and the other hooks throw `No found` if there isn't one above them in the tree.* **Without a `store` prop**: `` creates a store for you (with `batchUpdates` enabled). Fine for most apps.
* **With a `store` prop**: you pass a store you created yourself, giving you control over its lifecycle and isolation — useful for testing, micro-frontends, SSR, or independent state trees.For state access outside React (scripts, tests, cross-framework code), use the `globalStore` exported from `valdres`.## See also* [store](https://valdres.dev/valdres/store) — create a store instance
* [useStore](https://valdres.dev/react/useStore) — access the current store
---
Source: https://valdres.dev/react/Scope.md
# Scope
Signature
``
valdres-react
Create an isolated child store for a React subtree
Creates a scoped store that inherits state from the parent but can override values independently. Components inside the scope read and write to the scoped store.
## Usage
```tsx
import { Provider, Scope } from "valdres-react"
function App() {
return (
)
}
```
## Props
| Prop | Type | Description |
| ------------ | ---------------------------------- | ----------------------------------------------------- |
| `scopeId` | `string` | Optional identifier. Auto-generated if omitted. |
| `initialize` | `(txn) => void \| [Atom, value][]` | Optional callback to set initial values in the scope. |
| `children` | `ReactNode` | Components that will use the scoped store. |
## Initializing state
```tsx
{
txn.set(nameAtom, "Draft")
txn.set(emailAtom, "")
}}
>
```
Or with the array format:
```tsx
[
[nameAtom, "Draft"],
[emailAtom, ""],
]}
>
```
## Cleanup
The scope is automatically cleaned up when the component unmounts.
## See also
- [Scoped Stores](https://valdres.dev/guides/scoped-stores) — full guide on scoped stores
- [Provider](https://valdres.dev/react/Provider) — provide a store to your component tree
---
Source: https://valdres.dev/react/selector.md
# selector
Signature
`selector(getter: (get: GetFn) => T): Selector`
valdres
Derive computed state that updates automatically
Creates derived state that automatically recomputes when its dependencies change. Selectors are read-only — they compute their value from atoms and other selectors.
## Usage
```ts
import { atom, selector } from "valdres"
const firstNameAtom = atom("John")
const lastNameAtom = atom("Doe")
const fullNameSelector = selector(get => {
const first = get(firstNameAtom)
const last = get(lastNameAtom)
return `${first} ${last}`
})
```
## Parameters
| Parameter | Type | Description |
| -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getter` | `(get: GetFn) => T` | A function that computes the derived value. Use `get()` to read atoms or other selectors. |
| `options.name` | `string` | Optional name for debugging, devtools, and validation error messages |
| `options.schema` | `Schema` | Schema for runtime validation of the selector's result, and type inference. A no-op unless validation is enabled. See [Schema Validation](https://valdres.dev/guides/schema-validation). |
| `options.schemaValidation` | `boolean` | Per-selector override of the store's `schemaValidation` flag — `true` always validates this selector, `false` exempts it |
| `options.mutable` | `boolean` | Opt out of development/test deep-freezing. Required when results contain mutable built-ins or host objects that cannot be frozen safely. |
Selectors follow the same [immutability and exotic-value
contract](https://valdres.dev/valdres/atom#immutability-and-exotic-values) as atoms. When a
selector returns a value from a mutable atom unchanged, mark the selector
`mutable: true` as well so its cache does not attempt to deep-freeze that value.
## Async selectors
Selectors can return a promise. They work with `Suspense` in React. Note that
the getter itself must be a sync function that _returns_ a promise — `selector()`
rejects `async` functions at creation time:
```ts
const userDataSelector = selector(get => {
const userId = get(userIdAtom)
return fetch(`/api/users/${userId}`).then(res => res.json())
})
```
## Schema validation
A selector's `schema` validates its computed result on every evaluation — a
runtime contract that catches a selector drifting from its declared shape:
```ts
const fullNameSelector = selector(
get => `${get(firstNameAtom)} ${get(lastNameAtom)}`,
{ name: "fullName", schema: z.string() },
)
```
Validation is opt-in per store (`store({ schemaValidation: true })`) or per
selector (`schemaValidation: true`). See the
[Schema Validation guide](https://valdres.dev/guides/schema-validation).
## Evaluation errors
Synchronous exceptions thrown while evaluating a selector are wrapped in
`SelectorEvaluationError`. The original exception remains available as
`error.cause`, and the message includes the named selector chain that led to
the failure. Give selectors a `name` to make that trace useful.
A dependency cycle throws `SelectorCircularDependencyError`, which extends
`SelectorEvaluationError`. Both classes are exported from `valdres`, so check
for the more specific circular error first when handling both:
```ts
import {
SelectorCircularDependencyError,
SelectorEvaluationError,
} from "valdres"
try {
appStore.get(profileSelector)
} catch (error) {
if (error instanceof SelectorCircularDependencyError) {
console.error("Selector dependency cycle", error.message)
} else if (error instanceof SelectorEvaluationError) {
console.error("Selector evaluation failed", error.cause)
} else {
throw error
}
}
```
## See also
- [selectorFamily](https://valdres.dev/valdres/selectorFamily) — create a collection of selectors keyed by a parameter
- [Schema Validation](https://valdres.dev/guides/schema-validation) — runtime validation and type inference
- [useValue](https://valdres.dev/react/useValue) — read a selector value in your components
---
Source: https://valdres.dev/react/selectorFamily.md
# selectorFamily
Signature
`selectorFamily(factory: (key: K) => (get: GetFn, options: SelectorGetOptions) => T): SelectorFamily`
valdres
Create a keyed collection of derived selectors
Creates a family of selectors keyed by a parameter. Each selector derives its value from atoms or other selectors based on the key.
The family object is a factory, not readable or subscribable state. Read or
subscribe to a member such as `userDisplayNameSelector("user-1")`. Unlike an
`atomFamily`, creating a selector-family member does not add store-local state
or membership to enumerate.
Selector options apply to every family member. In particular, use
`{ mutable: true }` when results contain mutable built-ins or host objects; see
the selector [immutability contract](https://valdres.dev/valdres/selector#parameters).
## Member identity and lifetime
A member's identity is stable while live: repeated calls with the same key
return the same selector while a caller or live store strongly retains it, such
as through a subscription, dependency edge, or an enumerable store's cold
cache. A default non-enumerable store uses weak keys for cold entries, so a cold
read there does not by itself keep a member alive. The family cache is weak;
after a member becomes unreachable, garbage collection may reclaim it and a
later call can create a fresh identity.
`release(...args)` explicitly evicts the cached lookup early. Existing callers
and stores may continue using the released selector, while a later family call
can create a new member for those arguments.
Each member getter also receives `SelectorGetOptions`. Its `signal` is aborted
when that evaluation is superseded or disposed, and `storeId` identifies the
store evaluating the member. Existing getters that only accept `get` remain
valid.
```ts
const userSelector = selectorFamily(
userId =>
(get, { signal, storeId }) =>
fetch(`/api/users/${userId}?store=${storeId}`, { signal }).then(
res => res.json(),
),
)
```
## Usage
```ts
import { selectorFamily } from "valdres"
import { userAtom } from "./userAtom"
const userDisplayNameSelector = selectorFamily(id => get => {
const { firstName, lastName } = get(userAtom(id))
return `${firstName} ${lastName}`
})
store.get(userDisplayNameSelector("user-1")) // "John Doe"
```
## Custom key identity
Selector families use the same deterministic key codec as `atomFamily`: types
and argument count are distinct, while plain Object keys and Map/Set contents
are canonicalized independent of insertion order. Unsupported values (including
Symbols, functions, Promises, class instances, and cycles) throw a `TypeError`.
Provide `keyOf` when the original argument is unsupported or when only part of
it should determine selector identity:
```ts
const userRevision = selectorFamily(
user => get => `${get(userAtom(user.id)).name}@${user.revision}`,
{ keyOf: user => [user.id, user.revision] },
)
```
`keyOf` is also the lever for read-heavy code. A single string or number
argument is looked up directly, but an object argument has to be canonicalized
on **every** call — `family({ id })` in a loop re-encodes that object each time,
while `family(id)` does not. If a family with structured arguments sits on a hot
path, give it a `keyOf` that projects the identifying part:
```ts
// re-encodes { id, revision } on every call
const slow = selectorFamily(user => get => get(userAtom(user.id)).name)
// encodes one string instead
const fast = selectorFamily(user => get => get(userAtom(user.id)).name, {
keyOf: user => user.id,
})
```
## With async computation
```ts
const userPostsSelector = selectorFamily(userId => get =>
fetch(`/api/users/${userId}/posts`).then(res => res.json()),
)
```
As with `selector()`, the member getter itself must be synchronous. It may
return a Promise, but a native `async` function is rejected because Valdres
unwraps settled selector values and therefore cannot preserve an async
function's always-Promise return contract.
## In React
```tsx
import { useValue } from "valdres-react"
function UserName({ userId }) {
const displayName = useValue(userDisplayNameSelector(userId))
return {displayName}
}
```
## See also
- [selector](https://valdres.dev/valdres/selector) — create a single selector
- [atomFamily](https://valdres.dev/valdres/atomFamily) — create a family of atoms
- [index](https://valdres.dev/valdres/index) — reactively filter an atom family by a term
---
Source: https://valdres.dev/react/store.md
# storeSignature`store(id?: string, options?: StoreOptions): Store`valdresCreate a store to hold all stateCreates a store instance that holds all atom and selector state and manages
subscriptions. The store is the central hub for reading, writing, and
subscribing to state.## Usage```ts
import { atom, store } from "valdres"
const myStore = store()
const countAtom = atom(0)
```Every store exposes a stable, read-only `id`. Pass one explicitly when an
adapter or application needs to address the store later; generated IDs are
unique within the loaded Valdres instance.```ts
const checkoutStore = store("checkout")
checkoutStore.id // "checkout"
```The Store facade exposes operations and identity, not its mutable graph/cache
runtime. Framework and tooling integrations use Valdres' versioned adapter
entrypoint instead of reaching through the public Store object.## OptionsThe options bag is exported as `StoreOptions`, so a wrapper can accept and
forward it without re-declaring the shape. It also carries `id`, which the
`store(options)` form reads instead of a positional first argument.| Option | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batchUpdates` | `boolean` | Batch sequential `set()` calls within a tick into one notification pass (recommended for React) |
| `enumerable` | `boolean` | Retain values enumerably so `store.snapshot()` can list current state |
| `schemaValidation` | `boolean` | Validate atom/selector values against their `schema` (off by default). Inherited by scoped stores. See [Schema Validation](https://valdres.dev/guides/schema-validation). |With `batchUpdates`, a store and its scopes share pending writes for the tick.
Synchronous descendant reads see pending ancestor values while scope-local
shadows remain isolated from ancestors; subscriber notifications stay deferred
until the batch commits.```ts
// Enable schema validation (e.g. outside production)
const devStore = store({ schemaValidation: import.meta.env.DEV })
```## Reading state```ts
myStore.get(countAtom) // 0
```## Writing state```ts
// Set directly
myStore.set(countAtom, 42)
// Update based on previous value
myStore.set(countAtom, prev => prev + 1)
```Synchronous values and updater functions return the written value. Promise or
promise-returning-updater inputs return the normalized `Promise`, which settles
when the async write does:```ts
const count = myStore.set(countAtom, 42) // number
const pendingCount = myStore.set(countAtom, Promise.resolve(43)) // Promise
await pendingCount
```## Subscribing to changesSubscription callbacks are notifications. Read the current value from the store
when the callback runs:```ts
const unsub = myStore.sub(countAtom, () => {
console.log("count changed:", myStore.get(countAtom))
})
// Later: stop listening
unsub()
```## TransactionsBatch multiple updates so subscribers only fire once:```ts
myStore.txn(({ set }) => {
set(atomA, 1)
set(atomB, 2)
// Subscribers fire once after the transaction completes
})
```Valdres owns commit and rollback: a successful callback commits once, while a
callback that throws discards every staged write. Callback transactions
intentionally expose no manual `commit()` or backing store `data`.The transaction hands back whatever the callback returned, so a value read
against its view can come straight out:```ts
const total = myStore.txn(txn => {
txn.set(priceAtom, 100)
return txn.get(priceAtom) * quantity
})
```Promise and thenable callbacks are rejected at runtime — a transaction commits
synchronously, so it cannot await anything.> **Warning**
>
>
> Selectors that depend on atoms updated in a transaction will only recompute
> once, after all updates are applied. This is the intended behavior for
> performance.## Disposing request storesGlobal atoms remember each store that has materialized them so writes can fan
out synchronously. Dispose short-lived stores—such as one store per SSR request
or background job—when their work finishes:```ts
const requestStore = store()
try {
return await renderRequest(requestStore)
} finally {
requestStore.dispose()
}
````dispose()` is terminal. It drains the store and all descendant scopes of active
subscriptions, atom mounts and their timers, `onChange` / `onCommitEnd`
listeners, pending batched writes, async selector work, and registrations on the
global atoms they touched. Cleanup stays proportional to lifecycle resources the
store actually created.Detached scopes are disposed automatically when their last consumer calls
`detach()`. Every later operation on a disposed store throws
`StoreDisposedError`; calling `dispose()` again is a no-op. Create a new store
for later work.### Releasing your own resourcesValdres cleans up what it owns. For anything you keep alongside a store — a
cache, a connection, a timer — register it with `onDispose`, which runs when the
store is disposed, when an ancestor is disposed, or, for a scope, when its last
`detach()` lands:```ts
const requestStore = store()
const connection = openConnection()
requestStore.onDispose(() => connection.close())
```It returns a function that cancels the registration. Each call registers
independently, so the same function passed twice runs twice and each canceller
removes only its own. The store is already terminal inside the callback — every
operation on it throws — so read what you need beforehand and close over it.
Every callback runs even if an earlier one throws, and the first error reaches
whoever called `dispose()`.Per-atom setup belongs in an atom's `onMount` instead, whose cleanup tracks
subscribers rather than the store's lifetime.## Scopes`scope(scopeId)` opens a child store that inherits everything from this one and
keeps its own writes local — see the
[scoped stores guide](https://valdres.dev/guides/scoped-stores). `hasScope` answers whether one
exists right now, which is otherwise only observable by catching what the
callback form throws:```ts
const draft = myStore.scope("draft")
myStore.hasScope("draft") // true
draft.detach()
myStore.hasScope("draft") // false — that was the last lease
```It reports this store's own children, not a search of the tree; depth composes
through `scope()` rather than a path argument:```ts
myStore.scope("a", s => s.hasScope("b"))
```## The global store`valdres` exports a shared `globalStore` — the store that global atoms
synchronize through. Import it when you need store access outside of a component
(scripts, tests, workers, cross-framework code):```ts
import { globalStore } from "valdres"
globalStore.get(myAtom)
globalStore.set(myAtom, 1)
```> **Do not dispose the global store**
>
>
> `globalStore` is a process-wide singleton that global atoms use for
> synchronization. Calling `globalStore.dispose()` throws. Only dispose stores
> that your application creates with `store()`.Inside a component you normally read and write through your framework's
provider/context instead — see [Provider](https://valdres.dev/react/Provider).## See also* [Provider](https://valdres.dev/react/Provider) — provide a store to your component tree
* [useStore](https://valdres.dev/react/useStore) — access the current store in your components
* [Schema Validation](https://valdres.dev/guides/schema-validation) — opt-in runtime validation via
the `schemaValidation` option
---
Source: https://valdres.dev/react/useAtom.md
# useAtom
Signature
`useAtom(atom: Atom): [T, SetterFn]`
valdres-react
Subscribe to and update an atom's value
A React hook similar to `useState()` that returns the current value and a setter function for an atom. The component re-renders when the atom's value changes.
## Usage
```tsx
import { atom } from "valdres"
import { useAtom } from "valdres-react"
const countAtom = atom(0)
const Counter = () => {
const [count, setCount] = useAtom(countAtom)
return (
{count}
)
}
```
## Try it
▶ Try it live: [https://valdres.dev/react/useAtom](https://valdres.dev/react/useAtom)
## Returns
| Index | Type | Description |
| ----- | ------------- | ----------------------------------- |
| `[0]` | `T` | Current value of the atom |
| `[1]` | `SetterFn` | Function to update the atom's value |
## Updater function
The setter supports both direct values and updater functions:
```ts
setCount(42) // Set directly
setCount(prev => prev + 1) // Update based on previous value
```
> **Note**
>
>
> If you only need to read the value, use [useValue](https://valdres.dev/react/useValue) instead — it has the same subscription behavior but a simpler return type. If you only need the setter, use [useSetAtom](https://valdres.dev/react/useSetAtom) to avoid subscribing to changes.
## See also
- [useValue](https://valdres.dev/react/useValue) — read-only hook (no setter)
- [useSetAtom](https://valdres.dev/react/useSetAtom) — write-only hook (no subscription)
- [useResetAtom](https://valdres.dev/react/useResetAtom) — reset to default value
---
Source: https://valdres.dev/react/useResetAtom.md
# useResetAtom
Signature
`useResetAtom(atom: Atom): () => void`
valdres-react
Reset an atom to its default value
Returns a function that resets an atom back to its default value. For async atoms, this re-triggers the initializer function.
## Usage
```tsx
import { atom } from "valdres"
import { useResetAtom, useAtom } from "valdres-react"
const countAtom = atom(0)
function Counter() {
const [count, setCount] = useAtom(countAtom)
const reset = useResetAtom(countAtom)
return (
{count}
)
}
```
## Resetting async atoms
> **Tip**
>
>
> When you reset an async atom, the initializer function runs again. Combined with `Suspense`, this gives you a clean refetch pattern.
```tsx
const dataAtom = atom(() =>
fetch("/api/data").then(res => res.json())
)
function RefreshButton() {
const reset = useResetAtom(dataAtom)
return
}
```
## See also
- [useAtom](https://valdres.dev/react/useAtom) — read + write hook
- [useSetAtom](https://valdres.dev/react/useSetAtom) — write-only hook
---
Source: https://valdres.dev/react/useSetAtom.md
# useSetAtom
Signature
`useSetAtom(atom: Atom): SetterFn`
valdres-react
Write-only access to an atom
Returns a setter function for an atom without subscribing to its value. The component won't re-render when the atom changes — useful for components that only need to trigger updates.
## Usage
```tsx
import { atom } from "valdres"
import { useSetAtom } from "valdres-react"
const countAtom = atom(0)
function IncrementButton() {
const setCount = useSetAtom(countAtom)
return
}
```
## Why use this over useAtom?
If a component only writes to an atom but never displays its value, `useSetAtom` avoids subscribing to changes. This means the component won't re-render when the atom updates, which can improve performance.
## See also
- [useAtom](https://valdres.dev/react/useAtom) — read + write hook
- [useResetAtom](https://valdres.dev/react/useResetAtom) — reset to default value
---
Source: https://valdres.dev/react/useStore.md
# useStore
Signature
`useStore(): Store`
valdres-react
Access the current store instance
Returns the current valdres store from the nearest ``, or the default global store if no Provider is present. Useful when you need direct store access for imperative operations.
## Usage
```tsx
import { useStore } from "valdres-react"
function Debug() {
const store = useStore()
const handleClick = () => {
// Direct store access for imperative operations
const value = store.get(myAtom)
console.log("Current value:", value)
}
return
}
```
## Transactions
Access the store to perform batched updates:
```tsx
function BatchUpdate() {
const store = useStore()
const handleReset = () => {
store.txn(({ set }) => {
set(nameAtom, "")
set(emailAtom, "")
set(ageAtom, 0)
})
}
return
}
```
## See also
- [Provider](https://valdres.dev/react/Provider) — provide a store to a React subtree
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/react/useStoreId.md
# useStoreId
Signature
`useStoreId(): string`
valdres-react
Identify the nearest store
Returns the id of the nearest ``'s store. Useful for debugging nested providers and scopes, or keying things per store. Throws if there is no `` above.
## Usage
```tsx
import { useStoreId } from "valdres-react"
function DebugBadge() {
const id = useStoreId()
return store: {id}
}
```
## See also
- [useStore](https://valdres.dev/react/useStore) — access the store itself
- [Provider](https://valdres.dev/react/Provider) — provide a store to the tree
---
Source: https://valdres.dev/react/useTransaction.md
# useTransaction
Signature
`useTransaction(store?: Store): (callback: (txn: Transaction) => any) => any`
valdres-react
Batch updates — subscribers fire once
Returns a function that runs a callback as a [transaction](https://valdres.dev/guides/transactions) on the current store: all updates apply atomically and subscribers fire once at the end. The callback receives `{ set, get, reset, del, unset }`.
## Usage
```tsx
import { atom } from "valdres"
import { useTransaction } from "valdres-react"
const firstNameAtom = atom("")
const lastNameAtom = atom("")
function ResetForm() {
const txn = useTransaction()
const clear = () =>
txn(({ reset }) => {
reset(firstNameAtom)
reset(lastNameAtom)
})
return
}
```
Pass a store to target one explicitly: `useTransaction(myStore)`.
## See also
- [Transactions guide](https://valdres.dev/guides/transactions) — semantics, nesting, and performance
- [useValdresCallback](https://valdres.dev/react/useValdresCallback) — memoized callback with transactional set/get
- [useStore](https://valdres.dev/react/useStore) — access the current store
---
Source: https://valdres.dev/react/useValdresCallback.md
# useValdresCallback
Signature
`useValdresCallback(callback: (set, get, reset) => Fn, deps): Fn`
valdres-react
Recoil-style callback hook
`useCallback` with store access: the outer function receives `set`, `get`, and `reset` and returns your event handler. The handler runs inside a transaction, so multiple updates commit atomically. Equivalent to Recoil's `useRecoilCallback`.
## Usage
```tsx
import { atom } from "valdres"
import { useValdresCallback } from "valdres-react"
const cartAtom = atom([])
const totalAtom = atom(0)
function AddButton({ id, price }: { id: string; price: number }) {
const add = useValdresCallback(
(set, get) => () => {
set(cartAtom, [...get(cartAtom), id])
set(totalAtom, get(totalAtom) + price)
},
[id, price],
)
return
}
```
The component doesn't subscribe to `cartAtom` or `totalAtom` — `get` reads the current value at call time without causing re-renders.
## See also
- [useTransaction](https://valdres.dev/react/useTransaction) — run an ad-hoc transaction
- [useSetAtom](https://valdres.dev/react/useSetAtom) — write a single atom without subscribing
---
Source: https://valdres.dev/react/useValue.md
# useValue
Signature
`useValue(state: Atom | Selector): T`
valdres-react
Read-only subscription to state
A read-only hook that subscribes to an atom or selector value. Use this when you only need to read state — the component won't cause unnecessary re-renders from setter changes.
## Usage
```tsx
import { atom, selector } from "valdres"
import { useValue } from "valdres-react"
const nameAtom = atom("Valdres")
const greetingSelector = selector(get => `Hello, ${get(nameAtom)}!`)
function Greeting() {
const greeting = useValue(greetingSelector)
return
{greeting}
}
```
## With selector families
```tsx
import { useValue } from "valdres-react"
import { userDisplayNameSelector } from "./state"
function UserName({ userId }) {
const name = useValue(userDisplayNameSelector(userId))
return {name}
}
```
## See also
- [useAtom](https://valdres.dev/react/useAtom) — read + write hook
- [useSetAtom](https://valdres.dev/react/useSetAtom) — write-only hook
---
Source: https://valdres.dev/angular/injectAtom.md
# injectAtom
Signature
`injectAtom(atom: Atom): AtomSignal`
valdres-angular
Subscribe to and update an atom's value
Returns an Angular `WritableSignal` that stays in sync with the atom. Reading the signal returns the current value, and calling `.set()` or `.update()` updates the atom. Also provides a `.reset()` method.
## Usage
```ts
import { Component } from "@angular/core"
import { atom } from "valdres"
import { injectAtom } from "valdres-angular"
const countAtom = atom(0)
@Component({
selector: "app-counter",
template: `
{{ count() }}
`,
})
export class CounterComponent {
count = injectAtom(countAtom)
}
```
## Returns
`AtomSignal` extends Angular's `WritableSignal` with:
| Method | Description |
| ------------- | --------------------------------- |
| `()` | Read the current value |
| `.set(value)` | Set a new value |
| `.update(fn)` | Update based on previous value |
| `.reset()` | Reset to the atom's default value |
## See also
- [injectValue](https://valdres.dev/angular/injectValue) — read-only signal
- [injectSetAtom](https://valdres.dev/angular/injectSetAtom) — write-only setter
- [injectResetAtom](https://valdres.dev/angular/injectResetAtom) — reset function
---
Source: https://valdres.dev/angular/injectResetAtom.md
# injectResetAtom
Signature
`injectResetAtom(atom: Atom): () => void`
valdres-angular
Reset an atom to its default value
Returns a function that resets an atom back to its default value.
## Usage
```ts
import { Component } from "@angular/core"
import { atom } from "valdres"
import { injectAtom, injectResetAtom } from "valdres-angular"
const countAtom = atom(0)
@Component({
selector: "app-counter",
template: `
{{ count() }}
`,
})
export class CounterComponent {
count = injectAtom(countAtom)
reset = injectResetAtom(countAtom)
}
```
## See also
- [injectAtom](https://valdres.dev/angular/injectAtom) — read + write signal
- [injectSetAtom](https://valdres.dev/angular/injectSetAtom) — write-only setter
---
Source: https://valdres.dev/angular/injectSetAtom.md
# injectSetAtom
Signature
`injectSetAtom(atom: Atom): SetterFn`
valdres-angular
Write-only access to an atom
Returns a setter function for an atom without subscribing to changes. The component won't be checked for changes when the atom updates.
## Usage
```ts
import { Component } from "@angular/core"
import { atom } from "valdres"
import { injectSetAtom } from "valdres-angular"
const countAtom = atom(0)
@Component({
selector: "app-increment",
template: ``,
})
export class IncrementComponent {
private setCount = injectSetAtom(countAtom)
increment = () => this.setCount(c => c + 1)
}
```
## See also
- [injectAtom](https://valdres.dev/angular/injectAtom) — read + write signal
- [injectResetAtom](https://valdres.dev/angular/injectResetAtom) — reset to default value
---
Source: https://valdres.dev/angular/injectStore.md
# injectStore
Signature
`injectStore(): Store`
valdres-angular
Access the current store instance
Injects the current valdres store from the Angular dependency injection system. Useful for imperative operations.
## Usage
```ts
import { Component } from "@angular/core"
import { injectStore } from "valdres-angular"
@Component({
selector: "app-debug",
template: ``,
})
export class DebugComponent {
private store = injectStore()
logValue() {
console.log("Current:", this.store.get(myAtom))
}
}
```
## See also
- [provideValdres](https://valdres.dev/angular/provideValdres) — setup valdres in Angular
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/angular/injectTransaction.md
# injectTransaction
Signature
`injectTransaction(store?: Store): (callback: (txn: Transaction) => any) => any`
valdres-angular
Batch updates — subscribers fire once
Returns a function that runs a callback as a [transaction](https://valdres.dev/guides/transactions) on the current store: all updates apply atomically and subscribers fire once at the end. The callback receives `{ set, get, reset, del, unset }`. Call it in an injection context (field initializer or constructor).
## Usage
```ts
import { Component } from "@angular/core"
import { atom } from "valdres"
import { injectTransaction } from "valdres-angular"
const firstNameAtom = atom("")
const lastNameAtom = atom("")
@Component({
selector: "reset-form",
template: ``,
})
export class ResetForm {
txn = injectTransaction()
clear() {
this.txn(({ reset }) => {
reset(firstNameAtom)
reset(lastNameAtom)
})
}
}
```
Pass a store to target one explicitly: `injectTransaction(myStore)`.
## See also
- [Transactions guide](https://valdres.dev/guides/transactions) — semantics, nesting, and performance
- [injectStore](https://valdres.dev/angular/injectStore) — access the current store
---
Source: https://valdres.dev/angular/injectValue.md
# injectValue
Signature
`injectValue(state: Atom | Selector): Signal`
valdres-angular
Read-only subscription to state
Returns a read-only Angular `Signal` that tracks an atom or selector value. The signal updates whenever the underlying state changes.
## Usage
```ts
import { Component } from "@angular/core"
import { atom, selector } from "valdres"
import { injectValue } from "valdres-angular"
const nameAtom = atom("Valdres")
const greetingSelector = selector(get => `Hello, ${get(nameAtom)}!`)
@Component({
selector: "app-greeting",
template: `
{{ greeting() }}
`,
})
export class GreetingComponent {
greeting = injectValue(greetingSelector)
}
```
## See also
- [injectAtom](https://valdres.dev/angular/injectAtom) — read + write signal
- [injectSetAtom](https://valdres.dev/angular/injectSetAtom) — write-only setter
---
Source: https://valdres.dev/angular/provideValdres.md
# provideValdres
Signature
`provideValdres(options?: ValdresOptions): EnvironmentProviders`
valdres-angular
Provide a store to your Angular app
Registers a valdres store in Angular's dependency injection system, making it available to all components via the `inject*` functions.
## Usage
```ts
import { bootstrapApplication } from "@angular/platform-browser"
import { provideValdres } from "valdres-angular"
import { AppComponent } from "./app.component"
bootstrapApplication(AppComponent, {
providers: [provideValdres()],
})
```
## With a custom store
```ts
import { store } from "valdres"
import { provideValdres } from "valdres-angular"
const myStore = store()
bootstrapApplication(AppComponent, {
providers: [provideValdres({ store: myStore })],
})
```
## See also
- [injectStore](https://valdres.dev/angular/injectStore) — access the store in components
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/angular/provideValdresScope.md
# provideValdresScope
Signature
`provideValdresScope(options?: ValdresScopeOptions): Provider[]`
valdres-angular
Create an isolated child store for an Angular component
Creates a scoped store that inherits state from the parent but can override values independently. All child components that inject Valdres will use the scoped store.
## Usage
```ts
import { Component } from "@angular/core"
import { provideValdresScope } from "valdres-angular"
@Component({
providers: [provideValdresScope({ scopeId: "modal" })],
template: ``,
})
export class ModalComponent {}
```
## Options
| Option | Type | Description |
| ------------ | ---------------------------------- | ----------------------------------------------- |
| `scopeId` | `string` | Optional identifier. Auto-generated if omitted. |
| `initialize` | `(txn) => void \| [Atom, value][]` | Optional callback to set initial values. |
## Initializing state
```ts
import { Component } from "@angular/core"
import { provideValdresScope, injectValue } from "valdres-angular"
import { nameAtom, emailAtom } from "./store"
@Component({
providers: [
provideValdresScope({
scopeId: "edit-form",
initialize: txn => {
txn.set(nameAtom, "Draft")
txn.set(emailAtom, "")
},
}),
],
template: ``,
})
export class EditFormHost {}
```
## Cleanup
The scope is automatically cleaned up when the component is destroyed.
## See also
- [Scoped Stores](https://valdres.dev/guides/scoped-stores) — full guide on scoped stores
- [provideValdres](https://valdres.dev/angular/provideValdres) — provide a store to your component tree
---
Source: https://valdres.dev/guides/compatibility.md
# 1.0 compatibility contract
These are deliberate Valdres 1.0 contracts. They are useful when choosing the
library, configuring a bundler, or deciding whether an upgrade changes
application behavior.
## ESM package and CommonJS loading
Valdres is ESM-only. The package does not ship a separate CommonJS build. Modern
Node.js can nevertheless load its ESM entry with `require()` through Node's
`require(esm)` support. The export map's `default` condition points to the same
ESM artifact as `import`, which is what a CommonJS resolver selects; it is not a
hidden CommonJS fallback. The published package requires Node.js 22.12 or newer.
Only the public export paths in the package export map are supported. Do not
import private `dist` chunks or source paths.
## Size
The honest size for the core runtime is about **30 KB gzip** in a minified
production consumer bundle. The exact number depends on the bundler and the
exports used; the release gate currently measures roughly 32 KB gzip for the
`atom` and `atom + selector + store` fixtures, and roughly 36 KB when every core
export is retained.
This is a consumer-bundle number, not the size of one source function after
tree-shaking and not the compressed npm tarball. Valdres publishes minified
JavaScript, and CI measures the packed artifact and representative consumer
bundles on every relevant change.
## Deep drop-equal is the default
Atoms, atom families, selectors, and selector families use deep structural
equality by default. When the next settled value is deeply equal to the current
value, Valdres drops the update: it keeps the current value and does not notify
dependents or subscribers. This avoids rerenders when an immutable update
recreates an equivalent object or collection.
Deep equality has a cost, and reference changes are sometimes meaningful. Use
the `equal` option as the explicit escape hatch. `Object.is` gives
reference/value identity semantics:
```ts
import { atom, selector } from "valdres"
const documentAtom = atom({ blocks: [] }, { equal: Object.is })
const viewSelector = selector(get => render(get(documentAtom)), {
equal: Object.is,
})
```
With `equal: Object.is`, replacing an object with a different but structurally
equal object is an update. In-place mutation remains unsupported because both
comparators see the same reference; replace the value when writing.
## Process-less runtimes
When `process.env.NODE_ENV` exists, Valdres follows it. When `process` does not
exist, as in many edge, worker, and direct-CDN runtimes, the default package
entry behaves as production. It skips development-only deep-freezing, validation
diagnostics, warnings, and instrumentation.
For debugging a process-less application, enable the package's `development`
export condition. Apply the condition consistently to `valdres` and every
framework adapter so the app does not load isolated default and development
runtime graphs. A URL-based, no-build ESM application can request the published
file from a CDN, for example
`https://unpkg.com/valdres@/dist/development/index.js`. This does not
make `valdres/dist/development/index.js` a supported package deep import: it is
not in the export map, so package consumers must use the `development`
condition. Bun enables that condition by default for development builds; use
`bun build --production` for a production process-less bundle.
## Selector-family identity is stable while live
Calling a `selectorFamily` repeatedly with the same key returns the same member
while a caller or live store retains that member. A subscription, dependency
edge, or an enumerable store's cold cache can provide that retention. The family
cache is weak: after the member is no longer reachable, garbage collection may
reclaim it and a later call may create a new object identity.
This is the “stable while live” contract. It provides stable identity wherever
the reactive graph needs it without turning every key ever queried into a
permanent memory entry. Calling `release(...args)` evicts a future family lookup
but does not invalidate references or store entries that are already live.
## Runtime and global-name singletons
Valdres permits multiple copies of the same known version in one JavaScript
global. The first import claims a `globalThis` instance slot; later copies of
that version adopt its process-wide `globalStore`, backing store data, name
registry, and global-family registry. This keeps global state unified when a
dependency graph happens to bundle Valdres more than once.
Different versions still throw with deduplication guidance. A duplicate also
throws when either copy's version is unknown, which is the case for unbuilt
source unless the build injects `process.env.VALDRES_VERSION`: without two known
versions, Valdres cannot establish that the engine contracts are compatible.
Names on atoms and atom families are global addresses used by state transfer,
not debug labels with module-local scope. They must be unique. Recreating an
ordinary named atom or family throws instead of silently replacing its
registered definition.
A `globalAtomFamily` has intentional singleton-by-name behavior: recreating it
under the same name returns the original family, and the later default factory
and options do not replace the first definition. Development builds warn when
this happens. This also defines its HMR behavior: during a hot update, the
global family keeps the definition that was registered first; perform a full
page or process reload to apply edits to that definition. A detectable contract
mismatch is never reused: an atom already registered under the name, or a later
`keyOf` with a different detectable arity, throws instead.
The instance guard and name registry live on the JavaScript global, so workers,
iframes, and separate server processes each have their own instance and
registry. They do not synchronize state across those boundaries.
## Stability boundary
The exported declarations in the packed package's `dist/types` tree are the
public TypeScript API. Valdres freezes that surface at the first 1.0 release
candidate and checks subsequent changes semantically. Private source modules,
private distribution chunks, and undocumented internal object fields are not
part of the compatibility contract.
---
Source: https://valdres.dev/guides/core-concepts.md
# Core Concepts
Valdres has four building blocks: **atoms**, **selectors**, **families**, and **stores**. Understanding these gets you 90% of the way.
## Atoms
An atom is the smallest unit of state. Create one with a default value:
```ts
import { atom } from "valdres"
const countAtom = atom(0)
const nameAtom = atom("world")
```
Atoms are just descriptions — they don't hold values themselves. Values live in a **store**.
## Selectors
A selector derives a value from one or more atoms (or other selectors). It re-computes automatically when its dependencies change:
```ts
import { selector } from "valdres"
const doubledCount = selector(get => get(countAtom) * 2)
const greeting = selector(get => `Hello, ${get(nameAtom)}!`)
```
Selectors are read-only by default. They're great for computed or filtered views of your state.
## Families
When you need many atoms or selectors indexed by a key — a list of users, a grid of cells, todo items by ID — use a family:
```ts
import { atomFamily, selectorFamily } from "valdres"
const userAtom = atomFamily(userId => ({ id: userId, name: "" }))
const userLabel = selectorFamily(userId =>
get => `User: ${get(userAtom(userId)).name}`
)
```
Calling `userAtom("abc")` returns the atom for that specific key. Atoms are created lazily on first access.
## Stores
A store holds all the atom values. You can create one explicitly, or let your framework adapter create a default one:
```ts
import { store } from "valdres"
const myStore = store()
myStore.set(countAtom, 42)
console.log(myStore.get(countAtom)) // 42
// Subscribe to changes
myStore.sub(countAtom, () => {
console.log("count changed:", myStore.get(countAtom))
})
```
In framework adapters, a store is typically provided via context (e.g. `` in React, `createValdres()` in Vue). If you don't provide one, a default global store is used.
## Putting It Together
```ts
import { atom, selector, store } from "valdres"
const todosAtom = atom([])
const completedCount = selector(get =>
get(todosAtom).filter(t => t.done).length
)
const myStore = store()
myStore.set(todosAtom, [
{ text: "Learn Valdres", done: true },
{ text: "Build something", done: false },
])
console.log(myStore.get(completedCount)) // 1
```
The core `valdres` package is framework-agnostic. Framework adapters like `valdres-react` add hooks and components that subscribe to store changes and trigger re-renders efficiently.
---
Source: https://valdres.dev/guides/example-currency.md
# Currency Converter
A currency converter that demonstrates async atoms for data fetching and selectors for derived computations. Exchange rates are fetched once and cached in an atom. The converted amount updates reactively as the user types.
## Shared state
```ts
import { atom, selector } from "valdres"
export const amountAtom = atom(100)
export const fromCurrencyAtom = atom("USD")
export const toCurrencyAtom = atom("EUR")
// Async atom — fetches exchange rates once, cached automatically
export const ratesAtom = atom(async () => {
const res = await fetch("https://api.exchangerate-api.com/v4/latest/USD")
const data = await res.json()
return data.rates as Record
})
// Derived: the converted amount
export const convertedAmountSelector = selector(get => {
const amount = get(amountAtom)
const from = get(fromCurrencyAtom)
const to = get(toCurrencyAtom)
const rates = get(ratesAtom)
// Convert: amount in "from" currency → USD → "to" currency
const amountInUsd = amount / rates[from]
return Math.round(amountInUsd * rates[to] * 100) / 100
})
export const currencies = ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "CNY"]
```
> **Async atoms are lazy**
>
>
> The fetch only runs when `ratesAtom` is first read. In React, this integrates with Suspense — wrap your component in `` and the loading state is handled for you.
## React
```tsx
import { Suspense } from "react"
import { useAtom, useValue } from "valdres-react"
import { amountAtom, fromCurrencyAtom, toCurrencyAtom, convertedAmountSelector, currencies } from "./state"
function CurrencyConverter() {
const [amount, setAmount] = useAtom(amountAtom)
const [from, setFrom] = useAtom(fromCurrencyAtom)
const [to, setTo] = useAtom(toCurrencyAtom)
const converted = useValue(convertedAmountSelector)
return (
setAmount(Number(e.target.value))}
/>
{converted}
)
}
// Wrap in Suspense for the async rates fetch
function App() {
return (
Loading exchange rates...}>
)
}
```
## Vue
```vue
`,
})
export class UserCard {
store = injectStore()
userId!: string
user = injectValue(userAtom(this.userId))
colors = { online: "#22c55e", away: "#eab308", offline: "#94a3b8" }
onStatus(e: Event) { setStatus(this.store, this.userId, (e.target as HTMLSelectElement).value) }
onRemove() { removeUser(this.store, this.userId) }
}
```
## Key takeaways
- **Dynamic collections** — `atomFamily` + `atom` for IDs is the idiomatic Valdres pattern for lists.
- **Per-item derived state** — `selectorFamily` computes derived values per user without recomputing for unrelated users.
- **Aggregate selectors** — the stats bar depends on all user atoms but only re-renders when an actual status changes.
- **Transactions** — adding and removing users atomically updates both the family and the ID list.
---
Source: https://valdres.dev/guides/example-notepad.md
# Shared Notepad
A notepad where text is synchronized across all framework implementations. Type in the React version and see it update in Vue, Svelte, Solid, and Angular — all through a single valdres store.
This example demonstrates the core value proposition: **your state is framework-agnostic**. The same atoms power every framework.
## Shared state
```ts
import { atom, selector, store } from "valdres"
export const noteAtom = atom("")
export const charCountSelector = selector(get => get(noteAtom).length)
export const wordCountSelector = selector(get => {
const text = get(noteAtom).trim()
return text ? text.split(/\s+/).length : 0
})
// One store shared across all frameworks
export const appStore = store()
```
> **One store, many frameworks**
>
>
> The `appStore` instance is imported by every framework. When React updates `noteAtom`, Vue and Svelte subscribers are notified immediately — there's no bridge, adapter, or event bus.
## React
```tsx
import { Provider, useAtom, useValue } from "valdres-react"
import { noteAtom, charCountSelector, wordCountSelector, appStore } from "./state"
function Notepad() {
const [note, setNote] = useAtom(noteAtom)
const chars = useValue(charCountSelector)
const words = useValue(wordCountSelector)
return (
{{ chars() }} characters · {{ words() }} words
`,
})
export class Notepad {
note = injectAtom(noteAtom)
chars = injectValue(charCountSelector)
words = injectValue(wordCountSelector)
}
```
## The cross-framework demo
Here's how you'd mount all five in the same page, sharing a single store:
```ts
// main.ts
import { appStore, noteAtom } from "./state"
// React
import { createRoot } from "react-dom/client"
import { Provider } from "valdres-react"
createRoot(document.getElementById("react-notepad")).render(
)
// Vue
import { createApp } from "vue"
import { createValdres } from "valdres-vue"
const vueApp = createApp(VueNotepad)
vueApp.use(createValdres({ store: appStore }))
vueApp.mount("#vue-notepad")
// Svelte
import { mount } from "svelte"
import SvelteNotepad from "./SvelteNotepad.svelte"
mount(SvelteNotepad, { target: document.getElementById("svelte-notepad") })
// All three textareas now stay in sync through appStore
```
Type in any one — the others update instantly.
## Key takeaways
- **Framework agnostic** — the state layer doesn't know or care which framework reads it.
- **No bridges needed** — React, Vue, and Svelte all subscribe to the same store directly. There's no event bus, postMessage, or custom synchronization.
- **Derived state works everywhere** — the word and character counts are selectors that every framework can use.
- **Micro-frontend friendly** — this pattern works for micro-frontends where different teams use different frameworks but share state.
---
Source: https://valdres.dev/guides/example-profile-editor.md
# Profile Editor
An edit form that uses scoped stores for a "save or cancel" pattern. The edit
form opens in a scope that inherits the current profile — edits stay isolated
until the user saves.
Scoped stores make this pattern unusually low-boilerplate — other libraries can
do it too, but typically require manually cloning the form state and diffing it
back on save.
## Shared state
```ts
import { atom, store } from "valdres"
export const profileAtom = atom({
name: "Alice Johnson",
email: "alice@example.com",
bio: "Software engineer",
})
```
## How it works
1. User clicks "Edit" — a scoped store is created, inheriting the current
profile
2. Edits happen inside the scope — the original profile is untouched
3. "Save" copies the scoped values back to the parent store
4. "Cancel" discards the scope — nothing changes
```
┌─ Parent Store ──────────────────┐
│ profileAtom: { name: "Alice" } │
│ │
│ ┌─ Edit Scope ──────────────┐ │
│ │ profileAtom: { name: "Bo" }│ │ ← edits are isolated
│ └───────────────────────────┘ │
└─────────────────────────────────┘
```
## React
```tsx
import { useState } from "react"
import { Provider, Scope, useValue, useAtom, useStore } from "valdres-react"
import { profileAtom } from "./state"
function ProfileView() {
const profile = useValue(profileAtom)
const parentStore = useStore()
const [editing, setEditing] = useState(false)
return (
{editing ? (
setEditing(false)}
/>
) : (
{profile.name}
{profile.email}
{profile.bio}
)}
)
}
function EditForm({ parentStore, onClose }) {
const [profile, setProfile] = useAtom(profileAtom)
const update = (field, value) => {
setProfile(prev => ({ ...prev, [field]: value }))
}
const handleSave = () => {
// Copy scoped value back to parent
parentStore.set(profileAtom, profile)
onClose()
}
return (
`,
})
export class ProfileEditForm {
@Input() parentStore!: Store
close = new EventEmitter()
profile = injectAtom(profileAtom)
update(field: string, value: string) {
this.profile.update(prev => ({ ...prev, [field]: value }))
}
handleSave() {
this.parentStore.set(profileAtom, this.profile())
this.close.emit()
}
}
```
## Key takeaways
- **Scoped stores** — edits are isolated in a child store. The parent state is
untouched until you explicitly save.
- **No copying** — you don't need to manually clone state into local form state.
The scope inherits everything automatically.
- **Cancel is free** — just unmount the scope. No cleanup, no reset logic.
- **Less boilerplate** — with Jotai, Zustand, or Redux you'd reach the same
result by manually cloning form state and writing it back; scoped stores
handle the inherit-and-commit for you.
---
Source: https://valdres.dev/guides/example-todo.md
# Todo List
A classic todo list that demonstrates `atomFamily` for individual items, family subscriptions for the list, and `selector` for derived counts.
## Shared state
This state definition is the same regardless of which framework you use:
```ts
import { atom, atomFamily, selector } from "valdres"
export const todoAtom = atomFamily()
export const todoIdsAtom = atom([])
export const remainingCountSelector = selector(get => {
const ids = get(todoIdsAtom)
return ids.filter(id => !get(todoAtom(id)).done).length
})
export function addTodo(store, title) {
const id = crypto.randomUUID()
store.txn(({ set }) => {
set(todoAtom(id), { id, title, done: false })
set(todoIdsAtom, ids => [...ids, id])
})
return id
}
export function toggleTodo(store, id) {
store.set(todoAtom(id), prev => ({ ...prev, done: !prev.done }))
}
export function removeTodo(store, id) {
store.txn(({ set }) => {
set(todoIdsAtom, ids => ids.filter(i => i !== id))
})
}
```
> **Why atomFamily?**
>
>
> Each todo lives in its own atom. When you toggle one todo, only the component rendering that specific todo re-renders — not the entire list. This gives you fine-grained updates for free.
## React
```tsx
import { useValue, useStore } from "valdres-react"
import { todoAtom, todoIdsAtom, remainingCountSelector, addTodo, toggleTodo, removeTodo } from "./state"
function TodoApp() {
const store = useStore()
const ids = useValue(todoIdsAtom)
const remaining = useValue(remainingCountSelector)
const handleAdd = (e) => {
e.preventDefault()
const input = e.target.elements.title
if (input.value.trim()) {
addTodo(store, input.value.trim())
input.value = ""
}
}
return (
{remaining} items remaining
{ids.map(id => )}
)
}
function TodoItem({ id }) {
const store = useStore()
const todo = useValue(todoAtom(id))
return (
)
}
```
## Vue
```vue
{{ remaining }} items remaining
```
```vue
```
## Svelte
```svelte
{remaining.value} items remaining
{#each ids.value as id (id)}
{@const todo = watch(todoAtom(id))}
{/each}
```
## Solid
```tsx
import { createValue, useStore } from "valdres-solid"
import { todoAtom, todoIdsAtom, remainingCountSelector, addTodo, toggleTodo, removeTodo } from "./state"
import { For } from "solid-js"
function TodoApp() {
const store = useStore()
const ids = createValue(todoIdsAtom)
const remaining = createValue(remainingCountSelector)
let inputRef
const handleAdd = (e) => {
e.preventDefault()
if (inputRef.value.trim()) {
addTodo(store, inputRef.value.trim())
inputRef.value = ""
}
}
return (
{remaining()} items remaining
{id => }
)
}
function TodoItem(props) {
const store = useStore()
const todo = createValue(todoAtom(props.id))
return (
`,
})
export class TodoApp {
store = injectStore()
ids = injectValue(todoIdsAtom)
remaining = injectValue(remainingCountSelector)
handleAdd(e: Event) {
e.preventDefault()
const input = (e.target as HTMLFormElement).elements.namedItem("title") as HTMLInputElement
if (input.value.trim()) {
addTodo(this.store, input.value.trim())
input.value = ""
}
}
}
@Component({
selector: "todo-item",
template: `
`,
inputs: ["todoId"],
})
export class TodoItem {
store = injectStore()
todoId!: string
todo = computed(() => injectValue(todoAtom(this.todoId))())
toggle() { toggleTodo(this.store, this.todoId) }
remove() { removeTodo(this.store, this.todoId) }
}
```
## Key takeaways
- **Fine-grained updates** — each todo is its own atom. Toggling one doesn't re-render the others.
- **Transactions** — adding a todo updates both the item atom and the ID list atomically.
- **Derived state** — the remaining count auto-updates when any todo changes.
- **Framework agnostic state** — the entire state layer (`state.ts`) is identical across all frameworks. Only the UI binding changes.
---
Source: https://valdres.dev/guides/installation.md
# Installation
Valdres is split into a core package (`valdres`) and framework-specific adapters. Install both the core and the adapter for your framework.
## React
npm
bun
yarn
pnpm
```bash
npm install valdres valdres-react
```
```bash
bun add valdres valdres-react
```
```bash
yarn add valdres valdres-react
```
```bash
pnpm add valdres valdres-react
```
## Vue
```bash
npm install valdres valdres-vue
```
## Svelte
```bash
npm install valdres valdres-svelte
```
## Solid
```bash
npm install valdres valdres-solid
```
## Angular
```bash
npm install valdres valdres-angular
```
## Vanilla (no framework)
If you don't need a framework adapter, the core package works standalone:
```bash
npm install valdres
```
```ts
import { atom, selector, store } from "valdres"
const myStore = store()
const countAtom = atom(0)
myStore.set(countAtom, 42)
console.log(myStore.get(countAtom)) // 42
```
---
Source: https://valdres.dev/guides/introduction.md
# Introduction
Valdres is a fast, reactive state management library for JavaScript and React. It's inspired by Recoil and Jotai with an emphasis on performance.
## Installation
npm
bun
yarn
pnpm
```bash
npm install valdres valdres-react
```
```bash
bun add valdres valdres-react
```
```bash
yarn add valdres valdres-react
```
```bash
pnpm add valdres valdres-react
```
## Quick Start
Create atoms to hold your state and selectors to derive computed values:
```ts
import { atom, selector } from "valdres"
const countAtom = atom(0)
const doubledSelector = selector(get => get(countAtom) * 2)
```
Use them in your React components:
```tsx
import { useAtom, useValue } from "valdres-react"
function Counter() {
const [count, setCount] = useAtom(countAtom)
const doubled = useValue(doubledSelector)
return (
Count: {count}
Doubled: {doubled}
)
}
```
## Key Concepts
- **Atoms** hold pieces of state. They can be read and written from anywhere.
- **Selectors** derive computed state from atoms. They update automatically when dependencies change.
- **Families** (`atomFamily`, `selectorFamily`) create collections of atoms/selectors keyed by a parameter.
- **Stores** hold all atom values. A default global store is used unless you provide a ``.
> **Tip**
>
>
> The core `valdres` package is framework-agnostic. You can use it with React via `valdres-react`, or without any framework at all.
## Quick Migrate
Already using Recoil or Jotai? Migration is a one-line import change:
```tsx
// From Recoil
import { atom, selector } from "@valdres-react/recoil"
// From Jotai
import { atom, createStore } from "@valdres-react/jotai"
```
> **Note**
>
>
> The compatibility packages mirror the original APIs, so most of your existing code works unchanged. See the [Jotai](https://valdres.dev/guides/vs-jotai) and [Recoil](https://valdres.dev/guides/vs-recoil) comparison guides for details.
---
Source: https://valdres.dev/guides/migration.md
# Migration Guide
Valdres provides drop-in compatibility packages for both Recoil and Jotai. You can migrate your entire app by changing a single import — then gradually adopt the native Valdres API at your own pace.
## From Recoil
Replace your Recoil import with the Valdres compatibility layer:
```ts
// Before
import { atom, selector, useRecoilState } from "recoil"
// After
import { atom, selector, useRecoilState } from "@valdres-react/recoil"
```
Install the package:
```bash
npm install @valdres-react/recoil
```
That's it. Most existing Recoil code keeps working — now backed by Valdres under the hood — so you can migrate the import first and adopt the native API at your own pace.
> **Why migrate from Recoil?**
>
>
> Recoil is no longer actively maintained. Valdres is actively developed, has a zero-dependency core, and doesn't require string keys for atoms.
## From Jotai
Replace your Jotai import with the Valdres compatibility layer:
```ts
// Before
import { atom, createStore } from "jotai"
// After
import { atom, createStore } from "@valdres-react/jotai"
```
Install the package:
```bash
npm install @valdres-react/jotai
```
## Gradual adoption
Once you've migrated, you can incrementally adopt the native Valdres API:
1. **Replace imports** — Switch from `@valdres-react/recoil` or `@valdres-react/jotai` to `valdres` and `valdres-react`
2. **Use native hooks** — Replace `useRecoilState` with `useAtom`, `useRecoilValue` with `useValue`
3. **Adopt new features** — Start using transactions, first-class families, and framework-agnostic state
```ts
// Compatibility layer
import { atom } from "@valdres-react/recoil"
import { useRecoilState } from "@valdres-react/recoil"
// Native Valdres
import { atom } from "valdres"
import { useAtom } from "valdres-react"
```
## Key differences from Recoil
| Feature | Recoil | Valdres |
| ----------------- | -------------------- | ---------------------------------------- |
| Atom keys | Required string keys | No keys needed (identified by reference) |
| Dependencies | Several | Zero (core) |
| Maintenance | Abandoned | Actively developed |
| Families | Utility | First-class primitive |
| Framework support | React only | React, Vue, Svelte, Solid, Angular |
## Key differences from Jotai
| Feature | Jotai | Valdres |
| ----------------- | ---------------------- | ---------------------------------- |
| React integration | useEffect + useReducer | useSyncExternalStore |
| Atom types | Unified atom concept | Separate atom + selector |
| Families | Community utility | First-class with subscription |
| Transactions | Not explicit | Built-in `store.txn()` |
| Framework support | React only | React, Vue, Svelte, Solid, Angular |
---
Source: https://valdres.dev/guides/motivation.md
# Motivation
Valdres was created due to performance issues encountered building an offline-first process model editor. We started with Recoil, then moved to Jotai when the Recoil project appeared to be abandoned — but ran into performance bottlenecks with Jotai as well.
The core insight was that `useSyncExternalStore` (used by Zustand) provides better React integration performance than the `useEffect` + `useReducer` pattern used by Jotai. Valdres combines the atom-based model of Recoil/Jotai with the subscription approach of Zustand.
## Design Principles
- **Performance first** — designed for apps with hundreds of atoms and frequent updates
- **Separate atoms and selectors** — clearer mental model than Jotai's unified atom concept
- **First-class families** — `atomFamily` and `selectorFamily` are core primitives, not utilities
- **Transactions** — batch multiple updates so subscribers fire once
- **No framework lock-in** — the core `valdres` package has zero dependencies and works outside React
---
Source: https://valdres.dev/guides/outside-react.md
# Works Everywhere
Unlike most state management libraries, Valdres doesn't depend on any framework. The core `valdres` package is pure JavaScript — it works in Node.js, Deno, Bun, web workers, service workers, or any JavaScript runtime.
This is a fundamental design choice, not an afterthought. Your state logic lives in `valdres`, and framework bindings (`valdres-react`, `valdres-vue`, etc.) are thin adapters that subscribe to it.
## Vanilla JavaScript
```ts
import { atom, selector, store } from "valdres"
const myStore = store()
const countAtom = atom(0)
const doubleSelector = selector(get => get(countAtom) * 2)
myStore.get(countAtom) // 0
myStore.get(doubleSelector) // 0
myStore.set(countAtom, 5)
myStore.get(doubleSelector) // 10
// Subscribe to changes
const unsub = myStore.sub(countAtom, () => {
console.log("count changed:", myStore.get(countAtom))
})
myStore.set(countAtom, 10)
// logs: "count changed: 10"
unsub() // stop listening
```
## Node.js / server-side
Valdres works on the server without any special configuration. This is useful for server-side rendering, API routes, or background jobs that share state definitions with the frontend.
```ts
// shared/state.ts — shared between client and server
import { atom, atomFamily } from "valdres"
export const sessionAtom = atom(null)
export const cacheAtom = atomFamily()
```
```ts
// server.ts
import { store } from "valdres"
import { sessionAtom, cacheAtom } from "./shared/state"
const serverStore = store()
// Pre-populate state on the server
serverStore.set(sessionAtom, { userId: "abc", role: "admin" })
serverStore.set(cacheAtom("config"), await loadConfig())
// Pass state to the client via serialization
const snapshot = {
session: serverStore.get(sessionAtom),
config: serverStore.get(cacheAtom("config")),
}
// Release global-atom registrations held for this request.
serverStore.dispose()
```
For real request handlers, put `dispose()` in a `finally` block so thrown
renders and aborted requests are cleaned up too.
## Web Workers
Since Valdres has no DOM dependency, it runs natively in web workers. Keep heavy computation off the main thread while sharing state definitions.
```ts
// worker.ts
import { atom, store } from "valdres"
const progressAtom = atom(0)
const workerStore = store()
self.onmessage = async (event) => {
const items = event.data
for (let i = 0; i < items.length; i++) {
await processItem(items[i])
workerStore.set(progressAtom, (i + 1) / items.length)
self.postMessage({ progress: workerStore.get(progressAtom) })
}
}
```
## Testing
Testing with Valdres is straightforward — create a store, set state, assert. No providers, no mocking, no framework overhead.
```ts
import { atom, selector, store } from "valdres"
import { expect, test } from "bun:test"
const countAtom = atom(0)
const doubleSelector = selector(get => get(countAtom) * 2)
test("selector derives from atom", () => {
const testStore = store()
testStore.set(countAtom, 5)
expect(testStore.get(doubleSelector)).toBe(10)
})
test("transactions are atomic", () => {
const testStore = store()
const a = atom(100)
const b = atom(100)
const total = selector(get => get(a) + get(b))
testStore.txn(({ set }) => {
set(a, 50)
set(b, 150)
})
expect(testStore.get(total)).toBe(200)
})
```
## Sharing state across frameworks
Because state lives in the store — not in components — you can share the same atoms across different frameworks in the same app. This is what powers the demo on our homepage.
```ts
// shared.ts — import this from React, Vue, Svelte, or anything else
import { atom, store } from "valdres"
export const appStore = store()
export const countAtom = atom(0)
export const themeAtom = atom("dark")
```
Each framework adapter just subscribes to the same store:
```tsx
// In React
import { useValue } from "valdres-react"
import { countAtom } from "./shared"
const count = useValue(countAtom)
```
```vue
```
## Why this matters
Most state libraries are tightly coupled to a specific framework's rendering model. This means:
- You can't test state logic without mounting components
- You can't share state between micro-frontends using different frameworks
- You can't use state in workers, CLI tools, or server code
- Migration between frameworks requires rewriting state management
Valdres avoids all of these problems by keeping state management framework-agnostic at its core.
---
Source: https://valdres.dev/guides/patterns.md
# Patterns & Recipes
Practical patterns for building real applications with Valdres.
## Todo list with families
Use `atomFamily` to model a collection of items, with a separate atom tracking the list of IDs.
```ts
import { atom, atomFamily } from "valdres"
const todoAtom = atomFamily()
const todoIdsAtom = atom([])
// Add a todo
function addTodo(store, title) {
const id = crypto.randomUUID()
store.txn(({ set }) => {
set(todoAtom(id), { id, title, done: false })
set(todoIdsAtom, ids => [...ids, id])
})
}
// Toggle completion
function toggleTodo(store, id) {
store.set(todoAtom(id), prev => ({ ...prev, done: !prev.done }))
}
```
In React, render each todo with fine-grained updates — only the changed todo re-renders:
```tsx
import { useValue, useSetAtom } from "valdres-react"
function TodoList() {
const ids = useValue(todoIdsAtom)
return ids.map(id => )
}
function TodoItem({ id }) {
const todo = useValue(todoAtom(id))
return (
)
}
```
## Async data fetching
Atoms can be initialized with async functions. They work seamlessly with React Suspense.
```tsx
import { atom } from "valdres"
import { useValue } from "valdres-react"
import { Suspense } from "react"
const userAtom = atom(async () => {
const res = await fetch("/api/user")
return res.json()
})
function UserProfile() {
const user = useValue(userAtom)
return
{user.name}
}
// Wrap in Suspense
function App() {
return (
Loading...}>
)
}
```
## Derived collections
Use `selectorFamily` to derive computed values for each item in a collection.
```ts
import { selector, selectorFamily } from "valdres"
const todoAtom = atomFamily()
// Derived: display text for each todo
const todoDisplaySelector = selectorFamily(id => get => {
const todo = get(todoAtom(id))
return todo.done ? `✓ ${todo.title}` : todo.title
})
// Derived: count of completed todos
const completedCountSelector = selector(get => {
const ids = get(todoIdsAtom)
return ids.filter(id => get(todoAtom(id)).done).length
})
```
## Transactions for consistent updates
When multiple atoms need to change together, use transactions. Subscribers only fire once after all updates complete.
```ts
import { atom, store } from "valdres"
const balanceA = atom(100)
const balanceB = atom(100)
const myStore = store()
// Without transaction: components see intermediate state
myStore.set(balanceA, prev => prev - 50)
myStore.set(balanceB, prev => prev + 50) // brief moment where $50 is "missing"
// With transaction: atomic update
myStore.txn(({ set }) => {
set(balanceA, prev => prev - 50)
set(balanceB, prev => prev + 50)
// Subscribers fire once, after both updates
})
```
## Form state
Use individual atoms for each field instead of one big form object. This gives you fine-grained re-renders — updating one field doesn't re-render the others.
```ts
import { atom } from "valdres"
const nameAtom = atom("")
const emailAtom = atom("")
const messageAtom = atom("")
```
```tsx
import { useAtom, useValue } from "valdres-react"
function NameField() {
const [name, setName] = useAtom(nameAtom)
return setName(e.target.value)} />
}
function EmailField() {
const [email, setEmail] = useAtom(emailAtom)
return setEmail(e.target.value)} />
}
// Only re-renders when all three change (e.g., for a preview)
function FormPreview() {
const name = useValue(nameAtom)
const email = useValue(emailAtom)
const message = useValue(messageAtom)
return
}
```
## Subscribing to a family
Unlike other libraries, you can subscribe to an entire `atomFamily` to get notified when items are added or removed.
```ts
import { atomFamily, store } from "valdres"
const userAtom = atomFamily()
const myStore = store()
// Family callbacks receive the arguments of the member that changed
myStore.sub(userAtom, id => {
console.log("Changed user ID:", id)
})
myStore.set(userAtom("user-1"), { name: "Alice" })
// logs: Changed user ID: user-1
myStore.set(userAtom("user-2"), { name: "Bob" })
// logs: Changed user ID: user-2
```
## State outside of components
Valdres state lives in a store, not in components. You can read and write state from anywhere — event handlers, WebSocket callbacks, service workers, or tests.
```ts
import { atom, store } from "valdres"
const myStore = store()
const statusAtom = atom("idle")
// From a WebSocket
ws.addEventListener("message", event => {
const data = JSON.parse(event.data)
myStore.set(statusAtom, data.status)
})
// From a timer
setInterval(() => {
myStore.set(statusAtom, "polling")
}, 5000)
// In a test
myStore.set(statusAtom, "testing")
expect(myStore.get(statusAtom)).toBe("testing")
```
---
Source: https://valdres.dev/guides/performance.md
# Performance
> **Continuously verified**
>
>
> These benchmarks run on every commit. If a regression is detected, the PR is blocked until performance is restored.
Benchmarks: [https://valdres.dev/guides/performance](https://valdres.dev/guides/performance)
## Why the core is fast
The engine is optimized for minimal allocations and cache-friendly data structures — WeakMap-based storage with no intermediate objects, and transactions that batch updates so subscribers fire once.
In **React** specifically, the adapter is built on `useSyncExternalStore` (where Jotai uses `useEffect` + `useReducer`), which avoids extra renders and effect-cleanup overhead. The other adapters integrate with each framework's native reactivity — Vue refs, Svelte runes, Solid signals, Angular signals — so there the relevant performance is the framework's own.
> **What these numbers are (and aren't)**
>
>
> Every benchmark here compares the core Valdres engine against Jotai at the JavaScript level. They are not framework-rendering benchmarks, and Valdres does not claim to be faster than a framework's native reactivity (e.g. Svelte runes). The adapters exist to share one store across frameworks, not to outrun them.
## Running benchmarks locally
```bash
# Bun (JSC/Safari engine)
bun run --cwd packages/valdres test:bench
# Node.js (V8/Chrome engine)
bun run --cwd packages/valdres test:bench:node
```
## Historical trends
Performance is tracked over time on every push to `main`. View the live, always-current numbers and history at [bencher.dev/perf/valdres](https://bencher.dev/perf/valdres).
---
Source: https://valdres.dev/guides/quick-start-angular.md
# Quick Start with Angular
## Install
```bash
npm install valdres valdres-angular
```
## Create your first atom
```ts
// store.ts
import { atom } from "valdres"
export const countAtom = atom(0)
```
## Use it in a component
```ts
import { Component } from "@angular/core"
import { injectAtom } from "valdres-angular"
import { countAtom } from "./store"
@Component({
template: `
Count: {{ count() }}
`,
})
export class CounterComponent {
count = injectAtom(countAtom)
}
```
## Provide a store
Use `provideValdres` in your app config:
```ts
import { provideValdres } from "valdres-angular"
export const appConfig = {
providers: [provideValdres()],
}
```
## Read-only values
Use `injectValue` when you only need to read:
```ts
import { Component } from "@angular/core"
import { injectValue } from "valdres-angular"
import { countAtom } from "./store"
@Component({
template: `
The count is {{ count() }}
`,
})
export class DisplayComponent {
count = injectValue(countAtom)
}
```
## Next steps
- [Core Concepts](https://valdres.dev/guides/core-concepts) — atoms, selectors, families, stores
- [Patterns & Recipes](https://valdres.dev/guides/patterns) — real-world examples
---
Source: https://valdres.dev/guides/quick-start-solid.md
# Quick Start with Solid
## Install
```bash
npm install valdres valdres-solid
```
## Create your first atom
```ts
// store.ts
import { atom } from "valdres"
export const countAtom = atom(0)
```
## Use it in a component
```tsx
import { createAtom } from "valdres-solid"
import { countAtom } from "./store"
function Counter() {
const [count, setCount] = createAtom(countAtom)
return (
Count: {count()}
)
}
```
## Provide a store
Wrap your app with `ValdresProvider`:
```tsx
import { ValdresProvider } from "valdres-solid"
function App() {
return (
)
}
```
## Read-only values
Use `createValue` when you only need to read:
```tsx
import { createValue } from "valdres-solid"
import { countAtom } from "./store"
function Display() {
const count = createValue(countAtom)
return
The count is {count()}
}
```
## Next steps
- [Core Concepts](https://valdres.dev/guides/core-concepts) — atoms, selectors, families, stores
- [Patterns & Recipes](https://valdres.dev/guides/patterns) — real-world examples
---
Source: https://valdres.dev/guides/quick-start-svelte.md
# Quick Start with Svelte
`valdres-svelte` is the Svelte 5 (runes) adapter. It bridges valdres atoms and
selectors into reactive boxes you read with `.current`, plus a store-contract
bridge for `$`-syntax and a provider tier for SSR.
## Install
```bash
npm install valdres valdres-svelte
```
## Create your first atom
```ts
// store.ts
import { atom } from "valdres"
export const countAtom = atom(0)
```
## Provide a store
Call `setValdresContext` once near the root so descendants share a store. With
no argument it creates a `store({ batchUpdates: true })` for the component tree
— which on the server means one store per request, the pattern SvelteKit wants.
```svelte
{@render children()}
```
## Read and write with `fromState`
`fromState` returns a reactive box. For an atom, `.current` is readable **and**
writable, so `bind:value` and `count.current++` just work. For a
read-modify-write it also has `update(fn)` (like `svelte/store`'s
`Writable.update`) and a `reset()`.
```svelte
Count: {count.current}
```
Pass an explicit store as the second argument (`fromState(countAtom, store)`)
when you're outside component initialization — e.g. in plain `.svelte.ts`
module state. Without it, the box resolves the store from context, which is only
available during init.
A selector (or any read-only state) yields a box with a read-only `.current`:
```svelte
Doubled: {double.current}
```
## `$`-syntax with `toStore`
For Svelte's store contract (`$`-prefix auto-subscription, `bind:value={$count$}`),
use `toStore`. An atom becomes a `Writable`; a selector becomes a read-only
`Readable`. The store argument is optional and falls back to context.
```svelte
Count: {$count$}
```
## Scoped state
`scope` creates a child store layered over the parent for a subtree, with an
optional `initialize` to seed it. It detaches automatically when the component
is destroyed. Descendants reading via `fromState`/`toStore` resolve the scoped
store.
```svelte
Scoped count: {count.current}
```
## Transactions
`transaction()` returns a runner bound to the context store, captured at
component init. That capture is what makes it safe to call from an event
handler — Svelte throws `lifecycle_outside_component` if you call `getContext`
inside a handler.
```svelte
```
## Async selectors
A selector can return a promise. Core erases asyncness, so `fromState(sel).current`
is typed `V | Promise` — consume it with Svelte's `{#await}` block:
```svelte
{#await user.current}
Loading…
{:then u}
Hello {u.name}
{:catch error}
Failed: {error.message}
{/await}
```
When you'd rather branch on flags than `await`, `resourceState` runs the
promise detection for you and returns `{ current, loading, error }`:
```svelte
{#if user.loading}
Loading…
{:else if user.error}
Failed: {String(user.error)}
{:else}
Hello {user.current?.name}
{/if}
```
## SvelteKit (SSR)
Load data on the server, then map it to atoms with `initialize` in the root
layout. Because `initialize` runs on both the server render and the client
hydration, the atoms hold the right values in both passes — no custom
serializer needed.
```ts
// +layout.server.ts
export const load = async () => {
return { count: 7 } // plain, serializable
}
```
```svelte
{@render children()}
```
If your `load` data is itself a `dehydrate(store)` payload (e.g. produced by an
API that ran a server-side valdres store), pass it as `hydrate` instead — it's
applied as a standalone commit on the fresh store. Atoms carrying a codec schema
round-trip `BigInt`/`Date`/`Map`/`Set` over plain JSON automatically. When both
are given, `initialize` runs first so hydrated values win.
```svelte
{@render children()}
```
## Gotcha: lazy bootstrap
The reactive box subscribes lazily (it's built on Svelte's `createSubscriber`,
the same primitive behind `MediaQuery`). A valdres atom with an `onMount`
bootstrap — the `@valdres/browser-*` packages, for instance — only starts once
`.current` is **read inside an effect** (a template expression, `$derived`,
`$effect`). A component that reads the value solely from an event handler will
see the unbootstrapped default. Read it in the template, or via `$`-syntax with
`toStore`, to start the subscription. If you genuinely need it to start without
rendering it, force the subscription with a throwaway effect:
```svelte
```
## Next steps
- [Core Concepts](https://valdres.dev/guides/core-concepts) — atoms, selectors, families, stores
- [Patterns & Recipes](https://valdres.dev/guides/patterns) — real-world examples
---
Source: https://valdres.dev/guides/quick-start-vue.md
# Quick Start with Vue
## Install
```bash
npm install valdres valdres-vue
```
## Create your first atom
```ts
// store.ts
import { atom } from "valdres"
export const countAtom = atom(0)
```
## Use it in a component
```vue
Count: {{ count }}
```
## Provide a store
Wrap your app with `createValdres` to provide a store to all components:
```ts
// main.ts
import { createApp } from "vue"
import { createValdres } from "valdres-vue"
import App from "./App.vue"
const app = createApp(App)
app.use(createValdres())
app.mount("#app")
```
## Read-only values
Use `useValue` when you only need to read:
```vue
The count is {{ count }}
```
## Next steps
- [Core Concepts](https://valdres.dev/guides/core-concepts) — atoms, selectors, families, stores
- [Patterns & Recipes](https://valdres.dev/guides/patterns) — real-world examples
---
Source: https://valdres.dev/guides/schema-validation.md
# Schema Validation
Atoms and selectors accept an optional `schema` that validates values at
runtime — and types your state without a generic. Validation is **opt-in per
store** and off by default, so it adds zero cost unless you turn it on.
```ts
import { atom, store } from "valdres"
import { z } from "zod"
const userAtom = atom(
{ name: "Ada", age: 36 },
{
name: "userAtom",
schema: z.object({ name: z.string(), age: z.number().min(0) }),
},
)
const s = store({ schemaValidation: true })
s.set(userAtom, { name: "Bob", age: -1 })
// SchemaValidationError: Schema validation failed for 'userAtom': …
```
## Two features in one
1. **Type inference.** The schema is the single source of truth for the atom's
type — `atom(undefined, { schema: z.string() })` is `Atom`, no
generic needed. This works even when validation is off.
2. **Runtime validation.** With validation enabled, every value entering the
store is checked against the schema — catching the bugs TypeScript can't see
(API responses with the wrong shape, form input, data crossing team
boundaries).
## Enabling validation
Validation is off by default. Enable it per store:
```ts
const devStore = store({ schemaValidation: true })
```
Scoped stores inherit the setting from their parent. A typical setup enables it
everywhere except production:
```ts
const appStore = store({ schemaValidation: import.meta.env.DEV })
```
An individual atom or selector can override the store's setting:
```ts
// Always validated — even in a store with validation off.
// Useful for true boundary atoms (API responses, URL params).
const apiResponseAtom = atom(undefined, {
schema: responseSchema,
schemaValidation: true,
})
// Never validated — even in a store with validation on.
const hotPathAtom = atom(0, {
schema: z.number(),
schemaValidation: false,
})
```
## Supported schema libraries
Any [Standard Schema](https://standard-schema.dev) works — Zod 3.24+/4,
Valibot, ArkType, and others — as well as any classic validator with a
`parse(value)` method.
```ts
import * as v from "valibot"
const nameAtom = atom("Ada", { schema: v.string() })
```
When a schema offers both interfaces (like Zod), the `parse` path is used so
the library's native error (e.g. a `ZodError`) is preserved on the thrown
error's `cause`.
## Validate-only semantics
The schema runs purely as a check — **the original value is stored unchanged**.
A store with validation on holds exactly the same values as one with it off, so
enabling validation in development can never make behavior diverge from
production.
The flip side: one-way transforming or coercing schemas (`z.coerce.number()`,
`z.string().trim()`, `z.string().default(...)`) validate but do **not**
transform. Avoid them here — the inferred type follows the schema's output
while the stored value stays the input. Do coercion at your data boundary
(form handler, fetch layer) and give the atom a plain validator instead.
Bidirectional codecs are the sanctioned exception — see below.
## Wire codecs (zod ≥ 4.1)
A [zod codec](https://zod.dev/codecs) is a bidirectional schema: `decode` turns
the wire representation into the runtime value, `encode` turns it back. Give an
atom a codec and `dehydrate`/`hydrate` move JS-native values — BigInt, Date,
Map, Set — over a plain JSON wire with no custom serializer:
```ts
import { atom, dehydrate, hydrate, store } from "valdres"
import { z } from "zod"
const bigintCodec = z.codec(z.string(), z.bigint(), {
decode: s => BigInt(s),
encode: b => b.toString(),
})
const mapCodec = z.codec(
z.array(z.tuple([z.string(), z.number()])),
z.map(z.string(), z.number()),
{ decode: entries => new Map(entries), encode: m => [...m.entries()] },
)
const setCodec = z.codec(z.array(z.string()), z.set(z.string()), {
decode: values => new Set(values),
encode: s => [...s],
})
const supplyAtom = atom(0n, { name: "app/supply", schema: bigintCodec }) // Atom
const scoresAtom = atom(new Map(), { name: "app/scores", schema: mapCodec })
const tagsAtom = atom(new Set(), { name: "app/tags", schema: setCodec })
// server — the payload is plain JSON: BigInt is a string, Map/Set are arrays
const payload = dehydrate(serverStore)
const html = ``
// client — decode restores the runtime values
hydrate(clientStore, window.__STATE__)
clientStore.get(supplyAtom) // 900719925474099100n (a real BigInt)
clientStore.get(scoresAtom) // Map { "a" → 1 }
```
The atom stores the codec's _output_ type (`Atom`), and setting runtime
values passes validation — the encode direction is what's checked. Decoding at
`hydrate` inherently validates the wire value, so a tampered or stale payload
entry fails loudly instead of landing silently.
**The codec must sit at the non-JSON position.** A plain `z.bigint()` or
`z.map(...)` inside an object validates the runtime value but encodes as an
identity — `JSON.stringify` will still throw on the BigInt and silently turn
the Map into `{}`:
```ts
// ✗ validates, but cannot cross a JSON wire
z.object({ supply: z.bigint(), scores: z.map(z.string(), z.number()) })
// ✓ codecs at the non-JSON positions — nested codecs encode through
z.object({ supply: bigintCodec, scores: mapCodec })
```
Wire codecs are a zod ≥ 4.1 feature (any schema exposing
`safeEncode`/`safeDecode`). Validation itself works with any supported schema
library; atoms whose schema can't encode — including one-way transform
schemas — transfer their raw value exactly as without a schema.
**Codecs cover values, not family keys.** `dehydrate` emits an atomFamily
member's arguments raw, and `hydrate` re-derives the member by calling
`family(...args)` with the JSON-parsed args. Family keys accept more than JSON
does — `Date`, `Map`, `Set`, `BigInt`, `NaN` — because key identity is a local
concern, but those args don't survive the wire: a `Date` comes back as its ISO
string and resolves to a _different_ member, so the hydrated value lands
somewhere nothing reads while the real member keeps its default. Dev-mode
`dehydrate` throws on such an entry, naming the family and the argument path;
key transferred families by strings and numbers instead.
```ts
const eventsAtom = atomFamily([], { name: "app/events" })
eventsAtom(new Date("2024-01-01")) // fine locally
dehydrate(store) // throws in dev: args[0] is a Date
// ✓ key by a value JSON round-trips unchanged
const eventsAtom = atomFamily([], { name: "app/events" })
eventsAtom("2024-01-01")
```
## What gets validated
With validation enabled, values are checked at every write boundary:
| Boundary | On failure |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `store.set(atom, value)` | throws `SchemaValidationError` |
| Atom defaults (static, function, selector) | throws on first read |
| Selector results | throws on evaluation |
| `store.txn(...)` writes | throws inside the txn body — the whole transaction aborts, nothing is committed |
| Async values (a promise resolving to an invalid value) | reported via `console.error`; the invalid value is **never committed** |
Async failures can't throw to the original caller (the promise was already
returned), which is why they're reported instead. For an async `set`, the atom
reverts to its previous value; for an async default, the value is dropped so a
later read retries.
## Error handling
Sync failures throw a `SchemaValidationError` (exported from `valdres`) that
names the offending atom or selector and keeps the underlying error on `cause`:
```ts
import { SchemaValidationError } from "valdres"
try {
s.set(userAtom, badValue)
} catch (err) {
if (err instanceof SchemaValidationError) {
console.log(err.message) // Schema validation failed for 'userAtom': …
console.log(err.cause) // the ZodError (or library-native error)
}
}
```
Give your atoms a `name` — it's what makes these errors debuggable in an app
with hundreds of atoms.
## Limitations
- **Async defaults under React Suspense:** an invalid async default drops its
value (like a rejected one), so a component that keeps re-reading will
re-initialize and re-fetch. Validate at the fetch boundary rather than
relying on async-default validation under Suspense.
- **Asynchronous schemas** (an async Standard Schema, or a Zod schema with an
async `refine`) are not supported — validation runs synchronously and
surfaces a clear error. Use synchronous schemas.
## When to use it
Most internal state doesn't need runtime validation — TypeScript already covers
a `countAtom`. Schemas earn their keep at **system boundaries**: API responses,
form input, URL/storage-hydrated state, and atoms one team owns while another
writes. A good default: type inference everywhere you like, runtime validation
on boundary atoms via the per-atom override, and the store-wide flag on in
development as a safety net.
## See also
- [Core Concepts](https://valdres.dev/guides/core-concepts) — atoms, selectors, and stores
- [TypeScript](https://valdres.dev/guides/typescript) — more on type inference
- The `atom`, `selector`, and `store` API pages document the `schema` and
`schemaValidation` options in detail
---
Source: https://valdres.dev/guides/scoped-stores.md
# Scoped Stores
Scoped stores are child stores that inherit all state from their parent but can
override values independently. Think of them as a "fork" of state — reads fall
through to the parent, but writes stay local.
This is useful for modals, multi-step forms, drag previews, multi-tenant UIs, or
any scenario where you need isolated copies of shared state.
## How it works
```ts
import { atom, store } from "valdres"
const nameAtom = atom("Alice")
const rootStore = store()
// Create a scoped child store
const childStore = rootStore.scope("child-1")
```
### Reading: inherits from parent
```ts
rootStore.set(nameAtom, "Alice")
childStore.get(nameAtom) // "Alice" — falls through to parent
```
### Writing: stays local
```ts
childStore.set(nameAtom, "Bob")
childStore.get(nameAtom) // "Bob" — shadowed in child
rootStore.get(nameAtom) // "Alice" — parent unchanged
```
### Parent updates don't overwrite shadows
Once a scope shadows an atom, parent updates to that atom no longer affect the
scope:
```ts
rootStore.set(nameAtom, "Charlie")
rootStore.get(nameAtom) // "Charlie"
childStore.get(nameAtom) // "Bob" — still the scoped value
```
But atoms that the scope _hasn't_ shadowed continue to flow through:
```ts
const ageAtom = atom(30)
rootStore.set(ageAtom, 31)
childStore.get(ageAtom) // 31 — still reading from parent
```
## Selectors in scopes
Selectors automatically evaluate against the scope's view of state:
```ts
import { atom, selector, store } from "valdres"
const priceAtom = atom(100)
const taxAtom = atom(0.2)
const totalSelector = selector(get => get(priceAtom) * (1 + get(taxAtom)))
const root = store()
const child = root.scope("preview")
root.get(totalSelector) // 120
child.set(taxAtom, 0.25)
child.get(totalSelector) // 125 — uses child's tax, parent's price
root.get(totalSelector) // 120 — unchanged
```
## Families in scopes
Atom families work across scopes. A child scope inherits the parent's family
members but can add its own:
```ts
import { atomFamily, store } from "valdres"
const todoAtom = atomFamily()
const root = store()
const child = root.scope("draft")
root.set(todoAtom("a"), { title: "Buy milk", done: false })
child.get(todoAtom("a")) // { title: "Buy milk", done: false } — inherited
// Add a new item only in the child scope
child.set(todoAtom("b"), { title: "Draft todo", done: false })
root.get(todoAtom) // ["a"]
child.get(todoAtom) // ["a", "b"] — child sees both
```
### Deleting a member in a scope
`del()` removes the member from **this store's** membership. On a scope that is
a local removal, and the two read paths answer differently on purpose:
```ts
root.set(todoAtom("a"), { title: "Buy milk", done: false })
child.del(todoAtom("a"))
child.get(todoAtom) // [] — not one of the child's members
child.get(todoAtom("a")) // { title: "Buy milk" … } — still the parent's value
root.get(todoAtom) // ["a"] — the parent is untouched
```
A value read with no local value falls through the scope chain, exactly as it
does for any other atom — the scope said "not one of mine", not "gone
everywhere". On a root store there is nothing to fall through to, so a deleted
member reads its family default instead.
This is also why reverting a scope has to restore membership and not just
values: see [Reverting a scope](#reverting-a-scope) below.
## Subscriptions
Subscriptions within a scope react to changes in that scope's view of state:
```ts
const root = store()
const child = root.scope("child")
const countAtom = atom(0)
child.sub(countAtom, () => {
console.log("child sees:", child.get(countAtom))
})
root.set(countAtom, 1)
// logs: "child sees: 1" — parent update flows through
child.set(countAtom, 99)
// logs: "child sees: 99" — scoped update
root.set(countAtom, 2)
// nothing logged — child has shadowed this atom
```
## Transactions in scopes
Transactions work the same way inside scopes:
```ts
child.txn(({ set }) => {
set(nameAtom, "New name")
set(ageAtom, 25)
// Both updates are atomic within the scope
})
```
## Reverting a scope
`unset` drops one shadowed value so the atom re-inherits its parent's:
```ts
import { atom, atomFamily, store } from "valdres"
const nameAtom = atom("Alice")
const todoAtom = atomFamily(id => `todo:${id}`)
const root = store()
root.set(todoAtom("a"), "Buy milk")
const draft = root.scope("draft")
draft.set(nameAtom, "Bob")
draft.unset(nameAtom)
draft.get(nameAtom) // "Alice" — the parent's value again, and tracking it
```
`unsetAll()` does that for everything the scope owns, in a single commit:
```ts
draft.set(nameAtom, "Bob")
draft.set(todoAtom("b"), "Draft todo")
draft.unsetAll()
draft.get(nameAtom) // "Alice"
draft.get(todoAtom) // [todoAtom("a")] — the draft's own member is gone too
```
Family membership reverts in both directions: members the scope added leave its
`get(family)`, and members it deleted with `del()` come back.
The scope itself survives — this is the difference from `detach()`. Its id,
subscriptions, nested scopes, and any other handles on it all keep working, and
it starts shadowing again the moment you write to it. Reach for `unsetAll()`
when a scope's edits have been applied (or abandoned) but the scope stays on
screen; reach for `detach()` when the scope is done for good.
Every atom the scope shadowed notifies, exactly as `unset` does — including one
whose parent value happens to be identical, because the scope really did stop
owning it. Atoms it never shadowed are untouched.
### Reverting inside a transaction
A scope's own transaction can revert it directly:
```ts
draft.txn(txn => {
txn.unsetAll()
txn.set(nameAtom, "a fresh start")
})
```
More often the revert belongs to a commit the parent is driving — publishing a
draft, say — so the whole thing lands atomically and no subscriber sees the
scope snap back before the write that supersedes it:
```ts
const publishedName = atom("")
root.txn(txn => {
txn.set(
publishedName,
root.scope("draft", s => s.get(nameAtom)),
)
txn.scope("draft", scoped => scoped.unsetAll())
})
```
`txn.scope()` throws if the scope does not exist, so guard with `hasScope` when
a scope may never have been opened — from **inside** the transaction callback:
```ts
root.txn(txn => {
if (root.hasScope("draft")) {
txn.scope("draft", scoped => scoped.unsetAll())
}
})
```
Checking before `txn()` looks equivalent but is not on a `batchUpdates` store:
`txn()` flushes the pending batch before running your callback, and a subscriber
woken by that flush can detach the last lease on the scope you just checked for.
Inside the callback the flush has already happened.
`unsetAll()` is a scope operation — a root store has no parent to revert to, and
calling it there throws. It is typed that way too: `unsetAll` exists on
`ScopedStore` and on the transaction `scope()` hands you, not on `Store` or on a
root transaction.
## Cleanup
When you're done with a scope, call `detach()` to clean it up:
```ts
const child = root.scope("temp")
// ... use the scope ...
child.detach()
```
In framework integrations, cleanup happens automatically when the scope
component unmounts.
`detach()` releases **your** lease. The scope itself dies when its last lease
goes, so a holder cannot tell from its own `detach()` whether the scope survived
— `store.hasScope(scopeId)` answers that from the parent:
```ts
const first = root.scope("draft")
const second = root.scope("draft")
first.detach()
root.hasScope("draft") // true — second still holds a lease
second.detach()
root.hasScope("draft") // false — gone
```
### Releasing your own resources with a scope
If you keep anything alongside a scope — a cache, a subscription to something
external, a timer — register it with `onDispose`, which runs when the scope
actually dies: on its last `detach()`, or when an ancestor is disposed.
```ts
const draft = root.scope(changeSetRef)
draft.onDispose(() => cache.delete(changeSetRef))
```
Without it the only signal is inference on the next acquire, which cannot
distinguish a scope that survived from a new one that reuses the id — so state
keyed by the id outlives the scope it belonged to and leaks into its successor.
The store is already terminal inside the callback, so read anything you need
beforehand and close over it. `onDispose` is on every store, not just scopes: a
request/SSR root store releases its resources the same way.
## In React
Use the `Scope` component to create a scoped store for a subtree:
```tsx
import { Provider, Scope } from "valdres-react"
import { useValue } from "valdres-react"
function App() {
return (
)
}
```
Everything inside `` reads and writes to the scoped store. Components
outside continue using the parent store.
### Initializing scope state
Pass an `initialize` callback to set up initial values:
```tsx
{
txn.set(nameAtom, "Draft name")
txn.set(emailAtom, "draft@example.com")
}}
>
```
Or use the array format:
```tsx
[
[nameAtom, "Draft name"],
[emailAtom, "draft@example.com"],
]}
>
```
### Auto-generated scope IDs
If you omit `scopeId`, a unique ID is generated automatically:
```tsx
```
## Use cases
### Edit modal with cancel
Create a scope for the edit form. Edits stay in the scope; saving copies them to
the parent and reverts the scope, so the form is clean the next time it opens —
and both halves land in one commit:
```tsx
function EditModal({ userId }) {
const store = useStore()
const handleSave = () => {
store.txn(txn => {
txn.set(
userAtom(userId),
store.scope("edit", scoped => scoped.get(userAtom(userId))),
)
txn.scope("edit", scoped => scoped.unsetAll())
})
}
const handleCancel = () => {
// Throw the edits away without tearing the scope down.
store.scope("edit", scoped => scoped.unsetAll())
onClose()
}
return (
)
}
```
`useStore()` inside `` gives you the scope itself, so a "reset this form"
button in the form can call `store.unsetAll()` directly — cast the handle if
your adapter types it as a plain `Store`.
### Multi-tenant dashboard
Each tenant panel gets its own scope, sharing base configuration but with
independent data:
```tsx
function Dashboard({ tenants }) {
return (
{tenants.map(tenant => (
[
[tenantIdAtom, tenant.id],
[tenantNameAtom, tenant.name],
]}
>
))}
)
}
```
### Drag preview
Show a preview of what state will look like without committing:
```tsx
function DragPreview({ itemId, targetListId }) {
return (
)
}
```
## Performance
Scoped stores are optimized for minimal overhead:
- **No upfront copying** — values are resolved lazily by walking up the scope
chain
- **Selective propagation** — when a parent atom updates, the change only
propagates to scopes that haven't shadowed it
- **Reference counting** — scopes are cleaned up when no consumers remain
---
Source: https://valdres.dev/guides/transactions.md
# Transactions
Transactions let you update multiple atoms at once. Subscribers and selectors only re-evaluate after all updates are applied — never in an intermediate state.
## The problem
Without transactions, each `set` call immediately notifies subscribers:
```ts
import { atom, selector, store } from "valdres"
const firstName = atom("John")
const lastName = atom("Doe")
const fullName = selector(get => `${get(firstName)} ${get(lastName)}`)
const myStore = store()
// Two separate updates — subscribers fire twice
// After first set: fullName = "Jane Doe"
// After second set: fullName = "Jane Smith"
myStore.set(firstName, "Jane")
myStore.set(lastName, "Smith")
```
If a component is subscribed to `fullName`, it briefly shows "Jane Doe" before settling on "Jane Smith". That intermediate state may cause flickers or unnecessary work.
## The solution
Wrap related updates in `store.txn()`:
```ts
myStore.txn(({ set }) => {
set(firstName, "Jane")
set(lastName, "Smith")
// Nothing fires until here
})
// Now subscribers fire once with fullName = "Jane Smith"
```
## Synchronous callbacks
Transaction callbacks must be synchronous. Returning a Promise or other
thenable throws and aborts the automatic commit, because writes after an
`await` cannot be part of the same atomic commit. Perform asynchronous work
before the transaction, then apply its result synchronously:
```ts
const user = await fetchUser()
myStore.txn(({ set }) => {
set(userAtom, user)
set(statusAtom, "ready")
})
```
## Atomic lifecycle
Valdres owns the transaction lifecycle. The callback receives state operations
such as `get`, `set`, and `reset`, but no `commit()` method or backing store
data. Returning successfully commits once; throwing discards every staged write:
```ts
myStore.txn(({ set }) => {
set(statusAtom, "saving")
throw new Error("save failed")
})
// statusAtom was not changed
```
If an operation intentionally needs multiple publish points, use separate
`store.txn()` calls. Each call is an explicit atomic boundary.
## Updater functions
Inside a transaction, `set` works the same as outside — you can pass values or updater functions:
```ts
const countA = atom(0)
const countB = atom(0)
myStore.txn(({ set }) => {
set(countA, prev => prev + 1)
set(countB, prev => prev + 10)
})
```
As with `store.set`, a synchronous transaction write returns its staged value,
while a Promise or promise-returning updater returns a real `Promise`. The
transaction callback itself must remain synchronous—capture the returned Promise
if work outside the transaction needs to await settlement.
```ts
let settlement: Promise
myStore.txn(({ set }) => {
settlement = set(countA, Promise.resolve(10))
})
await settlement!
```
## When to use transactions
**Use transactions when:**
- Updating multiple related atoms that feed into the same selector
- Moving items between collections (remove from one, add to another)
- Resetting a form (clear all fields at once)
- Any operation where intermediate state would be wrong or confusing
**You don't need transactions when:**
- Updating a single atom
- Updates are unrelated and independent
- Intermediate states are acceptable
## Real-world example: drag and drop
When an item is dragged from one list to another, you need to remove it from the source and add it to the target atomically:
```ts
import { atom, atomFamily, store } from "valdres"
const listItemsAtom = atomFamily() // listId → itemId[]
const itemAtom = atomFamily() // itemId → item data
const myStore = store()
function moveItem(itemId, fromListId, toListId) {
myStore.txn(({ set }) => {
set(listItemsAtom(fromListId), ids =>
ids.filter(id => id !== itemId)
)
set(listItemsAtom(toListId), ids =>
[...ids, itemId]
)
})
// Components subscribed to either list update once
// The item is never "missing" from both lists
}
```
## Performance
Transactions aren't just about correctness — they're a performance optimization. Without them, a selector depending on 10 atoms would recompute 10 times during a bulk update. With a transaction, it recomputes once.
```ts
const atoms = Array.from({ length: 100 }, () => atom(0))
const sum = selector(get => atoms.reduce((acc, a) => acc + get(a), 0))
// Without txn: sum recomputes 100 times
atoms.forEach(a => myStore.set(a, 1))
// With txn: sum recomputes once
myStore.txn(({ set }) => {
atoms.forEach(a => set(a, 1))
})
```
---
Source: https://valdres.dev/guides/typescript.md
# TypeScript
Valdres is written in TypeScript and provides full type inference out of the box. You rarely need to write explicit type annotations.
## Atoms infer their type
```ts
import { atom } from "valdres"
const countAtom = atom(0) // Atom
const nameAtom = atom("hello") // Atom
const userAtom = atom(null) // Atom
```
When the default value is enough, TypeScript infers the type automatically. Use an explicit generic when you need a wider type than the default implies.
## Selectors infer from the getter
```ts
import { atom, selector } from "valdres"
const priceAtom = atom(100)
const taxRateAtom = atom(0.25)
// Selector — inferred from the return type
const totalSelector = selector(get => {
const price = get(priceAtom) // number
const rate = get(taxRateAtom) // number
return price * (1 + rate)
})
```
The `get` function is fully typed — it knows what type each atom or selector returns.
## Families are generic
```ts
import { atomFamily, selectorFamily } from "valdres"
type User = { id: string; name: string; email: string }
// AtomFamily — key is string, value is User
const userAtom = atomFamily()
// The returned atom is typed
const alice = userAtom("alice") // Atom
```
```ts
// SelectorFamily — key is string, value is string
const displayNameSelector = selectorFamily(id => get => {
const user = get(userAtom(id))
return user.name
})
```
## Store methods are typed
```ts
import { atom, store } from "valdres"
const myStore = store()
const countAtom = atom(0)
myStore.get(countAtom) // number
myStore.set(countAtom, 42) // OK
myStore.set(countAtom, "hello") // Type error!
myStore.set(countAtom, prev => prev + 1) // prev is number
```
## Async atoms
Async atoms resolve to their inner type:
```ts
type User = { id: string; name: string }
const userAtom = atom(async () => {
const res = await fetch("/api/user")
return res.json()
})
// In React: useValue returns User (not Promise)
const user = useValue(userAtom) // User
```
## React hooks are typed
All hooks infer types from the atom or selector passed in:
```ts
import { useAtom, useValue, useSetAtom } from "valdres-react"
const countAtom = atom(0)
const [count, setCount] = useAtom(countAtom) // [number, (v: number | (prev: number) => number) => void]
const value = useValue(countAtom) // number
const setter = useSetAtom(countAtom) // (v: number | (prev: number) => number) => void
```
---
Source: https://valdres.dev/guides/vs-jotai.md
# Valdres vs Jotai
Valdres was created due to performance issues encountered building an offline-first process model editor. First with Recoil and then with Jotai due to the apparent abandonment of the Recoil project.
If you are a current Jotai user and want to quickly test out Valdres, we have a compatibility package that mirrors the Jotai API. Just change your imports:
```tsx
// Before
import { atom, createStore } from "jotai"
// After
import { atom, createStore } from "@valdres-react/jotai"
```
## Similarities
### Storage
Jotai and Valdres have a similar approach to how atoms and selectors are stored internally. They both use WeakMap — if an atom or selector is no longer referenced it can be garbage collected.
## Differences
### React implementation
Jotai uses a combination of `useEffect` and `useReducer` while Valdres utilizes `useSyncExternalStore`, similar to the Zustand library. (The same developer has created both Zustand and Jotai.)
### atom + selector
Jotai has a single concept for both state and derived state. Valdres separates stored state (atoms) from derived/aggregated state (selectors), similar to Recoil. Based on our experience building an app with several hundred atoms and selectors, we see a clear benefit to the mental model and code readability.
### atomFamily / selectorFamily
In Jotai, `atomFamily` is a simple utility. In Valdres, `atomFamily` also has store-local membership: you can subscribe to the family and read its active members as an array. A `selectorFamily` is an identity-cached selector factory; read and subscribe to its individual members.
### Transactions
Recoil pioneered the ability to do transactions on state. Valdres brings this forward — you can batch multiple atom updates so subscribers only fire once. This is not an explicit part of Jotai.
---
Source: https://valdres.dev/guides/vs-recoil.md
# Valdres vs Recoil
Valdres takes heavy inspiration from Recoil's API design. If you're coming from Recoil, the concepts will feel familiar — atoms, selectors, families, and transactions all work similarly.
## Quick migrate
Change your imports to use the Recoil compatibility package:
```tsx
// Before
import { atom, selector } from "recoil"
// After
import { atom, selector } from "@valdres-react/recoil"
```
## Key differences
- **Actively maintained** — Recoil has been effectively abandoned by Meta. Valdres is actively developed.
- **Smaller bundle** — Valdres has a significantly smaller footprint.
- **No string keys** — Recoil requires unique string keys for every atom and selector. Valdres atoms and selectors are identified by reference, no keys needed.
- **WeakMap storage** — Atoms and selectors that are no longer referenced can be garbage collected.
- **Works outside React** — The core `valdres` package is framework-agnostic.
---
Source: https://valdres.dev/solid/createAtom.md
# createAtom
Signature
`createAtom(atom: Atom): [Accessor, SetterFn]`
valdres-solid
Subscribe to and update an atom's value
Returns a Solid accessor and a setter function for an atom. The accessor is reactive — any `createEffect` or component render that reads it will re-run when the atom changes.
## Usage
```tsx
import { atom } from "valdres"
import { createAtom } from "valdres-solid"
const countAtom = atom(0)
function Counter() {
const [count, setCount] = createAtom(countAtom)
return (
{count()}
)
}
```
## Returns
| Index | Type | Description |
| ----- | ------------- | ----------------------------------------------------- |
| `[0]` | `Accessor` | Reactive accessor — call it to read the current value |
| `[1]` | `SetterFn` | Function to update the atom's value |
## Updater function
The setter supports both direct values and updater functions:
```ts
setCount(42) // Set directly
setCount(prev => prev + 1) // Update based on previous value
```
> **Note**
>
>
> If you only need to read the value, use [createValue](https://valdres.dev/solid/createValue) instead. If you only need the setter, use [createSetAtom](https://valdres.dev/solid/createSetAtom) to avoid subscribing to changes.
## See also
- [createValue](https://valdres.dev/solid/createValue) — read-only accessor (no setter)
- [createSetAtom](https://valdres.dev/solid/createSetAtom) — write-only (no subscription)
- [createResetAtom](https://valdres.dev/solid/createResetAtom) — reset to default value
---
Source: https://valdres.dev/solid/createResetAtom.md
# createResetAtom
Signature
`createResetAtom(atom: Atom): () => void`
valdres-solid
Reset an atom to its default value
Returns a function that resets an atom back to its default value.
## Usage
```tsx
import { atom } from "valdres"
import { createAtom, createResetAtom } from "valdres-solid"
const countAtom = atom(0)
function Counter() {
const [count, setCount] = createAtom(countAtom)
const reset = createResetAtom(countAtom)
return (
{count()}
)
}
```
## See also
- [createAtom](https://valdres.dev/solid/createAtom) — read + write accessor
- [createSetAtom](https://valdres.dev/solid/createSetAtom) — write-only setter
---
Source: https://valdres.dev/solid/createSetAtom.md
# createSetAtom
Signature
`createSetAtom(atom: Atom): SetterFn`
valdres-solid
Write-only access to an atom
Returns a setter function for an atom without subscribing to changes. The component won't re-render when the atom updates.
## Usage
```tsx
import { atom } from "valdres"
import { createSetAtom } from "valdres-solid"
const countAtom = atom(0)
function IncrementButton() {
const setCount = createSetAtom(countAtom)
return
}
```
## See also
- [createAtom](https://valdres.dev/solid/createAtom) — read + write accessor
- [createResetAtom](https://valdres.dev/solid/createResetAtom) — reset to default value
---
Source: https://valdres.dev/solid/createTransaction.md
# createTransaction
Signature
`createTransaction(store?: Store): (callback: (txn: Transaction) => any) => any`
valdres-solid
Batch updates — subscribers fire once
Returns a function that runs a callback as a [transaction](https://valdres.dev/guides/transactions) on the current store: all updates apply atomically and subscribers fire once at the end. The callback receives `{ set, get, reset, del, unset }`.
## Usage
```tsx
import { atom } from "valdres"
import { createTransaction } from "valdres-solid"
const firstNameAtom = atom("")
const lastNameAtom = atom("")
function ResetForm() {
const txn = createTransaction()
const clear = () =>
txn(({ reset }) => {
reset(firstNameAtom)
reset(lastNameAtom)
})
return
}
```
Pass a store to target one explicitly: `createTransaction(myStore)`.
## See also
- [Transactions guide](https://valdres.dev/guides/transactions) — semantics, nesting, and performance
- [useStore](https://valdres.dev/solid/useStore) — access the current store
---
Source: https://valdres.dev/solid/createValue.md
# createValue
Signature
`createValue(state: Atom | Selector): Accessor`
valdres-solid
Read-only subscription to state
Returns a reactive Solid accessor for an atom or selector. Use this when you only need to read state.
## Usage
```tsx
import { atom, selector } from "valdres"
import { createValue } from "valdres-solid"
const nameAtom = atom("Valdres")
const greetingSelector = selector(get => `Hello, ${get(nameAtom)}!`)
function Greeting() {
const greeting = createValue(greetingSelector)
return
{greeting()}
}
```
## See also
- [createAtom](https://valdres.dev/solid/createAtom) — read + write accessor
- [createSetAtom](https://valdres.dev/solid/createSetAtom) — write-only setter
---
Source: https://valdres.dev/solid/useStore.md
# useStore
Signature
`useStore(): Store`
valdres-solid
Access the current store instance
Returns the current valdres store from the nearest `ValdresProvider`. Useful for imperative operations.
## Usage
```tsx
import { useStore } from "valdres-solid"
function Debug() {
const store = useStore()
const handleClick = () => {
console.log("Current:", store.get(myAtom))
}
return
}
```
## See also
- [ValdresProvider](https://valdres.dev/solid/ValdresProvider) — provide a store to the component tree
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/solid/ValdresProvider.md
# ValdresProviderSignature``valdres-solid
Provide a store to the component treeWraps a Solid component tree with a valdres store context.## Usage```tsx
import { ValdresProvider } from "valdres-solid"
function App() {
return (
)
}
```## With a custom store```tsx
import { store } from "valdres"
import { ValdresProvider } from "valdres-solid"
const myStore = store()
function App() {
return (
)
}
```## See also* [useStore](https://valdres.dev/solid/useStore) — access the store in components
* [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/solid/ValdresScope.md
# ValdresScope
Signature
``
valdres-solid
Create an isolated child store for a Solid subtree
Creates a scoped store that inherits state from the parent but can override values independently. Components inside the scope read and write to the scoped store.
## Usage
```tsx
import { ValdresProvider, ValdresScope } from "valdres-solid"
function App() {
return (
)
}
```
## Props
| Prop | Type | Description |
| ------------ | ---------------------------------- | ----------------------------------------------- |
| `scopeId` | `string` | Optional identifier. Auto-generated if omitted. |
| `initialize` | `(txn) => void \| [Atom, value][]` | Optional callback to set initial values. |
| `children` | `JSX.Element` | Components that will use the scoped store. |
## Initializing state
```tsx
{
txn.set(nameAtom, "Draft")
txn.set(emailAtom, "")
}}
>
```
## Cleanup
The scope is automatically cleaned up when the component is removed from the DOM.
## See also
- [Scoped Stores](https://valdres.dev/guides/scoped-stores) — full guide on scoped stores
- [ValdresProvider](https://valdres.dev/solid/ValdresProvider) — provide a store to your component tree
---
Source: https://valdres.dev/svelte/fromState.md
# fromState
Signature
`fromState(state: Atom | Selector, store?: Store): FromStateAtom | FromStateValue`
valdres-svelte
Reactive read/write box for an atom (read-only for selectors)
Bridges a valdres atom or selector into a Svelte 5 reactive box. Reading `.current` inside an effect — a template expression, `$derived`, `$effect` — subscribes to the state and re-runs that effect when it changes. For an atom the box is writable, so `bind:value` and `count.current++` just work; for a selector (or any read-only state) `.current` is read-only.
## Usage
```svelte
Count: {count.current}
```
The second `store` argument defaults to the store from [setValdresContext](https://valdres.dev/svelte/setValdresContext) / [scope](https://valdres.dev/svelte/scope), resolved via [getValdresContext](https://valdres.dev/svelte/getValdresContext). Because context is only available during component initialization, pass an explicit `store` to use the box in plain `.svelte.ts` module state or during SSR.
## Returns
For an **atom** (`FromStateAtom`):
| Member | Type | Description |
| --------- | -------------------------------------- | ------------------------------------------------------------------------- |
| `current` | `T` | Tracked read and write (`box.current = v`, `box.current++`, `bind:value`) |
| `update` | `(updater: (current: T) => T) => void` | Read-modify-write, mirroring `svelte/store`'s `Writable.update` |
| `reset` | `() => void` | Reset the atom to its default value |
For a **selector** (`FromStateValue`): a read-only `current`. Async selectors surface as `current: T | Promise` — see the async note below.
## Async selectors
Core erases asyncness, so `fromState(asyncSelector).current` is typed `T | Promise`. Consume it with Svelte's `{#await}` block, or reach for [resourceState](https://valdres.dev/svelte/resourceState) when you want `loading` / `error` flags:
```svelte
{#await user.current then u}
Hello {u.name}
{/await}
```
> **Lazy bootstrap**
>
>
> The box is built on Svelte's `createSubscriber` (the primitive behind `MediaQuery`), so the underlying subscription is lazy: it starts on the first effect that reads `.current`. A valdres `onMount`-driven atom — the [@valdres/browser-\*](https://valdres.dev/svelte/plugins/browser-online) packages — therefore bootstraps only once `.current` is read in the template or an effect. If a component reads the value solely from an event handler, start the subscription with a throwaway effect: `$effect(() => void box.current)`.
## See also
- [toStore](https://valdres.dev/svelte/toStore) — Svelte store-contract bridge for `$`-syntax
- [resourceState](https://valdres.dev/svelte/resourceState) — async selectors with `loading` / `error`
- [setValdresContext](https://valdres.dev/svelte/setValdresContext) — provide a store to the component tree
---
Source: https://valdres.dev/svelte/getValdresContext.md
# getValdresContext
Signature
`getValdresContext(): Store`
valdres-svelte
Read the current store from context
Returns the store set by the nearest [setValdresContext](https://valdres.dev/svelte/setValdresContext) / [scope](https://valdres.dev/svelte/scope) ancestor. Most of the time you don't need it — [fromState](https://valdres.dev/svelte/fromState), [toStore](https://valdres.dev/svelte/toStore), and [transaction](https://valdres.dev/svelte/transaction) resolve the context store on their own. Reach for it when you need direct `store.get` / `store.set` access.
## Usage
```svelte
```
> **Call during initialization**
>
>
> Svelte throws `lifecycle_outside_component` for `getContext` outside component initialization, so capture the store at the top level rather than inside an event handler. To run writes from a handler, use [transaction](https://valdres.dev/svelte/transaction), which captures the store for you.
## See also
- [setValdresContext](https://valdres.dev/svelte/setValdresContext) — provide the store
- [transaction](https://valdres.dev/svelte/transaction) — handler-safe transaction runner
---
Source: https://valdres.dev/svelte/resourceState.md
# resourceState
Signature
`resourceState(selector: Selector, store?: Store): ResourceState`
valdres-svelte
Async selector with loading and error state
Consumes a possibly-async selector as a reactive `{ current, loading, error }` box. Core erases asyncness, so `fromState(sel).current` may be `T | Promise`; `resourceState` does the runtime promise detection for you and tracks settlement. While pending, `loading` is `true` and `current` is `undefined`; on resolve, `current` holds the value; on reject, `error` holds the reason. A dependency change re-enters the pending state.
## Usage
```svelte
{#if user.loading}
Loading…
{:else if user.error}
Failed: {String(user.error)}
{:else}
Hello {user.current?.name}
{/if}
```
When you'd rather `await` than branch on flags, [fromState](https://valdres.dev/svelte/fromState) plus Svelte's `{#await}` block works directly on the `T | Promise` value (`fromState(sel).current`, not the `resourceState` box above):
```svelte
{#await user.current then u}
Hello {u.name}
{/await}
```
## Returns
| Member | Type | Description |
| --------- | ---------------- | ------------------------------------------------------- |
| `current` | `T \| undefined` | Resolved value, or `undefined` while pending or errored |
| `loading` | `boolean` | `true` while the selector's promise is pending |
| `error` | `unknown` | The rejection reason, if the promise rejected |
## See also
- [fromState](https://valdres.dev/svelte/fromState) — reactive box; `{#await}` works on its `.current`
- [toStore](https://valdres.dev/svelte/toStore) — Svelte store-contract bridge
---
Source: https://valdres.dev/svelte/scope.md
# scope
Signature
`scope(scopeId?: string, options?: ScopeOptions): Store`
valdres-svelte
Scoped child store for a component subtree
Creates a scoped child store layered over the parent for a subtree, and exposes it to descendants via context. Reuses an existing scope of the same `scopeId` if one is already in the tree; otherwise it creates one and detaches it automatically when the owning component is destroyed. Descendants reading via [fromState](https://valdres.dev/svelte/fromState) / [toStore](https://valdres.dev/svelte/toStore) resolve the scoped store.
## Usage
```svelte
Scoped count: {count.current}
```
The optional `initialize` callback seeds the scoped store inside a transaction when the scope is created — the same `InitializeCallback` contract used by [setValdresContext](https://valdres.dev/svelte/setValdresContext). It must be called during component initialization (it reads context and registers an `onDestroy` cleanup).
## See also
- [setValdresContext](https://valdres.dev/svelte/setValdresContext) — provide the root store
- [getValdresContext](https://valdres.dev/svelte/getValdresContext) — read the current (scoped) store
---
Source: https://valdres.dev/svelte/setValdresContext.md
# setValdresContext
Signature
`setValdresContext(storeOrOptions?: Store | SetValdresContextOptions): Store`
valdres-svelte
Provide a store to the component tree
Creates (or adopts) a valdres store and exposes it to descendants via Svelte context — the root of the adapter's provider tier. Call it once near the root. With no argument it creates `store({ batchUpdates: true })` for the component tree, which on the server means one store per request — the canonical SvelteKit pattern that avoids a module-level shared-store leak. Returns the store now in context.
## Usage
```svelte
{@render children()}
```
Descendants then read state with [fromState](https://valdres.dev/svelte/fromState) / [toStore](https://valdres.dev/svelte/toStore) and no explicit store argument.
## Options
Pass an options object to seed the store:
| Option | Type | Description |
| ---------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `store` | `Store` | Use this store instead of auto-creating one (warns if not created with `batchUpdates: true`) |
| `initialize` | `InitializeCallback` | Seed the store inside a transaction before it's exposed |
| `hydrate` | `DehydratedState` | Apply a `dehydrate(store)` payload to the fresh store |
| `hydrateOptions` | `HydrateOptions` | Forwarded to core `hydrate` (`{ invalid: "throw" \| "skip" }`) |
When both `initialize` and `hydrate` are given, `initialize` runs first so transferred values win.
## SvelteKit (SSR)
Load data on the server, then map it to atoms with `initialize`. Because `initialize` runs on both the server render and client hydration, the atoms hold the right values in both passes — no custom serializer needed.
```ts
// +layout.server.ts
export const load = async () => {
return { count: 7 } // plain, serializable
}
```
```svelte
{@render children()}
```
If your `load` data is itself a `dehydrate(store)` payload (e.g. from an API that ran a server-side store), pass it as `hydrate` instead. Atoms carrying a codec schema round-trip `BigInt` / `Date` / `Map` / `Set` over plain JSON automatically.
## See also
- [getValdresContext](https://valdres.dev/svelte/getValdresContext) — read the store from context
- [scope](https://valdres.dev/svelte/scope) — scoped child store for a subtree
---
Source: https://valdres.dev/svelte/toStore.md
# toStore
Signature
`toStore(state: Atom | Selector, store?: Store): Writable | Readable`
valdres-svelte
Svelte store contract for $-syntax
Bridges a valdres atom or selector into Svelte's store contract, for `$`-prefix auto-subscription and `bind:value={$count$}`. An atom yields a `Writable` (`subscribe` / `set` / `update`, all delegating to the store); a selector (or any read-only state) yields a read-only `Readable`. Prefer [fromState](https://valdres.dev/svelte/fromState) for new code — `toStore` exists for `$`-syntax interop.
## Usage
```svelte
Count: {$count$}
```
The `store` argument is optional and defaults to the context store (via [getValdresContext](https://valdres.dev/svelte/getValdresContext)), so it can be omitted during component initialization — consistent with every other primitive.
## See also
- [fromState](https://valdres.dev/svelte/fromState) — rune-based reactive box (preferred)
- [setValdresContext](https://valdres.dev/svelte/setValdresContext) — provide a store to the component tree
---
Source: https://valdres.dev/svelte/transaction.md
# transaction
Signature
`transaction(store?: Store): (callback: TransactionFn, name?: string) => void`
valdres-svelte
Batch multiple writes into a single commit
Returns a transaction runner bound to the current context store, captured at component initialization. That capture is what makes it safe to call from an event handler — Svelte throws `lifecycle_outside_component` if you call `getContext` inside a handler. Writes inside the callback commit together, so subscribers and selectors observe one atomic update. Forwards core's optional devtools `name`.
Callbacks must be synchronous. Returning a Promise or other thenable throws
without automatically committing staged writes; await asynchronous work before
calling the transaction runner.
## Usage
```svelte
```
Pass an explicit `store` to bind the runner to a specific store instead of the context store.
## See also
- [setValdresContext](https://valdres.dev/svelte/setValdresContext) — provide the store the runner binds to
- [scope](https://valdres.dev/svelte/scope) — scoped child store
---
Source: https://valdres.dev/vue/createValdres.md
# createValdres
Signature
`createValdres(options?: ValdresPluginOptions): Plugin`
valdres-vue
Provide a store to your Vue app
Creates a Vue plugin that provides a valdres store to all components via Vue's provide/inject system.
## Usage
```ts
import { createApp } from "vue"
import { createValdres } from "valdres-vue"
import App from "./App.vue"
const app = createApp(App)
app.use(createValdres())
app.mount("#app")
```
## With a custom store
```ts
import { store } from "valdres"
import { createValdres } from "valdres-vue"
const myStore = store()
app.use(createValdres({ store: myStore }))
```
## See also
- [useStore](https://valdres.dev/vue/useStore) — access the store in components
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/vue/useAtom.md
# useAtom
Signature
`useAtom(atom: Atom): Ref`
valdres-vue
Subscribe to and update an atom's value
Returns a reactive `Ref` that stays in sync with the atom. Writing to the ref updates the atom, and atom changes update the ref.
## Usage
```vue
{{ count }}
```
## Two-way binding
Since `useAtom` returns a `Ref`, it works with `v-model`:
```vue
```
## See also
- [useValue](https://valdres.dev/vue/useValue) — read-only composable
- [useSetAtom](https://valdres.dev/vue/useSetAtom) — write-only composable
- [useResetAtom](https://valdres.dev/vue/useResetAtom) — reset to default value
---
Source: https://valdres.dev/vue/useResetAtom.md
# useResetAtom
Signature
`useResetAtom(atom: Atom): () => void`
valdres-vue
Reset an atom to its default value
Returns a function that resets an atom back to its default value.
## Usage
```vue
{{ count }}
```
## See also
- [useAtom](https://valdres.dev/vue/useAtom) — read + write composable
- [useSetAtom](https://valdres.dev/vue/useSetAtom) — write-only composable
---
Source: https://valdres.dev/vue/useSetAtom.md
# useSetAtom
Signature
`useSetAtom(atom: Atom): SetterFn`
valdres-vue
Write-only access to an atom
Returns a setter function for an atom without subscribing to its value. Use this when a component only needs to trigger updates.
## Usage
```vue
```
## See also
- [useAtom](https://valdres.dev/vue/useAtom) — read + write composable
- [useResetAtom](https://valdres.dev/vue/useResetAtom) — reset to default value
---
Source: https://valdres.dev/vue/useStore.md
# useStore
Signature
`useStore(): Store`
valdres-vue
Access the current store instance
Returns the current valdres store from the Vue provide/inject context. Useful for imperative operations.
## Usage
```vue
```
## Transactions
Access the store to perform batched updates:
```vue
```
## See also
- [createValdres](https://valdres.dev/vue/createValdres) — setup the Vue plugin
- [store](https://valdres.dev/valdres/store) — create a store instance
---
Source: https://valdres.dev/vue/useTransaction.md
# useTransaction
Signature
`useTransaction(store?: Store): (callback: (txn: Transaction) => any) => any`
valdres-vue
Batch updates — subscribers fire once
Returns a function that runs a callback as a [transaction](https://valdres.dev/guides/transactions) on the current store: all updates apply atomically and subscribers fire once at the end. The callback receives `{ set, get, reset, del, unset }`.
## Usage
```vue
```
Pass a store to target one explicitly: `useTransaction(myStore)`.
## See also
- [Transactions guide](https://valdres.dev/guides/transactions) — semantics, nesting, and performance
- [useStore](https://valdres.dev/vue/useStore) — access the current store
---
Source: https://valdres.dev/vue/useValue.md
# useValue
Signature
`useValue(state: Atom | Selector): Ref`
valdres-vue
Read-only subscription to state
A read-only composable that returns a reactive `Ref` for an atom or selector. The ref updates whenever the underlying state changes.
## Usage
```vue
{{ greeting }}
```
## See also
- [useAtom](https://valdres.dev/vue/useAtom) — read + write composable
- [useSetAtom](https://valdres.dev/vue/useSetAtom) — write-only composable
---
Source: https://valdres.dev/vue/ValdresScope.md
# ValdresScope
Signature
``
valdres-vue
Create an isolated child store for a Vue subtree
Creates a scoped store that inherits state from the parent but can override values independently. Components inside the scope read and write to the scoped store.
## Usage
```vue
```
## Props
| Prop | Type | Description |
| ------------ | ---------------------------------- | ----------------------------------------------- |
| `scopeId` | `string` | Optional identifier. Auto-generated if omitted. |
| `initialize` | `(txn) => void \| [Atom, value][]` | Optional callback to set initial values. |
## Initializing state
```vue
```
## Cleanup
The scope is automatically cleaned up when the component is destroyed.
## See also
- [Scoped Stores](https://valdres.dev/guides/scoped-stores) — full guide on scoped stores
- [createValdres](https://valdres.dev/vue/createValdres) — provide a store to your component tree
---