jotai-scope

👻🔭 Isolate Jotai atoms with scope

Install

npm install jotai-scope

ScopeProvider

While Jotai's Provider allows to scope Jotai's store under a subtree, we can't use the store above the tree within the subtree.

A workaround is to use store option in useAtom and other hooks.

Instead of specifying the store option, <ScopeProvider> lets you reuse the same atoms in different parts of the React tree without sharing state while still being able to read other atoms from the parent store.

At‑a‑glance

• Scopes are opt‑in. Only atoms listed in atoms or atomFamilies are explicitly scoped.
• Unscoped derived atoms can read both unscoped and scoped atoms.
• Scoped derived atoms implicitly scope their atom dependencies. When you scope a derived atom, every atom it touches (recursively) is scoped automatically, but only when read by the derived atom. Outside the derived atom, it continues to be unscoped.
• Nested lookup. If a scope can’t find the atom in the current scope, it inherits from the nearest parent scope, up to the nearest store.
• Scoping works for both reading from atoms and writing to atoms.

Quick Start

1import { Provider, atom, useAtom, useAtomValue } from 'jotai'
2import { ScopeProvider } from 'jotai-scope'

1 · Isolating a counter

1const countAtom = atom(0)
2const doubledAtom = atom((get) => get(countAtom) * 2)
3
4function Counter() {
5  const [count, setCount] = useAtom(countAtom)
6  const doubled = useAtomValue(doubledAtom)
7  return (
8    <>
9      <button onClick={() => setCount((c) => c + 1)}>+1</button>
10      <span>{count} → {doubled}</span>
11    </>
12  )
13}
14
15export default function App() {
16  return (
17    <Provider>
18      <Counter /> {/* doubledAtom uses the parent store */}
19      <ScopeProvider atoms={[doubledAtom]}>
20        <Counter /> {/* doubledAtom is scoped */}
21      </ScopeProvider>
22    </Provider>
23  )
24}

The second counter owns a private doubledAtom and a private countAtom because doubledAtom is scoped.

2 · Nested scopes

1<ScopeProvider atoms={[countAtom]} name="S1">
2  <Counter />         {/* countAtom is read from S1 */}
3  <ScopeProvider atoms={[nameAtom]} name="S2">
4    <Counter />       {/* countAtom is read from S1 & nameAtom is read from S2 */}
5  </ScopeProvider>
6</ScopeProvider>

• Outer scope (S1) isolates countAtom.
• Inner scope (S2) isolates nameAtom, then looks up the tree and finds countAtom in S1.

3 · Providing default values

1<ScopeProvider atoms={[[countAtom, 42]]}>
2  <Counter />   {/* starts at 42 inside this scope */}
3</ScopeProvider>

Mix tuples and plain atoms as needed: atoms={[[countAtom, 1], anotherAtom]}.

4 · Scoping an atomFamily

1import { atom, atomFamily, useAtom } from 'jotai'
2import { ScopeProvider } from 'jotai-scope'
3
4const itemFamily = atomFamily((id: number) => atom(id))
5
6<Component />     {/* Unscoped items */}
7<ScopeProvider atomFamilies={[itemFamily]}>
8  <Component />   {/* Isolated items */}
9</ScopeProvider>
10

Inside the <ScopeProvider> every itemFamily(id) call resolves to a scoped copy, so items rendered inside the provider are independent from the global ones and from any sibling scopes.

A helpful syntax for describing nested scopes

a, b, c(a + b), d(a + c)
S1[a]:    a1, b0, c0(a1 + b0), d0(a1 + c0(a1 + b0))
S2[c, d]: a1, b0, c2(a2 + b2), d2(a2 + c2(a2 + b2))

Above:

• Scope S1 is the first scope under the store provider (S0). S1 scopes a, so a1 refers to the scoped a in S1.
• c is a derived atom. c reads a and b. In S1, c is not scoped so it reads a1 and b0 from S1.
• c is scoped in S2, so it reads a from S2 and b from S2. This is because atom dependencies of scoped atoms are implicitly scoped.
• Outside c and d in S2, a and b still inherit from S1.
• c and d are both scoped in S2, so they both read a2. Implicit dependencies are shared across scoped atoms in the same scope so a2 in c2 and a2 in d2 are the same atom.

API

1interface ScopeProviderProps {
2  atoms?: (Atom<any> | [WritableAtom<any, any[], any>, any])[]
3  atomFamilies?: AtomFamily<any, any>[]
4  children: React.ReactNode
5  name?: string
6} | {
7  scope: ScopedStore
8  children: React.ReactNode
9}

Caveats

• Avoid side effects inside atom read—it may run multiple times per scope. For async atoms, use an abort controller. The extra renders are a known limitation and solutions are being researched. If you are interested in helping, please join the discussion.

1import { createScope, ScopeProvider } from 'jotai-scope'
2
3const parentStore = createStore()
4const scopedStore = createScope({
5  parentStore,
6  atomSet: new Set([atomA, atomB]),
7  atomFamilySet: new Set([atomFamilyA, atomFamilyB]),
8})
9
10function Component() {
11  return (
12    <ScopeProvider scope={scopedStore}>
13      <YourComponent />
14    </ScopeProvider>
15  )
16}

1const parentStore = createStore()
2const scope1 = createScope({
3  parentStore,
4  atomSet: new Set([atomA, atomB]),
5  atomFamilySet: new Set([atomFamilyA, atomFamilyB]),
6  scopeName: 'level1',
7})
8const scope2 = createScope({
9  parentStore: scope1,
10  atomSet: new Set([atomC, atomD]),
11  scopeName: 'level2',
12})

1import { createIsolation } from 'jotai-scope'
2
3const { Provider, useStore, useAtom, useAtomValue, useSetAtom } =
4  createIsolation()
5
6function Library() {
7  return (
8    <Provider>
9      <LibraryComponent />
10    </Provider>
11  )
12}