([
{ id: 1, title: '見積もりを出す', done: false },
{ id: 2, title: '請求書を送る', done: false },
])
// 派生atom：数値や文字列を返すなら、値が同じとき購読者は再レンダーしない
const remainingAtom = atom((get) => get(todosAtom).filter((t) => !t.done).length)
// 配列を返す派生atomは毎回新しい配列になるので、中身が同じでも再レンダーする
const activeIdsAtom = atom((get) => get(todosAtom).filter((t) => !t.done).map((t) => t.id))
// selectAtom：第3引数の比較関数で「中身が同じなら更新しない」と指定できる
const sameIds = (a: number[], b: number[]) => a.length === b.length && a.every((v, i) => v === b[i])
const activeIdsSelectedAtom = selectAtom(
todosAtom,
(todos) => todos.filter((t) => !t.done).map((t) => t.id),
sameIds,
)
// splitAtom：配列を要素ごとの atom に分ける（第2引数は要素を識別するキー）
const todoAtomsAtom = splitAtom(todosAtom, (todo) => todo.id)
export function Remaining() {
return 残り {useAtomValue(remainingAtom)} 件
}
export function ActiveIds() {
return {useAtomValue(activeIdsAtom).join(',')}
}
export function ActiveIdsSelected() {
return {useAtomValue(activeIdsSelectedAtom).join(',')}
}
function TodoItem({ todoAtom }: { todoAtom: PrimitiveAtom }) {
const todo = useAtomValue(todoAtom)
const setTodo = useSetAtom(todoAtom)
return (
)
}
export function TodoList() {
const todoAtoms = useAtomValue(todoAtomsAtom)
return todoAtoms.map((a) => )
}
```
これらを並べ、2件目のタイトルを書き換えたときと1件目をクリックしたときの再レンダーを数えました（jotai 3.0.1・React 19.3.1・jsdom）。
| コンポーネント（読むatom） | 2件目の改名 | 1件目の完了 |
| ----------------------------- | ------- | ------- |
| Remaining（件数の派生atom） | 再レンダーなし | 再レンダー |
| ActiveIds（配列の派生atom） | 再レンダー | 再レンダー |
| ActiveIdsSelected（selectAtom） | 再レンダーなし | 再レンダー |
| TodoList（splitAtom） | 再レンダーなし | 再レンダーなし |
| TodoItem 1件目 | 再レンダーなし | 再レンダー |
| TodoItem 2件目 | 再レンダー | 再レンダーなし |
派生atomの値は `Object.is` で比べられるので、件数のような数値や文字列を返すなら、元の配列が変わっても値が同じ限り再レンダーは起きません。この例の activeIdsAtom は filter と map で計算のたびに新しい配列を作るため、未完了の ID が 1,2 のままでも改名だけで再レンダーされました。ここで selectAtom の第3引数に要素ごとに比べる関数を渡すと、中身が同じ間は更新されなくなります。
splitAtom は配列の要素ごとに atom を作ります。1件目をクリックしたとき再レンダーされたのはその TodoItem だけで、TodoList も2件目も描画されませんでした。TodoItem を `memo` で包まなくてもこうなります。第2引数の `(todo) => todo.id` は要素と atom を ID で結び付ける関数で、削除や並べ替えで位置がずれても対応が保たれます。要素の削除は、splitAtom が返す atom に `{ type: 'remove', atom }` を書き込んで行えます。深いオブジェクトの一部を読み書きする jotai-optics の `focusAtom` もありますが、latest は2024年5月の 0.4.0 で止まっています。新規に組むなら、まず atom を小さく分けて持てないかを考えてください。
## 非同期atomとSuspense・unwrapの使い分け
読み取り関数が Promise を返すと非同期atomになります。useAtomValue で読むと、React 19 では `React.use()` で Promise を読み、解決するまでコンポーネントがサスペンドします（React 18 では従来の実装に切り替わります）。読み取り関数の第2引数で受け取る `signal` は AbortSignal で、依存する atom が変わって再計算が始まる前に、前の処理へ中断が通知されます。
```
import { Suspense } from 'react'
import { atom, useAtom, useAtomValue } from 'jotai'
import { unwrap } from 'jotai/utils'
type User = { id: number; name: string }
export const userIdAtom = atom(1)
// 依存する userIdAtom が変わると、再計算の前に前のリクエストへ中断が通知される
export const userAtom = atom(async (get, { signal }): Promise => {
const res = await fetch(`https://jsonplaceholder.typicode.com/users/${get(userIdAtom)}`, { signal })
if (!res.ok) throw new Error(`HTTP ${res.status}`)
return res.json()
})
function UserName() {
const user = useAtomValue(userAtom) // 解決するまでサスペンドする
return {user.name}
}
// サスペンドさせたくない箇所は unwrap で「読み込み中は null」に変換する
const userOrNullAtom = unwrap(userAtom, () => null)
function UserBadge() {
const user = useAtomValue(userOrNullAtom)
return {user ? user.name : '読み込み中…'}
}
export default function Profile() {
const [id, setId] = useAtom(userIdAtom)
return (
<>
読み込み中…}>
)
}
```
サスペンドさせたくない箇所には `unwrap` を使います。上の `userOrNullAtom` は、Promise が解決するまで第2引数の関数が返す値（ここでは null）を返し、解決後にユーザーを返します。v2 で読み込み状態の分岐に使われていた `loadable` は v3 で削除され、[公式の移行ガイド](https://github.com/pmndrs/jotai/blob/v3.0.1/docs/guides/migrating-to-v3.mdx)は unwrap での置き換えを案内しています。ガイドには loadable と同じ `{ state: 'loading' | 'hasData' | 'hasError' }` を返す実装例も載っています。
Promise が reject されたときは、Suspense で待つ書き方でも unwrap でもエラーがそのまま投げられます。unwrap は loadable と違ってエラーを処理しないので、上の例なら `UserBadge` と `UserName` の両方を覆う位置に ErrorBoundary を置いてください。v3 で追加された `useAtomValueRaw`（Promise を解決せずに返す）と `useAtomValueRawSync` は上級者向けで、通常は useAtomValue のままで足ります。
## atomWithStorageによるlocalStorage永続化とgetOnInit
`jotai/utils` の `atomWithStorage` は、値を localStorage に JSON で保存する atom を作ります。既定の実装は storage イベントを購読するので、別タブでの変更も反映されます。
```
import { useAtom } from 'jotai'
import { atomWithStorage, RESET } from 'jotai/utils'
// localStorage の 'theme' キーに JSON で保存。別タブの変更も storage イベントで同期される
export const themeAtom = atomWithStorage<'light' | 'dark'>('theme', 'light', undefined, {
getOnInit: true, // 初回の読み取りから保存値を返す（既定 false では最初は 'light'）
})
export function ThemeSwitch() {
const [theme, setTheme] = useAtom(themeAtom)
return (
<>
)
}
```
注意したいのは `getOnInit` の既定値が false である点です。localStorage に “dark” を入れた状態で試すと、getOnInit なしの atom は最初の読み取りで初期値の “light” を返し、購読を始めたあとで “dark” に置き換わりました。getOnInit: true の atom は最初から “dark” を返します。SPA では、この差がテーマのちらつきとして見えます。
ただし SSR では、サーバーに localStorage がありません。getOnInit: true にすると、サーバーは初期値、クライアントは保存値で描画するため、結果が食い違ってハイドレーションエラーの原因になります。公式の Next.js ガイドは、保存値に依存する部分をクライアントだけで描画するよう勧めています。`setTheme(RESET)` を呼ぶと値が初期値に戻り、localStorage のキーも削除されました。sessionStorage や React Native の AsyncStorage を使う場合は、`createJSONStorage(() => sessionStorage)` のようにストレージを差し替えます。
## onMountとjotai-effectによる副作用の書き方
atom を購読するコンポーネントが初めて現れたときに処理を走らせたい場合は、atom の `onMount` プロパティを使います。`onMount` は atom を更新する関数を受け取り、後片付けの関数を返せます。購読者がいなくなると、その後片付け関数が呼ばれます。
```
import { atom } from 'jotai'
import { atomEffect } from 'jotai-effect'
import { todosAtom } from './todo'
// onMount：atom を購読するコンポーネントが初めて現れたときに呼ばれ、戻り値が後片付けになる
export const widthAtom = atom(0)
widthAtom.onMount = (setWidth) => {
const update = () => setWidth(window.innerWidth)
update()
window.addEventListener('resize', update)
return () => window.removeEventListener('resize', update)
}
// atomEffect：依存する atom が変わるたびに副作用を実行する（jotai-effect）
export const saveTodosEffect = atomEffect((get) => {
const todos = get(todosAtom)
console.log('todos changed:', todos.length)
})
// 使う側で useAtomValue(saveTodosEffect) すると、そのコンポーネントのマウント中だけ有効になる
```
依存する atom が変わるたびに副作用を実行したい場合は、別パッケージの jotai-effect（2026年10月6日公開の 2.4.2）を `npm install jotai-effect` で追加します。peerDependencies は `jotai >=2.20.0 || >=3.0.0-alpha.0` で、v2・v3 のどちらでも使えます。上のコードを jotai 3.0.1 で動かすと、`saveTodosEffect` はマウント時（0件）と Todo 追加時（1件）の2回実行され、resize イベントでは widthAtom の値が 1024 から 640 に更新されました。
v2 では、非同期atomの読み取り関数の中で `setSelf` を使って自分自身を更新できました。この機能は v3 で削除されています。移行ガイドに直接の代替は無く、用途に応じて onMount か jotai-effect で書き直すよう案内されています。
## Providerとストアの使い分け
### Next.jsのSSRでProviderが必要な理由
provider-less モードのデフォルトストアは、モジュールに1つだけ存在します。SSR ではこのストアがサーバーのプロセス内に残り、複数のリクエストで共有されます。[公式の Next.js ガイド](https://github.com/pmndrs/jotai/blob/v3.0.1/docs/guides/nextjs.mdx)は、これがバグやセキュリティ上のリスクにつながると警告しています。ルートに Provider を置けば、ストアの寿命がリクエスト単位になります。公式ドキュメントは Next.js のほか、同じ作者の React フレームワーク [Waku](/tech/details/3620/) での SSR 設定も扱っています。
jotai の React 用エントリは、ファイル先頭に `'use client'` が付いています。Provider とフックはクライアントコンポーネントでしか動かないので、サーバーコンポーネントの `app/layout.tsx` からは、次のようなクライアント側のラッパーを介して使います。
```
'use client'
import type { ReactNode } from 'react'
import { Provider } from 'jotai'
import { useHydrateAtoms } from 'jotai/utils'
import { filterAtom } from './todo'
function Hydrate({ filter, children }: { filter: 'all' | 'active' | 'done'; children: ReactNode }) {
useHydrateAtoms([[filterAtom, filter]]) // ストアごとに1回だけ初期値を流し込む
return children
}
// app/layout.tsx から … のように使う
export function Providers({ filter, children }: { filter: 'all' | 'active' | 'done'; children: ReactNode }) {
return (
{children}
)
}
```
`useHydrateAtoms` は、サーバーで取得した値を atom の初期値として流し込むフックです。ストアごとに1回しか反映されないので、再レンダーで props が変わっても atom の値は変わりません。
### React外からのatom操作：createStore
`createStore()` で作ったストアは、`get`・`set`・`sub` の3つのメソッドを持ちます。React の外、たとえば WebSocket の受信処理やテストコードから atom を読み書きするときに使います。`jotai/vanilla` の `atom` と `createStore` は React に依存せず、v3 の peerDependencies でも react は省略可能（optional）です。
```
import { createStore } from 'jotai'
import { todosAtom, addTodoAtom, remainingCountAtom } from './todo'
export const store = createStore() // に渡せば React 側と共有できる
const unsub = store.sub(remainingCountAtom, () => {
console.log('未完了:', store.get(remainingCountAtom))
})
store.set(addTodoAtom, '請求書を送る') // 未完了: 1
console.log(store.get(todosAtom).length) // 1
unsub()
```
実行すると「未完了: 1」と「1」が出力されます。同じストアを `` に渡すと、React 側のコンポーネントと値を共有できます。Provider を使わない構成で同じことをするには、デフォルトストアを返す `getDefaultStore()` を使います。
## Vitestによるテストとテスト間のストア分離
[公式のテストガイド](https://github.com/pmndrs/jotai/blob/v3.0.1/docs/guides/testing.mdx)は、Testing Library の方針に沿って、Jotai を実装の詳細として扱い、利用者と同じ操作でコンポーネントを確かめるよう勧めています。そのうえで、テスト前に atom へ値を入れたいときは Provider を使う方法を示しています。次のテストは Vitest 5.1.0（environment: jsdom）と @testing-library/react 16.3.3 で、2本とも通りました。
```
import { atom, useAtom } from 'jotai'
export const countAtom = atom(0)
export function Counter() {
const [count, setCount] = useAtom(countAtom)
return
}
```
```
import { afterEach, expect, test } from 'vitest'
import { cleanup, fireEvent, render, screen } from '@testing-library/react'
import { Provider, createStore } from 'jotai'
import { Counter, countAtom } from './test-counter'
afterEach(cleanup)
test('ストアに初期値を入れてから描画する', () => {
const store = createStore() // テストごとに新しいストアを作る
store.set(countAtom, 5)
render(
,
)
fireEvent.click(screen.getByRole('button'))
expect(screen.getByRole('button').textContent).toBe('count: 6')
expect(store.get(countAtom)).toBe(6) // React の外からも値を確かめられる
})
test('Provider で包めば前のテストの値は残らない', () => {
render(
,
)
expect(screen.getByRole('button').textContent).toBe('count: 0')
})
```
Provider で包むのを省くと、テストはデフォルトストアを共有します。Provider なしの Counter を描画してボタンを1回押すテストと、同じく Provider なしで描画するだけのテストを同じファイルで続けて実行したところ、2本目は「count: 0」ではなく「count: 1」から始まりました。Vitest は既定（`isolate: true`）でテストファイルごとに環境を分けるため、値が残るのは同じファイル内のテストの間です。`isolate: false` にすると、同じワーカーで動く別ファイルにも持ち越されえます。テストごとに `createStore()` のストアを渡すか、空の `` で包めば持ち越しは起きません。
初期値を流し込む方法は2つあります。上のように `store.set` で入れてから Provider に渡す方法と、公式ガイドのように `useHydrateAtoms` を呼ぶ小さなコンポーネントを Provider の内側に置く方法です。前者はテストの最後に `store.get` で値を直接確かめられるので、書き込み専用atomのロジックを検証するときに向いています。atom を単体で確かめたいときは、公式ガイドのとおり `renderHook` で useAtom を呼び、`act` の中で更新して `result.current` を検証します。
## Jotai DevToolsの導入と使い方
atom の値と変更履歴を画面上で確認するには、別パッケージの jotai-devtools を使います。[2026年10月5日公開の 0.15.0](https://github.com/jotaijs/jotai-devtools/releases/tag/v0.15.0) で jotai v3 に対応し、peerDependencies が `jotai >=3.0.0` に変わりました。最新の 0.15.1（10月6日）は v2 では入りません。v2 のまま使う場合、0.14.0 の peerDependencies は `jotai >=2.20.0` なので、jotai を 2.20 系に上げたうえで `npm install jotai-devtools@0.14.0` と版を指定します。jotai 3.0.1 と jotai-devtools 0.15.1 を組み合わせた下のコードは型検査を通過しました。
```
import { Provider, createStore } from 'jotai'
import { DevTools } from 'jotai-devtools'
import 'jotai-devtools/styles.css'
import App from './counter'
const store = createStore()
export default function Root() {
return (
{/* 本番ビルドでは表示されない */}
)
}
```
`` は本番以外の環境でだけ動きますが、README は `process.env.NODE_ENV` の条件分岐で包み、CSS も条件分岐の中で読み込んで本番のバンドルから除く書き方を推奨しています。Next.js では `next.config.ts` の `transpilePackages` に `'jotai-devtools'` を加えます。パネル上の atom 名は `debugLabel` から表示され、v3 で別パッケージになった `jotai-babel` の preset を入れると変数名が自動で付きます。
## v2からv3への移行：削除されたAPIと置き換え先
[v3.0.0 のリリースノート](https://github.com/pmndrs/jotai/releases/tag/v3.0.0)は「mostly backward-compatible」と説明し、移行ガイドにも、v2 で非推奨の警告が出ていないアプリはそのまま動くはずだと書かれています。削除・移動された機能は次の5つです。
| v2の機能 | v3での置き換え |
| ------------------------ | ------------------------ |
| jotai/utils の atomFamily | jotai-family パッケージ |
| jotai/utils の loadable | unwrap（または自作） |
| jotai/babel のプラグイン | jotai-babel パッケージ |
| 読み取り関数の setSelf | onMount または jotai-effect |
| useAtomValue の delay | store.sub を使う自作フック |
jotai 3.0.1 の `jotai/utils` を実際に読み込むと、loadable と atomFamily のどちらもエクスポートに含まれていませんでした。atomFamily は `import { atomFamily } from 'jotai-family'` に書き換えれば、同じ引数で同じ atom を返す挙動はそのまま使えます（`todoFamily(1) === todoFamily(1)` が true になることを確認）。
### 3.0.0のuseAtomValueで子コンポーネントの書き込みが反映されない回帰
v2 の useAtomValue は、値が変わらなくてもマウント直後に必ず1回再レンダーしていました（カウンターと同じ条件で、マウント時の描画は v2.20.3 で2回、v3 で1回）。この1回には、初回描画から購読開始までの間に起きた更新を拾う役割がありました。React は子の useEffect を親より先に実行するので、子が useEffect で atom に書き込むと、親の購読はその後になります。
```
import { useEffect } from 'react'
import { atom, useAtomValue, useSetAtom } from 'jotai'
const statusAtom = atom('initial')
function Child() {
const setStatus = useSetAtom(statusAtom)
useEffect(() => {
setStatus('written-by-child') // 子の useEffect は親より先に実行される
}, [setStatus])
return null
}
export function Parent() {
const status = useAtomValue(statusAtom)
return (
<>
{status}
)
}
```
| バージョン | 親に表示された値 |
| ------------ | ---------------- |
| jotai 2.20.3 | written-by-child |
| jotai 3.0.0 | initial（取りこぼし） |
| jotai 3.0.1 | written-by-child |
[3.0.1 のリリースノート](https://github.com/pmndrs/jotai/releases/tag/v3.0.1)は「This fixes a regression in useAtomValue introduced in v3.0.0\. Please update.」と書いています。修正（PR #3373）は、購読直後に値を確認し直し、変わっていなければ再レンダーしないものです。3.0.0 でも `useAtomValueRawSync` に替えると “written-by-child” が表示されました。公式ドキュメントの useAtomValue の項には、この種の更新を取りこぼしうるという記述が2026年11月時点でも残っているため、取りこぼしが許されない画面では useAtomValueRawSync も候補です（並行レンダリングの恩恵は受けられません）。
### Jotai v2からv3への移行手順
1. まず v2 の最終版 2.20.3 に上げ、開発ビルドで非推奨の警告が出ないことを確認します。
2. React 18・TypeScript 5.5・Node.js 22.12 以上を満たしているか確認します。CI の Node.js も含みます。
3. 上の表の5機能を置き換えます。atomFamily と Babel プラグインは import 先の変更だけで済みます。
4. `jotai/esm/…` などの内部パスを import していないか検索します。v3 では読み込めません。
5. jotai-devtools を使っていれば 0.15 系に上げます。0.14.0 以前は v3 に対応していません。
6. `npm install jotai@^3.0.1` で更新し、子の useEffect で atom を書いている画面を重点的に確認します。
## Zustand・Redux Toolkit・Recoilとの比較と選び方
| ライブラリ | 状態のモデル | 最新版 | 週間DL数 |
| ------------- | ------------- | ------ | ---------- |
| Jotai | atomの組み合わせ | 3.0.1 | 9,253,805 |
| Zustand | 単一ストア | 5.0.16 | 89,687,623 |
| Redux Toolkit | 単一ストア＋slice | 2.14.0 | 46,758,079 |
| Recoil | atom＋selector | 0.7.7 | 580,061 |
週間DL数は npm の2026年10月28日〜11月3日の値で、最新版は11月6日時点の npm の latest です。[公式の比較ページ](https://github.com/pmndrs/jotai/blob/v3.0.1/docs/basics/comparison.mdx)は「Jotai is like Recoil. Zustand is like Redux.」と整理しています。ストアの置き場所も、Jotai は Provider（コンテキスト）を、Zustand はモジュールのストアを優先する設計です。
Jotai を選ぶのは、useState と useContext で回していた状態の受け渡しが辛くなってきた段階です。Provider を何重にも重ねていたり、値ごとに Context を分けていたりするなら、そのまま置き換えられます。状態を画面単位でコード分割したい場合や、非同期データを Suspense で待ちたい場合も、公式の比較ページは Jotai を勧めています。Zustand の使い方は「[Zustandとは？読み方・使い方とv5の注意点【5.0.16対応】](/tech/details/7615/)」で解説しています。
反対に、すべての状態変更をアクションとして記録し、[Redux DevTools](/tech/details/3060/) で時系列に巻き戻して調べる運用をしているなら、Jotai は向きません。サーバーから取得したデータのキャッシュや再取得が状態の大半を占めるなら、先に [TanStack Query](/tech/details/10307/) の導入を検討してください。Jotai に残るのは UI の状態だけになることが多いです。
Recoil の GitHub リポジトリはアーカイブ（読み取り専用）になっており、npm の最終公開は2023年3月の 0.7.7 です。Recoil から移るときは、`atom({ key, default: 初期値 })` を `atom(初期値)` に書き換え、`selector` を派生atomに、`atomFamily` を jotai-family に置き換えます。Jotai は atom をオブジェクト参照で識別するので、キーの重複を気にする必要もなくなります。
## よくある質問
### Jotaiの読み方と名前の意味は何ですか？
「じょうたい」と読みます。日本語の「状態」が由来で、公式の比較ページにも「Jotai means “state” in Japanese.」とあります。同じ開発元の Zustand もドイツ語で「状態」を意味します。
### Jotaiの作者は誰ですか？
作者は Daishi Kato 氏（GitHub: dai-shi）で、[GitHub のプロフィール](https://github.com/dai-shi)の所在地は Tokyo です。同じプロフィールで Zustand・Jotai・Valtio の3つの状態管理ライブラリと、React フレームワークの Waku をメンテナンスしていると紹介しています。GitHub リポジトリの初回コミットは2020年8月11日（UTC）で、npm には同日に 0.0.0 が登録され、8月30日に 0.1.0 が公開されました。
### JotaiはReact Nativeでも使えますか？
使えます。公式の React Native ガイドは、atom を変更なしで使えると明記しています。永続化だけは localStorage が無いので、`createJSONStorage(() => AsyncStorage)` で作ったストレージを atomWithStorage に渡します。React Native でのアプリ開発全体を相談したい場合は、[Flutter・React Native のアプリ開発支援](/service/apps/cross%5Fplatform/)も行っています。
### Next.jsのServer ComponentsでJotaiのフックは使えますか？
使えません。jotai の React 用エントリには `'use client'` が付いており、フックと Provider はクライアントコンポーネント専用です。サーバーで取得した値は props でクライアントコンポーネントに渡し、useHydrateAtoms で atom に流し込みます。
### v3でatomFamilyが使えなくなったのはなぜですか？
削除されたわけではなく、別パッケージの jotai-family に移されました。`npm install jotai-family` で追加し、import 元を `'jotai/utils'` から `'jotai-family'` に変えれば、そのまま使えます。
## 関連記事
- [Zustandとは？読み方・使い方とv5の注意点【5.0.16対応】](/tech/details/7615/)
- [Redux Toolkitとは？createSliceとRTK Queryの実装と採用判断【2026年8月版】](/tech/details/16013/)
- [React Contextの使い方｜createContext・useContext・Providerの実装と再レンダー対策【React 19.3対応】](/tech/details/2681/)
- [TanStack Queryとは？React Queryとの違い・v5の使い方と既定値の落とし穴](/tech/details/10307/)
- [Nano Stores（nanostores）の使い方｜React・Astro連携と非同期・永続化の注意点【1.5.5対応】](/tech/details/9798/)
---
出典: [Jotaiとは？atomで組むReact状態管理の使い方・テスト・v3移行【3.0.1対応】]()（株式会社一創）