Jotai

Primitive and flexible state management for React.

Quick Start

Install:

npm install jotai

Basic usage:

import { atom, useAtom } from 'jotai';

const countAtom = atom(0);

function Counter() {
  const [count, setCount] = useAtom(countAtom);

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

Atoms

Primitive Atoms

import { atom } from 'jotai';

// Number
const countAtom = atom(0);

// String
const nameAtom = atom('');

// Boolean
const isOpenAtom = atom(false);

// Object
const userAtom = atom({ name: '', email: '' });

// Array
const todosAtom = atom<Todo[]>([]);

Using Atoms

import { useAtom, useAtomValue, useSetAtom } from 'jotai';

function Component() {
  // Read and write
  const [count, setCount] = useAtom(countAtom);

  // Read only
  const count = useAtomValue(countAtom);

  // Write only (no re-render on change)
  const setCount = useSetAtom(countAtom);

  return (
    <div>
      <p>{count}</p>
      <button onClick={() => setCount(c => c + 1)}>+1</button>
    </div>
  );
}

Derived Atoms

Read-Only Derived

import { atom } from 'jotai';

const countAtom = atom(0);

// Simple derived
const doubledAtom = atom((get) => get(countAtom) * 2);

// Derived from multiple atoms
const firstNameAtom = atom('John');
const lastNameAtom = atom('Doe');
const fullNameAtom = atom((get) => {
  return `${get(firstNameAtom)} ${get(lastNameAtom)}`;
});

// Filtered list
const todosAtom = atom<Todo[]>([]);
const completedTodosAtom = atom((get) => {
  return get(todosAtom).filter(todo => todo.completed);
});

Read-Write Derived

const countAtom = atom(0);

// Derived with custom setter
const doubledAtom = atom(
  (get) => get(countAtom) * 2,
  (get, set, newValue: number) => {
    set(countAtom, newValue / 2);
  }
);

// Toggle atom
const isOpenAtom = atom(false);
const toggleAtom = atom(
  (get) => get(isOpenAtom),
  (get, set) => {
    set(isOpenAtom, !get(isOpenAtom));
  }
);

Write-Only Atoms

// Action atom (no read value)
const incrementAtom = atom(null, (get, set) => {
  set(countAtom, get(countAtom) + 1);
});

// Usage
const increment = useSetAtom(incrementAtom);
<button onClick={increment}>+1</button>

// Action with parameters
const addTodoAtom = atom(null, (get, set, text: string) => {
  const todos = get(todosAtom);
  set(todosAtom, [...todos, { id: Date.now(), text, completed: false }]);
});

Async Atoms

Basic Async Atom

import { atom, useAtomValue } from 'jotai';
import { Suspense } from 'react';

const userIdAtom = atom(1);

const userAtom = atom(async (get) => {
  const id = get(userIdAtom);
  const response = await fetch(`/api/users/${id}`);
  return response.json();
});

function UserProfile() {
  const user = useAtomValue(userAtom);
  return <div>{user.name}</div>;
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <UserProfile />
    </Suspense>
  );
}

Async Atom with Error Handling

import { atom, useAtom } from 'jotai';
import { loadable } from 'jotai/utils';

const userAtom = atom(async (get) => {
  const response = await fetch('/api/user');
  if (!response.ok) throw new Error('Failed to fetch');
  return response.json();
});

const loadableUserAtom = loadable(userAtom);

function UserProfile() {
  const [userLoadable] = useAtom(loadableUserAtom);

  if (userLoadable.state === 'loading') {
    return <div>Loading...</div>;
  }

  if (userLoadable.state === 'hasError') {
    return <div>Error: {userLoadable.error.message}</div>;
  }

  return <div>{userLoadable.data.name}</div>;
}

Refreshable Async Atom

import { atom, useAtom, useSetAtom } from 'jotai';

const fetchCountAtom = atom(0);

const dataAtom = atom(async (get) => {
  get(fetchCountAtom); // Dependency for refresh
  const response = await fetch('/api/data');
  return response.json();
});

const refreshAtom = atom(null, (get, set) => {
  set(fetchCountAtom, (c) => c + 1);
});

function DataComponent() {
  const data = useAtomValue(dataAtom);
  const refresh = useSetAtom(refreshAtom);

  return (
    <div>
      <pre>{JSON.stringify(data)}</pre>
      <button onClick={refresh}>Refresh</button>
    </div>
  );
}

Jotai Utilities

atomWithStorage

import { atomWithStorage } from 'jotai/utils';

// Persists to localStorage
const themeAtom = atomWithStorage('theme', 'light');

// With sessionStorage
const sessionAtom = atomWithStorage('session', null, sessionStorage);

function ThemeToggle() {
  const [theme, setTheme] = useAtom(themeAtom);

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Theme: {theme}
    </button>
  );
}

atomWithReset

import { atomWithReset, useResetAtom } from 'jotai/utils';

const countAtom = atomWithReset(0);

