# jotai-scope

> 👻🔭

Latest version **0.12.2** (published 2026-08-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install jotai-scope
pnpm add jotai-scope
yarn add jotai-scope
bun add jotai-scope
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.12.2 |
| Published | 2026-08-13 |
| First published | 2023-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.0.0 |
| Dependencies | 0 |
| Unpacked size | 139.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 86 |
| Author | Daishi Kato |
| Maintainers | daishi, dmaskasky |
| Keywords | jotai, react, scope |

## Links

- npm: https://www.npmjs.com/package/jotai-scope
- Repository: https://github.com/jotaijs/jotai-scope
- Homepage: https://jotai.org/docs/extensions/scope
- Issues: https://github.com/jotaijs/jotai-scope/issues
- npm.io page: https://npm.io/package/jotai-scope

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.12.2 (latest) — 2026-08-13
- 0.12.1 — 2026-07-21
- 0.12.0 — 2026-07-21
- 0.11.0 — 2026-05-13
- 0.10.0 — 2025-12-10
- 0.9.7 — 2025-10-31
- 0.9.6 — 2025-10-30
- 0.9.5 — 2025-10-07
- 0.9.4 — 2025-09-10
- 0.9.3 — 2025-07-17
- 0.9.2 — 2025-07-17
- 0.9.1 — 2025-07-17
- 0.9.0 — 2025-07-17
- 0.8.3 — 2025-07-15
- 0.8.2 — 2025-07-12
- … 20 more at https://npm.io/package/jotai-scope/versions

## README

# 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

```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 (
    <>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
      <span>{count} → {doubled}</span>
    </>
  )
}

export default function App() {
  return (
    <Provider>
      <Counter /> {/* doubledAtom uses the parent store */}
      <ScopeProvider atoms={[doubledAtom]}>
        <Counter /> {/* doubledAtom is scoped */}
      </ScopeProvider>
    </Provider>
  )
}
```

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

**2 · Nested scopes**

```tsx
<ScopeProvider atoms={[countAtom]} name="S1">
  <Counter />         {/* countAtom is read from S1 */}
  <ScopeProvider atoms={[nameAtom]} name="S2">
    <Counter />       {/* countAtom is read from S1 & nameAtom is read from S2 */}
  </ScopeProvider>
</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**

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

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))

<Component />     {/* Unscoped items */}
<ScopeProvider atomFamilies={[itemFamily]}>
  <Component />   {/* Isolated items */}
</ScopeProvider>

```

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

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

### 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](https://github.com/jotaijs/jotai-scope/issues/25).


<Stackblitz id="vitejs-vite-ctcuhj" file="src%2FApp.tsx" />

## 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 (
    <ScopeProvider scope={scopedStore}>
      <YourComponent />
    </ScopeProvider>
  )
}
```

### Nesting Scopes
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 (
    <Provider>
      <LibraryComponent />
    </Provider>
  )
}
```

---
_Source: https://npm.io/package/jotai-scope · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._