Reading and Writing Atoms with useAtom

useAtom(someAtom) returns [value, setter], mirroring the useState API. The value is the current atom state; the setter updates it. Use this when a component both reads and writes the atom.

The setter accepts either a new value or an updater function: setCount(c => c + 1).

useAtomValue(someAtom) returns only the current value, with no setter. Use this in display-only components that read state but never modify it.

Because the component does not hold a setter reference, the intent is clearly documented in code: this component is a pure reader.

useSetAtom(someAtom) returns only the setter function. Critically, it does not subscribe the component to the atom's value. The component never re-renders when the atom changes.

Use this for action-only components like buttons that dispatch state changes but do not display any derived UI.

A component that calls useSetAtom(countAtom) to increment a counter will never re-render when countAtom changes, because it has no value subscription. Only the component displaying the count re-renders.

This is a simple but powerful optimization: decouple writers from readers to prevent cascading re-renders.

Import atomWithStorage from jotai/utils. Use it exactly like atom() but pass a storage key as the first argument: atomWithStorage('theme', 'light'). The atom automatically syncs to localStorage.

On page reload, the atom hydrates from localStorage. All components reading the atom pick up the persisted value immediately.

The RESET symbol from jotai/utils can be passed to the setter of an atomWithStorage atom: setter(RESET). This clears the localStorage entry and resets the atom to its initial value.

This is useful for logout flows or "reset to defaults" buttons in settings pages.

atomFamily from jotai/utils creates a factory that returns a parameterized atom. For example, atomFamily(id => atom(null)) creates a separate atom for each unique id passed.

This is ideal for per-item state like selectedAtom(itemId) or expandedAtom(rowId) without managing a single large map atom.

Atom families can grow unbounded if IDs accumulate. Use atomFamily.setShouldRemove((createdAt, param) => ...) to define a cleanup predicate that Jotai calls when deciding to evict stale family members.

For lists where items are added and removed, always clean up atom family entries when items are deleted to avoid memory leaks.

The jotai-devtools package provides a visual panel listing all active atoms and their current values. Install it, wrap your app in DevTools, and inspect atom state in real time.

Each atom update is logged with the previous and next value, making debugging complex atom interactions straightforward.

In a large list, a ListContainer component can use useSetAtom(selectedIdAtom) to update selection without subscribing to selectedIdAtom. Only the individual ListItem components that call useAtomValue(selectedIdAtom) re-render when the selection changes.

This pattern scales well: adding thousands of list items does not slow down selection updates.

Choose the hook that matches your component's need: useAtomValue for pure display, useSetAtom for pure actions, and useAtom when you need both. This intentional API design makes component responsibility clear at a glance.

A form field component typically uses useAtom; a submit button uses useSetAtom; a label displaying a count uses useAtomValue.

What is the key advantage of using useSetAtom instead of useAtom?

useAtom gives both value and setter; useAtomValue gives only the value (read subscriptions); useSetAtom gives only the setter (no re-render on value change). atomWithStorage persists to localStorage with RESET support, and atomFamily creates per-parameter atoms for dynamic lists.

Choosing the right hook minimizes unnecessary re-renders and makes component intent explicit.