---
title: "External stores"
description: "Read a Zustand or Redux store as a signal, per host or through context."
order: 6
---

import { ExternalStoreCart } from '@/components/external-store-cart';

export const config = {
	dependencies: {
		components: [ExternalStoreCart],
	},
};

# External stores

Use `@fromStore(store, select)` on a host, or `fromExternalStore(...)` as the signal, when the source of truth is **already** a Zustand, Redux, or `useSyncExternalStore` store. `createStore(...)` is the right choice when Radiant owns the data.

You need this when several things write the same cart, session, or feature flag: a checkout form, analytics, maybe a React island, and a Radiant badge on the header. Copying `store.getState()` into `@state` on every dispatch re-renders the whole host. The store stays in charge of writes. The host binds one slice.

<ExternalStoreCart />

The count patches in place (`this.$.count`). The list re-renders because its shape changed. **Add mug** and **Add lamp** call `cartStore.setState`. They never write a Radiant field.

## Why not @state, and why not createStore?

| You have | Use |
| --- | --- |
| State that belongs to this host | `@state` / `@prop` |
| Nested data Radiant owns | `createStore(...)` as a host member |
| A store other code already writes | `@fromStore(...)` / `fromExternalStore(...)` |

`fromExternalStore` is read-only. There is no `.set()`. Dispatch, `setState`, or the store's actions stay on the store.

## API

```ts
import { fromExternalStore } from '@ecopages/signals';

const count = fromExternalStore(store, (state) => state.items.length);
```

`store` is anything with `subscribe` and either `getSnapshot` (the React contract) or `getState` (Zustand and Redux). An optional `getServerSnapshot` is the value until the signal first subscribes to the store, and never after. The third argument takes `equals`, as `state(...)` does.

On a host, [@fromStore](/docs/decorators/from-store) is the field:

```tsx
@customElement('cart-badge')
class CartBadge extends RadiantElement<{ count: number }> {
	@fromStore(cartStore, (state) => state.items.length)
	count!: number;

	override render() {
		return <span>{this.$.count}</span>;
	}
}
```

The host subscribes to the store only while it is connected, for change reports, `@bindTo` and the `this.$` bindings in its view alike: it subscribes on connect, releases the store on disconnect, and subscribes again on reconnect, when a binding catches up with a write made while the host was detached. Server rendering reads `getServerSnapshot()` (or the live snapshot when there is none) and never subscribes, on an element or a controller.

`select` runs once per snapshot: a notification that leaves the snapshot the same object does not run it. A selected value that is `Object.is` equal to the previous one does not notify, so return a slice of the state (`state.items`, a count). A selector that builds a new object or array notifies on every store change; pass `{ equals }` to compare it yourself. While subscribed, `get()` reads a snapshot the store has not notified yet, so a computed over two signals of one store never mixes two snapshots. An error thrown by `select` is rethrown by `get()`, not into the store's listeners.

## Through context

Provide the store object (its identity stays stable). Each descendant selects the slice it uses. `@contextSelector` is the wrong tool here: it reacts when the **context value** is replaced, and a Zustand store is not replaced on `setState`.

```tsx
const cartContext = createContext<typeof cartStore>(Symbol('cart'));

@customElement('shop-root')
class ShopRoot extends RadiantElement {
	@provideContext({ context: cartContext, initialValue: cartStore })
	cart!: ContextProvider<typeof cartContext>;
}

@customElement('cart-badge')
class CartBadge extends RadiantElement<{ count: number }> {
	@onContextUpdate({ context: cartContext })
	onCart(store: typeof cartStore) {
		this.registerReactiveMember(
			'count',
			fromExternalStore(store, (state) => state.items.length),
		);
	}

	override render() {
		return <span>{this.$.count}</span>;
	}
}
```

A sibling that selects `state.user` does not update when the cart items change.

## Recipes

- [Zustand store](/docs/examples/zustand-store) — `create()` from Zustand, a cart badge and a list
- [Redux store](/docs/examples/redux-store) — `configureStore()`, two hosts, each on one slice

## Server snapshot and hydration

Pass `getServerSnapshot` when the live snapshot cannot be read on the server (it reads `localStorage` or `matchMedia`) or holds other data there. Server rendering paints from it and never calls `getSnapshot` or `subscribe`. On the client, `get()` returns it until the signal first subscribes: a host subscribes when it connects, before it hydrates or renders, so the client view shows the live snapshot, and so does every read after that, also once the host disconnects.

```ts
fromExternalStore({
	subscribe: store.subscribe,
	getSnapshot: () => store.getState(),
	getServerSnapshot: () => serverCart,
}, (state) => state.items.length);
```