function Counter() {
  const [count, setCount] = useAtom(countAtom);
  const reset = useResetAtom(countAtom);

  return (
    <div>
      <p>{count}</p>
      <button onClick={() => setCount(c => c + 1)}>+1</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

atomFamily

import { atomFamily } from 'jotai/utils';

// Create a family of atoms with parameter
const todoAtomFamily = atomFamily((id: string) =>
  atom({ id, text: '', completed: false })
);

function TodoItem({ id }: { id: string }) {
  const [todo, setTodo] = useAtom(todoAtomFamily(id));

  return (
    <div>
      <input
        value={todo.text}
        onChange={(e) => setTodo({ ...todo, text: e.target.value })}
      />
    </div>
  );
}

selectAtom

import { selectAtom } from 'jotai/utils';

const userAtom = atom({ name: 'John', age: 30, email: 'john@example.com' });

// Only re-renders when name changes
const nameAtom = selectAtom(userAtom, (user) => user.name);

// With equality function
const ageAtom = selectAtom(
  userAtom,
  (user) => user.age,
  (a, b) => a === b
);

splitAtom

import { splitAtom } from 'jotai/utils';

const todosAtom = atom<Todo[]>([]);
const todoAtomsAtom = splitAtom(todosAtom);

function TodoList() {
  const [todoAtoms, dispatch] = useAtom(todoAtomsAtom);

  return (
    <ul>
      {todoAtoms.map((todoAtom) => (
        <TodoItem
          key={`${todoAtom}`}
          todoAtom={todoAtom}
          onRemove={() => dispatch({ type: 'remove', atom: todoAtom })}
        />
      ))}
    </ul>
  );
}

function TodoItem({ todoAtom, onRemove }) {
  const [todo, setTodo] = useAtom(todoAtom);

  return (
    <li>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={(e) => setTodo({ ...todo, completed: e.target.checked })}
      />
      {todo.text}
      <button onClick={onRemove}>Delete</button>
    </li>
  );
}

focusAtom

import { focusAtom } from 'jotai-optics';

const userAtom = atom({ name: 'John', address: { city: 'NYC', zip: '10001' } });

// Focus on nested property
const cityAtom = focusAtom(userAtom, (optic) => optic.prop('address').prop('city'));

function CityInput() {
  const [city, setCity] = useAtom(cityAtom);
  return <input value={city} onChange={(e) => setCity(e.target.value)} />;
}

Provider

Scoped State

import { Provider, createStore } from 'jotai';

const myStore = createStore();

function App() {
  return (
    <Provider store={myStore}>
      <Counter />
    </Provider>
  );
}

Multiple Providers

function App() {
  return (
    <Provider>
      <Counter /> {/* Uses Provider 1 */}
      <Provider>
        <Counter /> {/* Uses Provider 2 - isolated state */}
      </Provider>
    </Provider>
  );
}

Store API

import { createStore } from 'jotai';

const store = createStore();

// Get value outside React
const count = store.get(countAtom);

// Set value outside React
store.set(countAtom, 10);

// Subscribe to changes
const unsub = store.sub(countAtom, () => {
  console.log('Count changed:', store.get(countAtom));
});

DevTools

import { useAtomsDebugValue } from 'jotai-devtools';

function DebugAtoms() {
  useAtomsDebugValue();
  return null;
}

function App() {
  return (
    <>
      <DebugAtoms />
      <Counter />
    </>
  );
}

Patterns

Form State

const formAtom = atom({
  name: '',
  email: '',
  message: '',
});

const nameAtom = focusAtom(formAtom, (o) => o.prop('name'));
const emailAtom = focusAtom(formAtom, (o) => o.prop('email'));
const messageAtom = focusAtom(formAtom, (o) => o.prop('message'));

const isValidAtom = atom((get) => {
  const form = get(formAtom);
  return form.name.length > 0 && form.email.includes('@');
});

Optimistic Updates

const todosAtom = atom<Todo[]>([]);

const addTodoAtom = atom(null, async (get, set, text: string) => {
  const tempId = Date.now();
  const newTodo = { id: tempId, text, completed: false, pending: true };

  // Optimistic update
  set(todosAtom, [...get(todosAtom), newTodo]);

  try {
    const response = await fetch('/api/todos', {
      method: 'POST',
      body: JSON.stringify({ text }),
    });
    const savedTodo = await response.json();

    // Replace temp with saved
    set(todosAtom, get(todosAtom).map(t =>
      t.id === tempId ? { ...savedTodo, pending: false } : t
    ));
  } catch (error) {
    // Rollback
    set(todosAtom, get(todosAtom).filter(t => t.id !== tempId));
  }
});

Best Practices

1. Define atoms outside components - Avoid recreating atoms
2. Use derived atoms - Compose complex state from primitives
3. Use utilities - atomWithStorage, atomFamily, splitAtom
4. Keep atoms small - One piece of state per atom
5. Use Suspense for async - Or loadable for manual handling

Common Mistakes

Reference Files

• references/utilities.md - Jotai utilities
• references/async.md - Async patterns
• references/integration.md - Framework integration