jotai-scope

👻🔭 Isolate Jotai atoms with scope

$3

``
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, 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.

$3

* 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.

$3

`tsx
import { Provider, atom, useAtom, useAtomValue } from 'jotai'
import { ScopeProvider } from 'jotai-scope'
`

1 · Isolating a counter

`tsx
const countAtom = atom(0)
const doubledAtom = atom((get) => get(countAtom) * 2)

function Counter() {
const [count, setCount] = useAtom(countAtom)
const doubled = useAtomValue(doubledAtom)
return (
<>
setCount((c) => c + 1)}>+1
{count} → {doubled}

)
}

export default function App() {
return (

{/ doubledAtom uses the parent store /}

{/ doubledAtom is scoped /}


)
}
`

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

2 · Nested scopes

`tsx

{/ countAtom is read from S1 /}

{/ countAtom is read from S1 & nameAtom is read from S2 /}


`

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

3 · Providing default values

`tsx

{/ starts at 42 inside this scope /}

`

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

4 · Scoping an atomFamily

`tsx
import { atom, atomFamily, useAtom } from 'jotai'
import { ScopeProvider } from 'jotai-scope'

const itemFamily = atomFamily((id: number) => atom(id))

{/ Unscoped items /}

{/ Isolated items /}


`

Inside the 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.

$3

`ts
interface ScopeProviderProps {
atoms?: (Atom | [WritableAtom, any])[]
atomFamilies?: AtomFamily[]
children: React.ReactNode
name?: string
} | {
scope: Store
children: React.ReactNode
}
`

$3

* 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.




createScope

createScope is a low-level API that allows you to create a scoped store
from a parent store. It is useful when you want to create a scope
outside of React.

`tsx
import { createScope, ScopeProvider } from 'jotai-scope'

const parentStore = createStore()
const scopedStore = createScope({
parentStore,
atomSet: new Set([atomA, atomB]),
atomFamilySet: new Set([atomFamilyA, atomFamilyB]),
})

function Component() {
return (



)
}
`

$3


You can create a scope from another scope.
`tsx
const parentStore = createStore()
const scope1 = createScope({
parentStore,
atomSet: new Set([atomA, atomB]),
atomFamilySet: new Set([atomFamilyA, atomFamilyB]),
scopeName: 'level1',
})
const scope2 = createScope({
parentStore: scope1,
atomSet: new Set([atomC, atomD]),
scopeName: 'level2',
})
`

createIsolation

Both Jotai's Provider and jotai-scope's scoped provider
are still using global contexts.

If you are developing a library that depends on Jotai and
the library user may use Jotai separately in their apps,
they can share the same context. This can be troublesome
because they point to unexpected Jotai stores.

To avoid conflicting the contexts, a utility function called createIsolation is exported from jotai-scope.

`tsx
import { createIsolation } from 'jotai-scope'

const { Provider, ScopeProvider, useStore, useAtom, useAtomValue, useSetAtom } =
createIsolation()

function Library() {
return (



)
}
``