{doubledCount}
} ``` ### Creating an atom from multiple atoms You can combine multiple atoms to create a derived atom. ```jsx const count1 = atom(1) const count2 = atom(2) const count3 = atom(3) const sum = atom((get) => get(count1) + get(count2) + get(count3)) ``` Or if you like fp patterns ... ```jsx const atoms = [count1, count2, count3, ...otherAtoms] const sum = atom((get) => atoms.map(get).reduce((acc, count) => acc + count)) ``` ### Derived async atoms [
](https://react.dev/reference/react/Suspense)
You can make the read function an async function too.
```jsx
const urlAtom = atom('https://json.host.com')
const fetchUrlAtom = atom(async (get) => {
const response = await fetch(get(urlAtom))
return await response.json()
})
function Status() {
// Re-renders the component after urlAtom is changed and the async function above concludes
const [json] = useAtom(fetchUrlAtom)
...
```
### You can create a writable derived atom
Specify a write function at the second argument. `get` will return the current
value of an atom. `set` will update the value of an atom.
```jsx
const decrementCountAtom = atom(
(get) => get(countAtom),
(get, set, _arg) => set(countAtom, get(countAtom) - 1)
)
function Counter() {
const [count, decrement] = useAtom(decrementCountAtom)
return (
{count}
...
```
### Write only derived atoms
Just do not define a read function.
```jsx
const multiplyCountAtom = atom(null, (get, set, by) =>
set(countAtom, get(countAtom) * by),
)
function Controls() {
const [, multiply] = useAtom(multiplyCountAtom)
return
}
```
### Async actions
Just make the write function an async function and call `set` when you're ready.
```jsx
const fetchCountAtom = atom(
(get) => get(countAtom),
async (_get, set, url) => {
const response = await fetch(url)
set(countAtom, (await response.json()).count)
}
)
function Controls() {
const [count, compute] = useAtom(fetchCountAtom)
return (
...
```
### Note about functional programming
Jotai's fluid interface is no accident — atoms are monads, just like promises!
Monads are an [established]()
pattern for modular, pure, robust and understandable code which is [optimized for change](https://overreacted.io/optimized-for-change/).
Read more about [Jotai and monads.](https://jotai.org/docs/basics/functional-programming-and-jotai)
## Links
- [website](https://jotai.org)
- [documentation](https://jotai.org/docs)
- [course](https://egghead.io/courses/manage-application-state-with-jotai-atoms-2c3a29f0)
---
### Overview (`website/README.md`)
## Getting Started
Install the dependencies:
```bash
pnpm install --ignore-workspace
```
Make a cache directory:
```bash
mkdir .cache
```
Run the development server:
```bash
pnpm run dev
```
Open [http://localhost:9000](http://localhost:9000) with your browser to see the result.
---
### Overview (`examples/hacker_news/README.md`)
# Hacker News [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/hacker_news)
## Description
Browse Hacker News items with Jotai. Click the arrow button to load the next item.
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/hacker_news && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/hacker_news
---
### Overview (`examples/hello/README.md`)
# Hello [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/hello)
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/hello && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/hello
---
### Overview (`examples/mega-form/README.md`)
# Mega form [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/mega-form)
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/mega-form && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/mega-form
---
### Overview (`examples/starter/README.md`)
# Starter [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/starter)
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/starter && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/starter
---
### Overview (`examples/text_length/README.md`)
# Text Length [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/text_length)
## Description
Count the length and show the uppercase of any text.
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/text_length && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/text_length
---
### Overview (`examples/todos/README.md`)
# Todos [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/todos)
## Description
Create a todo list, mark tasks as completed, and switch between `Completed` and `Incomplete` to filter items.
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/todos && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/todos
---
### Overview (`examples/todos_with_atomFamily/README.md`)
# Todos with atomFamily [](https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/todos_with_atomFamily)
> **⚠️ Note:** `atomFamily` from `jotai/utils` is deprecated and will be removed in v3. For new projects, please use the [`jotai-family`](https://github.com/jotaijs/jotai-family) package instead.
## Description
Implement a todo list using atomFamily and `localStorage`. You can save your todo list by clicking `Save to localStorage`, then restore it by clicking `Load from localStorage`.
## Set up locally
```bash
git clone https://github.com/pmndrs/jotai
# install project dependencies & build the library
cd jotai && pnpm install
# move to the examples folder & install dependencies
cd examples/todos_with_atomFamily && pnpm install
# start the dev server
pnpm dev
```
## Set up on `StackBlitz`
Link: https://stackblitz.com/github/pmndrs/jotai/tree/main/examples/todos_with_atomFamily
---
### Index (`docs/index.mdx`)
---
title: Documentation
description: Table of contents
nav: 0
---
Welcome to the Jotai v2 documentation! Jotai's atomic approach to global React state management scales from a simple `useState` replacement to an enterprise application with complex requirements.
## Features
- Minimal core API (2kb)
- Many utilities and extensions
- TypeScript oriented
- Works with Next.js, Waku, Remix, and React Native
## Core
Jotai has a very minimal API, exposing only a few exports from the main `jotai` bundle. They are split into four categories below.
{children}
)
}
const Component = () => {
const [state, setState] = useContext(StateContext)
}
// 3. Have multiple states and contexts
const State1Context = createContext()
const State2Context = createContext()
const Parent = ({ children }) => (
{children}
)
const Component1 = () => {
const [state, setState] = useContext(State1Context)
}
const Component2 = () => {
const [state, setState] = useContext(State2Context)
}
```
Now let's see how Jotai simplify it for us. You can just use atoms instead of multiple `Context`.
```jsx
import { Provider, atom, useAtom } from 'jotai'
const atom1 = atom(0)
const atom2 = atom(0)
// Optional: you can use Provider's just like useContext,
// ...but if you only need one,
// ...you can just omit it and Jotai will use a default one (called Provider-less mode).
const Parent = ({ children }) => {
return {children}
}
const Component1 = () => {
const [state, setState] = useAtom(atom1)
}
const Component2 = () => {
const [state, setState] = useAtom(atom2)
}
```
### How is Jotai different from Zustand?
#### Name
Jotai means "state" in Japanese.
Zustand means "state" in German.
#### Analogy
Jotai is like Recoil.
Zustand is like Redux.
#### Where state resides
To hold states,
Both have stores that can exist either at module level or at context level.
Jotai is designed to be context first, and module second.
Zustand is designed to be module first, and context second.
#### How to structure state
Jotai state consists of atoms (i.e. bottom-up).
Zustand state is one object (i.e. top-down).
#### Technical difference
The major difference is the state model. Zustand is a single store (although you could create multiple separate stores), while Jotai consists of primitive atoms and allows composing them together. In this sense, it's the matter of programming mental model.
#### When to use which
- If you need a replacement for useState+useContext, Jotai fits well.
- If you want a simple module state, Zustand fits well.
- If code splitting is important, Jotai should perform well.
- If you prefer Redux devtools, Zustand is good to go.
- If you want to make use of Suspense, Jotai is the one.
### How is Jotai different from Recoil?
(Disclaimer: the author is not very familiar with Recoil, this may be biased and inaccurate.)
#### Developer
- Jotai is developed with collective work by a few developers in Poimandres (formerly react-spring) org.
- Recoil is developed by a team at Facebook.
#### Basis
- Jotai is focusing on primitive APIs for easy learning, and it's unopinionated. (The same philosophy with Zustand)
- Recoil is all-in-one, and it has various cache strategies.
#### Technical difference
- Jotai depends on atom object referential identities.
- Recoil depends on atom string keys.
#### When to use which
- If you want to learn something new, either should work.
- If you like Zustand, Jotai would also be pleasant.
- If you need React Context alternatives, Jotai comes with enough features.
- If you need to read and write atoms outside React, Jotai provides store API.
- If you would try to create a new library, Jotai might give good primitives.
- Otherwise, both are pretty similar about the general goals and basic techniques, so please try both and share your feedback with us.
---
### Basics Concepts (`docs/basics/concepts.mdx`)
---
title: Concepts
nav: 7.01
---
Jotai is a library that will make you return to the basics of React development & keep everything simple.
### From scratch
Before trying to compare Jotai with what we may have known previously, let's just dive straight into something very simple.
The React world is very much like our world, it's a big set of small entities, we call them components, and we know that they have their own state. Structuring your components to interact altogether will create your app.
Now, the Jotai world also has its small entities, atoms, and they also have their state. Composing atoms will create your app state!
Jotai considers anything to be an atom, so you may say: `Huh, I need objects and arrays, filter them and then sort them out`.
And here's the beauty of it, Jotai gracefully lets you create dumb atoms derived from even more dumb atoms.
If, for example, I have a page with 2 tabs: online friends and offline friends.
I will have 2 atoms simply derived from a common, dumber source.
```js
const dumbAtom = atom([{ name: 'Friend 1', online: false }])
const onlineAtom = atom((get) => get(dumbAtom).filter((item) => item.online))
const offlineAtom = atom((get) => get(dumbAtom).filter((item) => !item.online))
```
And you could keep going on complexity forever.
Another incredible feature of Jotai is the built-in ability to suspend when using asynchronous atoms. This is a relatively new feature that needs more experimentation, but is definitely the future of how we will build React apps. [Check out the docs](https://react.dev/blog/2022/03/29/react-v18#new-suspense-features) for more info.
---
### Basics Functional Programming And Jotai (`docs/basics/functional-programming-and-jotai.mdx`)
---
title: Functional programming and Jotai
nav: 7.04
---
### Unexpected similarities
If you look at getter functions long enough, you may see a striking resemblance
to a certain JavaScript language feature.
```tsx
const nameAtom = atom('Visitor')
const countAtom = atom(1)
const greetingAtom = atom((get) => {
const name = get(nameAtom)
const count = get(countAtom)
return (
Hello, {name}! You have visited this page {count} times.
)
})
```
Compare that code with `async`–`await`:
```tsx
const namePromise = Promise.resolve('Visitor')
const countPromise = Promise.resolve(1)
const greetingPromise = (async function () {
const name = await namePromise
const count = await countPromise
return (
Hello, {name}! You have visited this page {count} times.
)
})()
```
This similarity is no coincidence. Both atoms and promises are **Monads**†, a
concept from functional programming. The syntax used in both `greetingAtom` and
`greetingPromise` is known as **do-notation**, a syntax sugar for the plainer
monad interface.
### About monads
The monad interface is responsible for the fluidity of the atom and promise
interfaces. The monad interface allowed us to define `greetingAtom` in terms of
`nameAtom` and `countAtom`, and allowed us to define `greetingPromise` in terms
of `namePromise` and `countPromise`.
If you're curious, a structure (like `Atom` or `Promise`) is a monad if you can
implement the following functions for it. A fun exercise is trying to implement
`of`, `map` and `join` for Arrays.
```ts
type SomeMonad = /* for example... */ Array
declare function of(plainValue: T): SomeMonad
declare function map(
anInstance: SomeMonad,
transformContents: (contents: T) => V,
): SomeMonad
declare function join(nestedInstances: SomeMonad>): SomeMonad
```
The shared heritage of Promises and Atoms means many patterns and best-practices
can be reused between them. Let's take a look at one.
### Sequencing
When talking about callback hell, we often mention the boilerplate, the
indentation and the easy-to-miss mistakes. However, plumbing a single async
operation into another single async operation was not the end of the callback
struggle. What if we made four network calls and needed to wait for them all?
A snippet like this was common:
```ts
const nPending = 4
const results: string[]
function callback(err, data) {
if (err) throw err
results.push(data)
if (results.length === nPending) {
// do something with results...
}
}
```
But what if the results have different types? and the order was important? Well,
we'd have a lot more frustrating work to do! This logic would be duplicated at
each usage, and would be easy to mess up. Since ES6, we simply call `Promise.all`:
```ts
declare function promiseAll(promises: Array>): Promise>
```
`Promise.all` "rearranges" `Array` and `Promise`. It turns out this concept,
_sequencing_, can be implemented for all monad–_Traversable_ pairs. Many kinds
of collections are Traversables, including Arrays. For example, this is a case
of sequencing specialized for atoms and arrays:
```ts
function sequenceAtomArray(atoms: Array>): Atom> {
return atom((get) => atoms.map(get))
}
```
### Culmination
Monads have been an interest to mathematicians for 60 years, and to programmers
for 40. There are many resources out there on patterns for monads. Take a look
at them! Here are a select few:
- [_Inventing Monads_](https://stopa.io/post/247) by Stepan Parunashvili
- [_How Monads Solve Problems_](https://thatsnomoon.dev/posts/ts-monads/) by ThatsNoMoon
- Wiki page [list of monad tutorials](https://wiki.haskell.org/Monad_tutorials_timeline)
- [Typeclassopedia](https://wiki.haskell.org/Typeclassopedia) (for the curious)
Learning a neat trick on using promises may well translate to atoms, as
`Promise.all` and `sequenceAtomArray` did. Monads are not magic, just unusually
useful, and a tool worth knowing.
---
_Notes_
**[†]** The ES6 Promise is not a completely valid monad because it cannot nest other
Promises, e.g. `Promise>` is semantically equivalent to
`Promise`. This is why Promises only have a `.then`, and not both a
`.map` and `.flatMap`. ES6 Promises are probably more properly described as
"monadic" rather than as monads.
Unlike ES6 Promises, the ES6 Array is a completely lawful monad.
---
### Basics Showcase (`docs/basics/showcase.mdx`)
---
title: Showcase
nav: 7.03
---
- Text Length example [](https://githubbox.com/pmndrs/jotai/tree/main/examples/text_length)
Count the length and show the uppercase of any text.
- Hacker News example [](https://githubbox.com/pmndrs/jotai/tree/main/examples/hacker_news)
Demonstrate a news article with Jotai, hit next to see more articles.
- Todos example [](https://githubbox.com/pmndrs/jotai/tree/main/examples/todos)
Record your todo list by typing them into this app, check them off if you have completed the task, and switch between `Completed` and `Incompleted` to see the status of your task.
- Todos example with atomFamily and localStorage [](https://githubbox.com/pmndrs/jotai/tree/main/examples/todos_with_atomFamily)
Implement a todo list using atomFamily and localStorage. You can store your todo list to localStorage by clicking `Save to localStorage`, then remove your todo list and try restoring them by clicking `Load from localStorage`.
- Clock with Next.js [](https://codesandbox.io/s/nextjs-with-jotai-5ylrj)
An UTC time electronic clock implementation using Next.js and Jotai.
- Tic Tac Toe game [](https://codesandbox.io/s/jotai-tic-tac-6cg3h)
A game of tic tac toe implemented with Jotai.
- React Three Fiber demo [](https://codesandbox.io/s/jotai-r3f-fri9d)
A simple demo to use Jotai with react-three-fiber
---
### Core Atom (`docs/core/atom.mdx`)
---
title: atom
description: This doc describes core `jotai` bundle.
nav: 2.01
keywords: atom,primitive,derived,debug,label,onmount
---
## atom
The `atom` function is to create an atom config.
We call it "atom config" as it's just a definition and it doesn't yet hold a value.
We may also call it just "atom" if the context is clear.
An atom config is an immutable object. The atom config object doesn't hold a value. The atom value exists in a store.
To create a primitive atom (config), all you need is to provide an initial value.
```js
import { atom } from 'jotai'
const priceAtom = atom(10)
const messageAtom = atom('hello')
const productAtom = atom({ id: 12, name: 'good stuff' })
```
You can also create derived atoms. We have three patterns:
- Read-only atom
- Write-only atom
- Read-Write atom
To create derived atoms, we pass a read function and an optional write function.
```js
const readOnlyAtom = atom((get) => get(priceAtom) * 2)
const writeOnlyAtom = atom(
null, // it's a convention to pass `null` for the first argument
(get, set, update) => {
// `update` is any single value we receive for updating this atom
set(priceAtom, get(priceAtom) - update.discount)
// or we can pass a function as the second parameter
// the function will be invoked,
// receiving the atom's current value as its first parameter
set(priceAtom, (price) => price - update.discount)
},
)
const readWriteAtom = atom(
(get) => get(priceAtom) * 2,
(get, set, newPrice) => {
set(priceAtom, newPrice / 2)
// you can set as many atoms as you want at the same time
},
)
```
`get` in the read function is to read the atom value.
It's reactive and read dependencies are tracked.
`get` in the write function is also to read atom value, but it's not tracked.
Furthermore, it can't read unresolved async values in Jotai v1 API.
`set` in the write function is to write atom value.
It will invoke the write function of the target atom.
### Note about creating an atom in render function
Atom configs can be created anywhere, but referential equality is important.
They can be created dynamically too.
To create an atom in render function, `useMemo` or `useRef` is required to get a stable reference. If in doubt about using `useMemo` or `useRef` for memoization, use `useMemo`.
Otherwise, it can cause infinite loop with `useAtom`.
```js
const Component = ({ value }) => {
const valueAtom = useMemo(() => atom({ value }), [value])
// ...
}
```
### Signatures
```ts
// primitive atom
function atom(initialValue: Value): PrimitiveAtom
// read-only atom
function atom(read: (get: Getter) => Value): Atom
// writable derived atom
function atom(
read: (get: Getter) => Value,
write: (get: Getter, set: Setter, ...args: Args) => Result,
): WritableAtom
// write-only derived atom
function atom(
read: Value,
write: (get: Getter, set: Setter, ...args: Args) => Result,
): WritableAtom
```
- `initialValue`: the initial value that the atom will return until its value is changed.
- `read`: a function that's evaluated whenever the atom is read. The signature of `read` is `(get) => Value`, and `get` is a function that takes an atom config and returns its value stored in Provider as described below. Dependency is tracked, so if `get` is used for an atom at least once, the `read` will be reevaluated whenever the atom value is changed.
- `write`: a function mostly used for mutating atom's values, for a better description; it gets called whenever we call the second value of the returned pair of `useAtom`, the `useAtom()[1]`. The default value of this function in the primitive atom will change the value of that atom. The signature of `write` is `(get, set, ...args) => Result`. `get` is similar to the one described above, but it doesn't track the dependency. `set` is a function that takes an atom config and a new value which then updates the atom value in Provider. `...args` is the arguments that we receive when we call `useAtom()[1]`. `Result` is the return value of the `write` function.
```js
const primitiveAtom = atom(initialValue)
const derivedAtomWithRead = atom(read)
const derivedAtomWithReadWrite = atom(read, write)
const derivedAtomWithWriteOnly = atom(null, write)
```
There are two kinds of atoms: a writable atom and a read-only atom. Primitive atoms are always writable. Derived atoms are writable if the `write` is specified. The `write` of primitive atoms is equivalent to the `setState` of `React.useState`.
### `debugLabel` property
The created atom config can have an optional property `debugLabel`. The debug label is used to display the atom in debugging. See [Debugging guide](../guides/debugging.mdx) for more information.
Note: While, the debug labels don’t have to be unique, it’s generally recommended to make them distinguishable.
### `onMount` property
The created atom config can have an optional property `onMount`. `onMount` is a function which takes a function `setAtom` and returns `onUnmount` function optionally.
The `onMount` function is called when the atom is subscribed in the provider in the first time,
and `onUnmount` is called when it’s no longer subscribed.
In some cases (like [React strict mode](https://react.dev/reference/react/StrictMode)),
an atom can be unmounted and then mounted immediately.
```js
const anAtom = atom(1)
anAtom.onMount = (setAtom) => {
console.log('atom is mounted in provider')
setAtom(c => c + 1) // increment count on mount
return () => { ... } // return optional onUnmount function
}
const Component = () => {
// `onMount` will be called when the component is mounted in the following cases:
useAtom(anAtom)
useAtomValue(anAtom)
// however, in the following cases,
// `onMount` will not be called because the atom is not subscribed:
useSetAtom(anAtom)
useAtomCallback(
useCallback((get) => get(anAtom), []),
)
// ...
}
```
Calling `setAtom` function will invoke the atom’s `write`. Customizing `write` allows changing the behavior.
```js
const countAtom = atom(1)
const derivedAtom = atom(
(get) => get(countAtom),
(get, set, action) => {
if (action.type === 'init') {
set(countAtom, 10)
} else if (action.type === 'inc') {
set(countAtom, (c) => c + 1)
}
},
)
derivedAtom.onMount = (setAtom) => {
setAtom({ type: 'init' })
}
```
### Advanced API
Since Jotai v2, the `read` function has the second argument `options`.
#### `options.signal`
It uses [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) so that you can abort async functions.
Abort is triggered before new calculation (invoking `read` function) is started.
How to use it:
```ts
const readOnlyDerivedAtom = atom(async (get, { signal }) => {
// use signal to abort your function
})
const writableDerivedAtom = atom(
async (get, { signal }) => {
// use signal to abort your function
},
(get, set, arg) => {
// ...
},
)
```
The `signal` value is [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
You can check `signal.aborted` boolean value, or use `abort` event with `addEventListener`.
For `fetch` use case, we can simply pass `signal`.
See the below example for `fetch` usage.
#### `options.setSelf`
⚠️ This internal feature was only available in Jotai v2 and has been removed in v3.
## Stackblitz
)
export default App
```
---
### Core Provider (`docs/core/provider.mdx`)
---
title: Provider
description: This doc describes core `jotai` bundle.
nav: 2.04
keywords: provider,usestore,ssr
---
## Provider
The `Provider` component is to provide state for a component sub tree.
Multiple Providers can be used for multiple subtrees, and they can even be nested.
This works just like React Context.
If an atom is used in a tree without a Provider,
it will use the default state. This is so-called provider-less mode.
Providers are useful for three reasons:
1. To provide a different state for each sub tree.
2. To accept initial values of atoms.
3. To clear all atoms by remounting.
```jsx
const SubTree = () => (
)
```
### Signatures
```ts
const Provider: React.FC<{
store?: Store
}>
```
Atom configs don't hold values. Atom values reside in separate stores. A Provider is a component that contains a store and provides atom values under the component tree. A Provider works like React context provider. If you don't use a Provider, it works as provider-less mode with a default store. A Provider will be necessary if we need to hold different atom values for different component trees. Provider can take an optional prop `store`.
```jsx
const Root = () => (
)
```
### `store` prop
A Provider accepts an optional prop `store` that you can use for the Provider subtree.
#### Example
```jsx
const myStore = createStore()
const Root = () => (
)
```
## useStore
This hook returns a store within the component tree.
```jsx
const Component = () => {
const store = useStore()
// ...
}
```
---
### Core Store (`docs/core/store.mdx`)
---
title: Store
description: This doc describes core `jotai` bundle.
nav: 2.03
keywords: store,createstore,getdefaultstore,defaultstore
---
## createStore
This function is to create a new empty store.
The store can be used to pass in `Provider`.
The store has three methods: `get` for getting atom values,
`set` for setting atom values, and `sub` for subscribing to atom changes.
```jsx
const myStore = createStore()
const countAtom = atom(0)
myStore.set(countAtom, 1)
const unsub = myStore.sub(countAtom, () => {
console.log('countAtom value is changed to', myStore.get(countAtom))
})
// unsub() to unsubscribe
const Root = () => (
)
```
## getDefaultStore
This function returns a default store that is used in provider-less mode.
```js
const defaultStore = getDefaultStore()
```
---
### Core Use Atom (`docs/core/use-atom.mdx`)
---
title: useAtom
description: This doc describes core `jotai` bundle.
nav: 2.02
keywords: use,useatom,useatomvalue,useatomvalueraw,useatomvaluerawsync,usesetatom,atomvalue,setatom
---
## Choosing a hook
- Read and write an atom: `useAtom`
- Read an atom's value: `useAtomValue`
- Write an atom without reading it (avoids re-renders): `useSetAtom`
- Read without suspending on async atoms: `useAtomValueRaw`
- Same, with no risk of missing an update: `useAtomValueRawSync`
## useAtom
The `useAtom` hook is used to read an atom from the state.
The state can be seen as a WeakMap of atom configs and atom values.
The `useAtom` hook returns the atom value and an update function as a tuple,
just like React's `useState`.
It takes an atom config created with `atom()` as a parameter.
At the creation of the atom config, there is no value associated with it.
Only once the atom is used via `useAtom`, does the initial value get stored in the state.
If the atom is a derived atom, the read function is called to compute its initial value.
When an atom is no longer used, meaning all the components using it are unmounted
and the atom config no longer exists, the value in the state is garbage collected.
```js
const [value, setValue] = useAtom(anAtom)
```
The `setValue` takes just one argument, which will be passed
to the write function of the atom as the third parameter.
The end result depends on how the write function is implemented.
If the write function is not explicitly set, the atom will simply receive the value passed as a parameter to `setValue`.
**Note:** as mentioned in the _atom_ section, referential equality is important when creating atoms,
so you need to handle it properly otherwise it can cause infinite loops.
```js
const stableAtom = atom(0)
const Component = () => {
const [atomValue] = useAtom(atom(0)) // This will cause an infinite loop since the atom instance is being recreated in every render
const [atomValue] = useAtom(stableAtom) // This is fine
const [derivedAtomValue] = useAtom(
useMemo(
// This is also fine
() => atom((get) => get(stableAtom) * 2),
[],
),
)
}
```
**Note**: Remember that React is responsible for calling your component, meaning it has to be idempotent, ready to be called multiple times. You will often see an extra re-render even if no props or atoms have changed. An extra re-render without a commit is an expected behavior, since it is the default behavior of useReducer in React 18.
### Signatures
```ts
// primitive or writable derived atom
function useAtom(
atom: WritableAtom,
options?: { store?: Store },
): [Value, SetAtom]
// read-only atom
function useAtom(
atom: Atom,
options?: { store?: Store },
): [Value, never]
```
### How atom dependency works
Every time we invoke the "read" function, we refresh the dependencies and dependents.
> The read function is the first parameter of the atom.
> If B depends on A, it means that A is a dependency of B, and B is a dependent on A.
```js
const uppercaseAtom = atom((get) => get(textAtom).toUpperCase())
```
When you create the atom, the dependency will not be present. On first use, we run the read function and conclude that `uppercaseAtom` depends on `textAtom`. So `uppercaseAtom` is added to the dependents of `textAtom`.
When we re-run the read function of `uppercaseAtom` (because its `textAtom` dependency is updated),
the dependency is created again, which is the same in this case. We then remove stale dependents from `textAtom` and replace them with their latest versions.
### Atoms can be created on demand
While the basic examples here show defining atoms globally outside components,
there's no restrictions about where or when we can create an atom.
As long as we remember that atoms are identified by their object referential identity,
we can create them anytime.
If you create atoms in render functions, you would typically want to use
a hook like `useRef` or `useMemo` for memoization. If not, the atom would be re-created each time the component renders.
You can create an atom and store it with `useState` or even in another atom.
See an example in [issue #5](https://github.com/pmndrs/jotai/issues/5).
You can also cache atoms somewhere globally.
See [this example](https://twitter.com/dai_shi/status/1317653548314718208) or
[that example](https://github.com/pmndrs/jotai/issues/119#issuecomment-706046321).
Check [`atomFamily`](../utilities/family.mdx) in utils for parameterized atoms.
## useAtomValue
```jsx
const countAtom = atom(0)
const Counter = () => {
const setCount = useSetAtom(countAtom)
const count = useAtomValue(countAtom)
return (
<>
count: {count}
)
}
```
Similar to the `useSetAtom` hook, `useAtomValue` allows you to access a read-only atom. Nonetheless, it can also be used to access read-write atom's values.
Under the hood, `useAtomValue` is [`useAtomValueRaw`](#useatomvalueraw) plus React's `use()`: it resolves promises and suspends, instead of returning them as-is.
### A subtle mount-timing change in v3
In v2, `useAtomValue` always re-rendered once right after mounting, even without a value change. This caught updates that happened between the initial render and the subscription, for example a value written by a child's `useEffect` (which runs before the parent's).
In v3, that extra render is gone: `useAtomValue` only re-renders on an actual change. It's faster, but it can miss that specific kind of update until the next one. Use [`useAtomValueRawSync`](#useatomvaluerawsync) if you need to catch it.
## useAtomValueRaw
⚠️ This hook is only available since Jotai v3, and it's intended for advanced users.
```jsx
const countAtom = atom(0)
const Counter = () => {
const count = useAtomValueRaw(countAtom)
// ...
}
```
`useAtomValueRaw` is like `useAtomValue`, but it doesn't resolve promises: the value of an async atom is returned as a promise, and the component never suspends. It subscribes to the store in an effect, so it doesn't cause an extra re-render on initial mount. As a trade-off, a value change that happens between the initial render and the subscription is not picked up until the next change.
> "Raw" means the promise is returned without being consumed through React's `use()`.
## useAtomValueRawSync
⚠️ This hook is only available since Jotai v3, and it's intended for advanced users.
```jsx
const countAtom = atom(0)
const Counter = () => {
const count = useAtomValueRawSync(countAtom)
// ...
}
```
`useAtomValueRawSync` has the same signature as `useAtomValueRaw` and doesn't resolve promises either, but it's implemented with `useSyncExternalStore`. It avoids tearing and picks up values written during mount. As a trade-off, updates are always rendered synchronously without taking advantage of concurrent rendering features.
> "Sync" refers to `useSyncExternalStore`: rendering is always synchronous, with no concurrent-rendering support.
## useSetAtom
```jsx
const switchAtom = atom(false)
const SetTrueButton = () => {
const setCount = useSetAtom(switchAtom)
const setTrue = () => setCount(true)
return (
)
}
const SetFalseButton = () => {
const setCount = useSetAtom(switchAtom)
const setFalse = () => setCount(false)
return (
)
}
export default function App() {
const state = useAtomValue(switchAtom)
return (
State: {state.toString()}
...
```
```
**effect:** A function for observing and reacting to atom state changes.
### Usage
```js
import { atomEffect } from 'jotai-effect'
const logEffect = atomEffect((get, set) => {
set(logAtom, get(someAtom)) // Runs on mount or when someAtom changes
return () => {
set(logAtom, 'unmounting') // Cleanup on unmount
}
})
// activates the atomEffect while Component is mounted
function Component() {
useAtom(logEffect)
}
```
## withAtomEffect
`withAtomEffect` binds an effect to a clone of the target atom. The effect is active while the cloned atom is mounted.
### Signature
```ts
function withAtomEffect(targetAtom: Atom, effect: Effect): Atom
```
**targetAtom:** The atom to which the effect is bound.
**effect:** A function for observing and reacting to atom state changes.
**Returns:** An atom that is equivalent to the target atom but having a bound effect.
### Usage
```js
import { withAtomEffect } from 'jotai-effect'
const valuesAtom = withAtomEffect(atom(null), (get, set) => {
set(valuesAtom, get(countAtom))
return () => {
// cleanup
}
})
```
## Dependency Management
Aside from mount events, the effect runs when any of its dependencies change value.
- **Sync:**
All atoms accessed with `get` inside the effect are added to the atom's dependencies.
Example
```js
atomEffect((get, set) => {
// updates whenever `anAtom` changes value
get(anAtom)
})
```
- **Async:**
Asynchronous `get` calls do not add dependencies.
Example
```js
atomEffect((get, set) => {
setTimeout(() => {
// does not add `anAtom` as a dependency
get(anAtom)
})
})
```
- **Cleanup:**
`get` calls in cleanup do not add dependencies.
Example
```js
atomEffect((get, set) => {
return () => {
// does not add `anAtom` as a dependency
get(anAtom)
}
})
```
- **Dependency Map Recalculation:**
Dependencies are recalculated on every run.
Example
```js
atomEffect((get, set) => {
if (get(isEnabledAtom)) {
// `isEnabledAtom` and `anAtom` are dependencies
const aValue = get(anAtom)
} else {
// `isEnabledAtom` and `anotherAtom` are dependencies
const anotherValue = get(anotherAtom)
}
})
```
## Effect Behavior
- **Executes Synchronously:**
`effect` runs synchronous in the current task after synchronous evaluations complete.
Example
```js
const logCounts = atomEffect((get, set) => {
set(logAtom, `count is ${get(countAtom)}`)
})
const actionAtom = atom(null, (get, set) => {
get(logAtom) // 'count is 0'
set(countAtom, (value) => value + 1)
get(logAtom) // 'count is 0' - the effect runs once the write function completes
})
store.sub(logCounts, () => {})
store.set(actionAtom)
store.get(logAtom) // 'count is 1' - the effect ran before `store.set` returned
```
- **Batched Updates:**
Multiple synchronous updates are batched as a single atomic transaction.
Example
```js
const tensAtom = atom(0)
const onesAtom = atom(0)
const updateTensAndOnes = atom(null, (get, set) => {
set(tensAtom, (value) => value + 1)
set(onesAtom, (value) => value + 1)
})
const combos = atom([])
const effectAtom = atomEffect((get, set) => {
const value = get(tensAtom) * 10 + get(onesAtom)
set(combos, (arr) => [...arr, value])
})
store.sub(effectAtom, () => {})
store.set(updateTensAndOnes)
store.get(combos) // [00, 11]
```
- **Resistant to Infinite Loops:**
`atomEffect` avoids rerunning when it updates a value that it is watching.
Example
```js
atomEffect((get, set) => {
get(countAtom)
set(countAtom, (value) => value + 1) // Will not loop
})
```
- **Cleanup Function:**
The cleanup function is invoked on unmount or before re-evaluation.
Example
```js
atomEffect((get, set) => {
const intervalId = setInterval(() => set(clockAtom, Date.now()))
return () => clearInterval(intervalId)
})
```
- **Idempotency:**
`atomEffect` runs once per state change, regardless of how many times it is referenced.
Example
```js
let i = 0
const effectAtom = atomEffect(() => {
get(countAtom)
i++
})
store.sub(effectAtom, () => {})
store.sub(effectAtom, () => {})
store.set(countAtom, (value) => value + 1)
console.log(i) // 1
```
- **Conditionally Running Effects:**
`atomEffect` only runs when mounted.
Example
```js
atom((get) => {
if (get(isEnabledAtom)) {
get(effectAtom)
}
})
```
- **Supports Peek:**
Use `get.peek` to read atom data without subscribing.
Example
```js
const countAtom = atom(0)
atomEffect((get, set) => {
const count = get.peek(countAtom) // Will not add `countAtom` as a dependency
})
```
- **Supports Recursion:**
Recursion is supported with `set.recurse` but not in cleanup.
Example
```js
atomEffect((get, set) => {
const count = get(countAtom)
if (count % 10 === 0) {
return
}
set.recurse(countAtom, (value) => value + 1)
})
```
---
### Extensions Immer (`docs/extensions/immer.mdx`)
---
title: Immer
description: This doc describes Immer extension.
nav: 4.04
keywords: immer
---
### Install
You have to install `immer` and `jotai-immer` to use this feature.
```
npm install immer jotai-immer
```
## atomWithImmer
`atomWithImmer` creates a new atom similar to the regular [`atom`](../core/atom.mdx) with a different `writeFunction`. In this bundle, we don't have read-only atoms, because the point of these functions is the immer produce(mutability) function.
The signature of writeFunction is `(get, set, update: (draft: Draft) => void) => void`.
```jsx
import { useAtom } from 'jotai'
import { atomWithImmer } from 'jotai-immer'
const countAtom = atomWithImmer({ value: 0 })
const Counter = () => {
const [count] = useAtom(countAtom)
return count: {count.value}
}
const Controls = () => {
const [, setCount] = useAtom(countAtom)
// setCount === update : (draft: Draft) => void
const inc = () =>
setCount((draft) => {
++draft.value
})
return
}
```
### Examples
Check this example with atomWithImmer:
) => void
const inc = () =>
setCount((draft) => {
++draft.value
})
return
}
```
### Examples
Check this example with withImmer:
) => void
const inc = () =>
setCount((draft) => {
++draft.value
})
return
}
```
It would be better if you don't use `withImmer` and `atomWithImmer` with `useImmerAtom` because they provide the immer-like `writeFunction` and we don't need to create a new one.
You can use `useSetImmerAtom` if you need only the setter part of `useImmerAtom`.
### Examples
Check this example with useImmerAtom:
-
-
-
)
}
```
### Stackblitz
```
So basically, we started with a `PrimitiveAtom<{a: number}>`, which has a getter and a setter, and then used `focusAtom` to zoom in on the `a`-property of
the `baseAtom`, and got a `PrimitiveAtom`. What is noteworthy here is that this `derivedAtom` is not only a getter, it is also a setter. If `derivedAtom` is updated, then equivalent update is done on the `baseAtom`.
The example below is simple, but it's a starting point. `focusAtom` supports many kinds of optics, including `Lens`, `Prism`, `Isomorphism`.
To see more advanced optics, please see the example at: https://github.com/akheron/optics-ts
### Example
```jsx
import { atom } from 'jotai'
import { focusAtom } from 'jotai-optics'
const objectAtom = atom({ a: 5, b: 10 })
const aAtom = focusAtom(objectAtom, (optic) => optic.prop('a'))
const bAtom = focusAtom(objectAtom, (optic) => optic.prop('b'))
const Controls = () => {
const [a, setA] = useAtom(aAtom)
const [b, setB] = useAtom(bAtom)
return (
Value of a: {a}
Value of b: {b}
)
}
```
#### Stackblitz
{JSON.stringify(status, null, 2)}
)
}
```
### atomWithMutationState usage
`atomWithMutationState` creates a new atom that gives you access to all mutations in the [`MutationCache`](https://tanstack.com/query/v5/docs/react/reference/useMutationState).
```jsx
const mutationStateAtom = atomWithMutationState((get) => ({
filters: {
mutationKey: ['posts'],
},
}))
```
### Suspense
jotai-tanstack-query can also be used with React's Suspense.
### atomWithSuspenseQuery usage
```jsx
import { atom, useAtom } from 'jotai'
import { atomWithSuspenseQuery } from 'jotai-tanstack-query'
const idAtom = atom(1)
const userAtom = atomWithSuspenseQuery((get) => ({
queryKey: ['users', get(idAtom)],
queryFn: async ({ queryKey: [, id] }) => {
const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
return res.json()
},
}))
const UserData = () => {
const [{ data }] = useAtom(userAtom)
return {JSON.stringify(data)}
}
```
### atomWithSuspenseInfiniteQuery usage
```jsx
import { atom, useAtom } from 'jotai'
import { atomWithSuspenseInfiniteQuery } from 'jotai-tanstack-query'
const postsAtom = atomWithSuspenseInfiniteQuery(() => ({
queryKey: ['posts'],
queryFn: async ({ pageParam }) => {
const res = await fetch(`https://jsonplaceholder.typicode.com/posts?_page=${pageParam}`)
return res.json()
},
getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
initialPageParam: 1,
}))
const Posts = () => {
const [{ data, fetchNextPage, isPending, isError, isFetching }] =
useAtom(postsAtom)
return (
<>
{data.pages.map((page, index) => (
{page.map((post: any) => (
{post.title}
))}
))}
)
}
```
### Referencing the same instance of Query Client in your project
Perhaps you have some custom hooks in your project that utilises the `useQueryClient()` hook to obtain the `QueryClient` object and call its methods.
To ensure that you reference the same `QueryClient` object, be sure to wrap the root of your project in a `` and initialise `queryClientAtom` with the same `queryClient` value you provided to `QueryClientProvider`.
Without this step, `useQueryAtom` will reference a separate `QueryClient` from any hooks that utilise the `useQueryClient()` hook to get the queryClient.
Alternatively, you can specify your `queryClient` with `getQueryClient` parameter.
#### Example
In the example below, we have a mutation hook, `useTodoMutation` and a query `todosAtom`.
We included an initialisation step in our root `` node.
Although they reference methods same query key (`'todos'`), the `onSuccess` invalidation in `useTodoMutation` will not trigger **if the `Provider` initialisation step was not done.**
This will result in `todosAtom` showing stale data as it was not prompted to refetch.
⚠️ Note: When using **Typescript**, it is recommended to use a Map when passing the queryClient value to useHydrateAtoms. You can find a working example in the [Initializing State on Render docs](https://jotai.org/docs/guides/initialize-atom-on-render#using-typescript)
```jsx
import { Provider } from 'jotai/react'
import { useHydrateAtoms } from 'jotai/react/utils'
import {
useMutation,
useQueryClient,
QueryClient,
QueryClientProvider,
} from '@tanstack/react-query'
import { atomWithQuery, queryClientAtom } from 'jotai-tanstack-query'
const queryClient = new QueryClient()
const HydrateAtoms = ({ children }) => {
useHydrateAtoms([[queryClientAtom, queryClient]])
return children
}
export const App = () => {
return (
{/*
This Provider initialisation step is needed so that we reference the same
queryClient in both atomWithQuery and other parts of the app. Without this,
our useQueryClient() hook will return a different QueryClient object
*/}
)
}
export const todosAtom = atomWithQuery((get) => {
return {
queryKey: ['todos'],
queryFn: () => fetch('/todos'),
}
})
export const useTodoMutation = () => {
const queryClient = useQueryClient()
return useMutation(
async (body: todo) => {
await fetch('/todo', { Method: 'POST', Body: body })
},
{
onSuccess: () => {
void queryClient.invalidateQueries(['todos'])
},
onError,
}
)
}
```
### SSR support
All atoms can be used within the context of a server side rendered app, such as a next.js app or Gatsby app. You can [use both options](https://tanstack.com/query/v5/docs/framework/react/guides/ssr) that React Query supports for use within SSR apps, [hydration](https://tanstack.com/query/v5/docs/react/guides/ssr#using-the-hydration-apis) or [`initialData`](https://tanstack.com/query/v5/docs/react/guides/ssr#get-started-fast-with-initialdata).
### Error handling
Fetch error will be thrown and can be caught with ErrorBoundary.
Refetching may recover from a temporary error.
See [a working example](https://codesandbox.io/s/4gfp6z) to learn more.
### Devtools
In order to use the Devtools, you need to install it additionally.
```bash
npm install @tanstack/react-query-devtools
```
All you have to do is put the `
)
}
```
## Migrate to v0.8.0
### Change in atom signature
All atom signatures have changed to be more consistent with TanStack Query.
v0.8.0 returns only a single atom, instead of a tuple of atoms, and hence the name change from `atomsWithSomething` to`atomWithSomething`.
```diff
- const [dataAtom, statusAtom] = atomsWithSomething(getOptions, getQueryClient)
+ const dataAtom = atomWithSomething(getOptions, getQueryClient)
```
### Simplified Return Structure
In the previous version of `jotai-tanstack-query`, the query atoms `atomsWithQuery` and `atomsWithInfiniteQuery` returned a tuple of atoms: `[dataAtom, statusAtom]`. This design separated the data and its status into two different atoms.
#### atomWithQuery and atomWithInfiniteQuery
- `dataAtom` was used to access the actual data (`TData`).
- `statusAtom` provided the status object (`QueryObserverResult`), which included additional attributes like `isPending`, `isError`, etc.
In v0.8.0, they have been replaced by `atomWithQuery` and `atomWithInfiniteQuery` to return only a single `dataAtom`. This `dataAtom` now directly provides the `QueryObserverResult`, aligning it closely with the behavior of Tanstack Query's bindings.
To migrate to the new version, replace the separate `dataAtom` and `statusAtom` usage with the unified `dataAtom` that now contains both data and status information.
```diff
- const [dataAtom, statusAtom] = atomsWithQuery(/* ... */);
- const [data] = useAtom(dataAtom);
- const [status] = useAtom(statusAtom);
+ const dataAtom = atomWithQuery(/* ... */);
+ const [{ data, isPending, isError }] = useAtom(dataAtom);
```
#### atomWithMutation
Similar to `atomsWithQuery` and `atomsWithInfiniteQuery`, `atomWithMutation` also returns a single atom instead of a tuple of atoms. The return type of the atom value is `MutationObserverResult`.
```diff
- const [, postAtom] = atomsWithMutation(/* ... */);
- const [post, mutate] = useAtom(postAtom); // Accessing mutation status from post; and mutate() to execute the mutation
+ const postAtom = atomWithMutation(/* ... */);
+ const [{ data, error, mutate }] = useAtom(postAtom); // Accessing mutation result and mutate method from the same atom
```
### Examples
#### Basic demo
{data.countries.map(({ name }) => (
- {name}
))}
)
}
const HydrateAtoms = ({ children }) => {
useHydrateAtoms([[environmentAtom, myEnvironment]])
return children
}
const App = () => {
return (
)
}
```
#### Examples
` 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.
### Install
```
npm install jotai-scope
```
### Counter Example
```tsx
import { atom, useAtom } from 'jotai'
import { ScopeProvider } from 'jotai-scope'
const countAtom = atom(0)
function Counter() {
const [count, setCount] = useAtom(countAtom)
const [anotherCount, setAnotherCount] = useAtom(anotherCountAtom)
return (
<>
count: {count}
another count: {anotherCount}
)
}
function App() {
return (
)
}
```
)
}
```
## `bunshi` (formerly `jotai-molecules`)
Jotai atoms provide a basic solution to optimize re-renders.
Atoms defined globally can depend on other atoms,
but they can't depend on props and state within a component tree.
It's possible to define atoms within a component tree,
but then you would need to pass those atoms in some ways
(for example, [atoms-in-atom](../guides/atoms-in-atom.mdx).)
[bunshi](https://github.com/saasquatch/bunshi) is
a third-party library to help such use cases.
See [Motivation](https://github.com/saasquatch/bunshi/tree/v1.1.1#motivation) for more details.
### Install
```
npm install bunshi
```
### Counter Example
```jsx
import { atom, useAtom } from 'jotai'
import { molecule, useMolecule, createScope, ScopeProvider } from 'bunshi/react'
const InitialCountScope = createScope({ initialCount: 0 })
const countMolecule = molecule((getMol, getScope) => {
const { initialCount } = getScope(InitialCountScope)
return atom(initialCount)
})
function Counter() {
const countAtom = useMolecule(countMolecule)
const [count, setCount] = useAtom(countAtom)
return (
{count}
)
}
function App() {
return (
With initial value 1
With initial value 2
Default
({
links: [
httpLink({
url: myUrl,
}),
],
})
const idAtom = atom('foo')
const queryAtom = trpc.bar.baz.atomWithQuery((get) => get(idAtom))
```
### atomWithQuery
`...atomWithQuery` creates a new atom with "query". It internally uses [Vanilla Client](https://trpc.io/docs/vanilla)'s `...query` procedure.
```tsx
import { atom, useAtom } from 'jotai'
import { httpLink } from '@trpc/client'
import { createTRPCJotai } from 'jotai-trpc'
import { trpcPokemonUrl } from 'trpc-pokemon'
import type { PokemonRouter } from 'trpc-pokemon'
const trpc = createTRPCJotai({
links: [
httpLink({
url: trpcPokemonUrl,
}),
],
})
const NAMES = [
'bulbasaur',
'ivysaur',
'venusaur',
'charmander',
'charmeleon',
'charizard',
'squirtle',
'wartortle',
'blastoise',
]
const nameAtom = atom(NAMES[0])
const pokemonAtom = trpc.pokemon.byId.atomWithQuery((get) => get(nameAtom))
const Pokemon = () => {
const [data, refresh] = useAtom(pokemonAtom)
return (
ID: {data.id}
Height: {data.height}
Weight: {data.weight}
)
}
```
#### Examples
// Will be enforced dynamically based on generic/typed-document-node types.
getVariables?: (get: Getter) => Variables
getContext?: (get: Getter) => Partial
getPause?: (get: Getter) => boolean
getClient?: (get: Getter) => Client
}
type AtomWithMutationOptions<
Data = unknown,
Variables extends AnyVariables = AnyVariables,
> = {
query: DocumentInput
getClient?: (get: Getter) => Client
}
// Subscription type is the same as AtomWithQueryOptions
```
### Disable suspense
Usage of `import { loadable } from "jotai/utils"` is preferred instead as proven more stable. However is you still want that
here is how you do it:
```tsx
import { suspenseAtom } from 'jotai-urql'
export const App = () => {
// We disable suspense for the entire app
useHydrateAtoms([[suspenseAtom, false]])
return ` and initialise clientAtom with the same urqlClient value you provided to UrqlProvider.
Without this step, you may end up specifying client each time when you use `atomWithQuery`. Now you can just ignore the optional `getClient` parameter, and it will use the client from the context.
```jsx
import { Suspense } from 'react'
import { Provider } from 'jotai/react'
import { useHydrateAtoms } from 'jotai/react/utils'
import { clientAtom } from 'jotai-urql'
import {
createClient,
cacheExchange,
fetchExchange,
Provider as UrqlProvider,
} from 'urql'
const urqlClient = createClient({
url: 'https://countries.trevorblades.com/',
exchanges: [cacheExchange, fetchExchange],
fetchOptions: () => {
return { headers: {} }
},
})
const HydrateAtoms = ({ children }) => {
useHydrateAtoms([[clientAtom, urqlClient]])
return children
}
export default function MyApp({ Component, pageProps }) {
return (
)
}
```
---
### Extensions Valtio (`docs/extensions/valtio.mdx`)
---
title: Valtio
description: This doc describes Valtio extension.
nav: 4.98
keywords: valtio,proxy
published: false
---
Jotai's state resides in React, but sometimes it would be nice
to interact with the world outside React.
Valtio provides a proxy interface that can be used to store some values
and sync with atoms in Jotai.
This only uses the vanilla api of valtio.
### Install
You have to install `valtio` and `jotai-valtio` to use this feature.
```
npm install valtio jotai-valtio
```
## atomWithProxy
`atomWithProxy` creates a new atom with valtio proxy.
It's two-way binding and you can change the value from both ends.
```jsx
import { useAtom } from 'jotai'
import { atomWithProxy } from 'jotai-valtio'
import { proxy } from 'valtio/vanilla'
const proxyState = proxy({ count: 0 })
const stateAtom = atomWithProxy(proxyState)
const Counter = () => {
const [state, setState] = useAtom(stateAtom)
return (
<>
count: {state.count}
)
}
```
### Parameters
```
atomWithProxy(proxyObject, options?)
```
**proxyObject** (required): the Valtio proxy object you want to derive the atom from
**options.sync** (optional): makes the atom update synchronously instead of waiting for batched updates, similar to [`valtio/useSnapshot`](https://github.com/pmndrs/valtio#update-synchronously). This will result in more renders, but have more guarantees that it syncs with other Jotai atoms.
```
atomWithProxy(proxyObject, { sync: true })
```
### Examples
)
}
```
Alternatively, you could avoid the inherent suspending that Jotai does for you, by wrapping your atoms with the [`loadable` API](../utilities/async.mdx#loadable), or by reading the atom with [`useAtomValueRaw`](../core/use-atom.mdx#useatomvalueraw) instead of `useAtomValue`.
If another atom uses an async atom, it will return a promise. So, we need to make the atom also async.
```js
const anotherAtom = atom(async (get) => (await get(asyncAtom)) / 2)
```
This also applies to an atom with write function.
```js
const asyncAtom = atom(async (get) => ...)
const writeAtom = atom(null, async (get, set, payload) => {
await get(asyncAtom)
// ...
})
```
## Async write atom
Async write atoms are another kind of async atom. When the `write` function of atom returns a promise.
```js
const countAtom = atom(1)
const asyncIncrementAtom = atom(null, async (get, set) => {
// await something
set(countAtom, get(countAtom) + 1)
})
const Component = () => {
const [, increment] = useAtom(asyncIncrementAtom)
const handleClick = () => {
increment()
}
// ...
}
```
## Async sometimes
An interesting pattern that can be achieved with Jotai is switching from async to sync to trigger suspending when wanted.
```js
const request = async () =>
fetch('https://jsonplaceholder.typicode.com/todos/1').then((res) =>
res.json(),
)
const baseAtom = atom(0)
const Component = () => {
const [value, setValue] = useAtom(baseAtom)
const handleClick = () => {
setValue(request()) // Will suspend until request resolves
}
// ...
}
```
### Usage in TypeScript
In TypeScript `atom(0)` is inferred as `PrimitiveAtom`. It cannot accept `Promise` as a value so preceding code would not typecheck. To accommodate for that you need to type your atom explicitly and add `Promise` as accepted value.
```ts
const baseAtom = atom>(0) // Will accept sync and async values
```
## Async forever
Sometimes you may want to suspend until an unpredetermined moment (or never).
```js
const baseAtom = atom(new Promise(() => {})) // Will be suspend until set otherwise
```
## Suspense
Async support is first class in Jotai. It fully leverages React Suspense at its core.
> Technically, Suspense usage other than React.lazy is still unsupported / undocumented in React 17. If this is blocking, so you can still use the [`loadable` API](../utilities/async.mdx) to avoid suspending
To use async atoms, you need to wrap your component tree with ``.
> If you have a ``, place **at least one** `` inside said ``; otherwise, it may cause an endless loop while rendering the components.
```jsx
const App = () => (
)
```
Having more ``s in the component tree is also possible and must be considered to profit from Jotai inherent handling at best.
---
### Guides Atoms In Atom (`docs/guides/atoms-in-atom.mdx`)
---
title: Atoms in atom
nav: 8.12
---
`atom()` creates an atom config, which is an object, but it doesn't hold a value.
Atom configs don't have string keys and we identify them with referential equality.
In other words, we can use an atom config like a key.
### Storing an atom config in useState
First things first, we can store an atom config in useState.
```jsx
const Component = ({ atom1, atom2 }) => {
const [selectedAtom, setSelectedAtom] = useState(atom1)
const [value] = useAtom(selectedAtom)
return (
Selected value: {value}
)
}
```
Note that we can pass atoms configs as props.
It might not make any sense, but we could create an atom config on demand.
```jsx
const Component = () => {
const [currentAtom, setCurrentAtom] = useState(() => atom(0))
const [count, setCount] = useAtom(currentAtom)
return (
Count: {count}
)
}
```
### Storing an atom config in atom
Likewise, we can store an atom config as a value of another atom.
```jsx
const firstNameAtom = atom('Tanjiro')
const lastNameAtom = atom('Kamado')
const showingNameAtom = atom(firstNameAtom)
const Component = () => {
const [nameAtom, setNameAtom] = useAtom(showingNameAtom)
const [name] = useAtom(nameAtom)
return (
Name: {name}
)
}
```
It's possible to create a derived atom.
```js
const derivedNameAtom = atom((get) => {
const nameAtom = get(showingNameAtom)
return get(nameAtom)
})
// Or a shorter version
const derivedNameAtom = atom((get) => get(get(showingNameAtom)))
```
To avoid confusing what is in atoms, naming atoms explicitly would be important.
Also, TypeScript type information would be helpful.
### Storing an array of atom configs in atom
Finally, the atoms in atom pattern is to store an array of atom config into an atom.
```jsx
const countsAtom = atom([atom(1), atom(2), atom(3)])
const Counter = ({ countAtom }) => {
const [count, setCount] = useAtom(countAtom)
return (
{count}
)
}
const Parent = () => {
const [counts, setCounts] = useAtom(countsAtom)
const addNewCount = () => {
const newAtom = atom(0)
setCounts((prev) => [...prev, newAtom])
}
return (
{counts.map((countAtom) => (
` with number being internal `key` assigned to each atom automatically. But you can add labels to atoms to help you distinguish them more easily with `debugLabel`.
```js
const countAtom = atom(0)
// countAtom's debugLabel by default is 'atom1'
if (process.env.NODE_ENV !== 'production') {
countAtom.debugLabel = 'count'
// debugLabel is 'count' now
}
```
Jotai provides both a Babel and a SWC plugin, that adds a debugLabel automatically to every atom, which makes things easier for us. For more info, check out [jotai-babel](https://github.com/jotaijs/jotai-babel) and [@swc-jotai/debug-label](https://github.com/pmndrs/jotai/blob/main/docs/tools/swc.mdx)
## Using React Dev Tools
You can use [React Dev Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
to inspect Jotai state. To achieve that [useDebugValue](https://react.dev/reference/react/useDebugValue)
is used inside custom hooks. Keep in mind that it only works in dev mode
(such as `NODE_ENV === 'development'`).
### useAtom
`useAtom` calls `useDebugValue` for atom values, so if you select the component that consumes Jotai atoms in React Dev Tools, you would see "Atom" hooks for each atom that is used in the component along with the value it has right now.
### useAtomsDebugValue
`useAtomsDebugValue` catches all atoms in a component tree under Provider (or an entire tree for Provider-less mode), and `useDebugValue` for all atoms values.
If you navigate to the component that has `useAtomsDebugValue` in the React Dev Tools, we can see a custom hook "AtomsDebugValue" which allows you to see all atom values and their dependents.
One use case is to put the hook just under the `Provider` component:
```jsx
const DebugAtoms = () => {
useAtomsDebugValue()
return null
}
const Root = () => (
)
```
## Using Redux DevTools
You can also use [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
to inspect atoms, with many features like Time-travelling and value dispatching.
### [useAtomDevtools](https://jotai.org/docs/api/devtools#use-atom-devtools)
> `useAtomDevtools` is a React hook that manages ReduxDevTools extension for a particular atom.
If you have a specific atom in mind that you may want to debug, `useAtomDevtools` can be a good option.
```js
const countAtom = atom(0)
// setting countAtom.debugLabel is recommended if we have more atoms
function Counter() {
const [count, setCount] = useAtom(countAtom)
useAtomDevtools(countAtom)
}
```
Now if we try `setCount`, we can see that the Redux Dev Tools logs those changes immediately.
#### Time travel
Sometimes we need to switch to a specific value of our atoms' state, with Time travelling this is possible.
You can hover on each action you see in the devtools and see the **Jump** option there, with clicking it you'd be able to switch to that specific value.
#### Pause
If we don't record changes on atoms, we can stop watching those using the **Pausing** feature.
#### Dispatch
It's possible to set values on atoms with the **Dispatch** feature. You can do that by clicking on the **Show Dispatcher** button.
This would set the `countAtoms`'s value to `5`.
> We should note that the value will be parsed by JSON.parse, so pass supported values.
### [useAtomsDevtools](../tools/devtools.mdx)
> `useAtomsDevtools` is a catch-all version of `useAtomDevtools` where it shows all atoms in the store instead of showing a specific one.
We'd recommend this hook if you want to keep track of all of your atoms in one place. It means every action on every atom that is placed in the bottom of this hook (in the React tree) will be caught by the Redux Dev Tools.
Every feature of `useAtomDevtools` is supported in this hook, but there's an extra feature, which includes giving more information about atoms dependents like:
```json
{
"values": {
"atom1:count": 0,
"atom2:doubleCount": 0,
"atom3:half": 0,
"atom4:sum": 0
},
"dependents": {
"atom1:count": ["atom1:count", "atom2:doubleCount", "atom4:sum"],
"atom2:doubleCount": ["atom3:half", "atom4:sum"],
"atom3:half": ["atom4:sum"],
"atom4:sum": []
}
}
```
## Frozen Atoms
To find bugs where you accidentally tried to mutate objects stored in atoms you
could use `freezeAtom` or `freezeAtomCreator`from `jotai/utils` bundle.
Which returns atoms value that is deeply freezed with `Object.freeze`.
### freezeAtom
```ts
freezeAtom(anAtom): AtomType
```
`freezeAtom` takes an existing atom and make it "frozen".
It returns the same atom.
The atom value will be deeply frozen by `Object.freeze`.
It is useful to find bugs where you unintentionally tried
to change objects (states) which can lead to unexpected behavior.
You may use `freezeAtom` with all atoms to prevent this situation.
#### Parameters
**anAtom** (required): An atom you wish to freeze.
#### Examples
```js
import { atom } from 'jotai'
import { freezeAtom } from 'jotai/utils'
const objAtom = freezeAtom(atom({ count: 0 }))
```
### freezeAtomCreator
If you need, you can define a factory for `freezeAtom`.
```ts
import { freezeAtom } from 'jotai/utils'
export function freezeAtomCreator<
CreateAtom extends (...args: unknown[]) => Atom,
>(createAtom: CreateAtom): CreateAtom {
return ((...args: unknown[]) => freezeAtom(createAtom(...args))) as never
}
```
---
### Guides Initialize Atom On Render (`docs/guides/initialize-atom-on-render.mdx`)
---
title: Initializing state on render
description: How to initialize atom state on initial render
nav: 8.13
---
There are times when you need to create an reusable component which uses atoms.
These atoms' initial state are determined by the props passed to the component.
Below is a basic example illustrating how you can use `Provider` and its prop, `initialValues`, to initialize state.
### Basic Example
> CodeSandbox link: [codesandbox](https://codesandbox.io/s/init-atoms-with-usehydrateatoms-nryk1w).
Consider a basic example where you have a reusable `TextDisplay` component that allows you to display and update plain text.
This component has two child components, `PrettyText` and `UpdateTextInput`.
- `PrettyText` displays the text in blue.
- `UpdateTextInput` is an input field which updates the text value.
As opposed to passing `text` as a prop in the two child components, you decided that the `text` state should be shared between components as an atom.
To make `TextDisplay` component reusable, we take in a prop `initialTextValue`, which determines the initial state of the `text` atom.
To tie `initialTextValue` to `textAtom`, we wrap the child components in a component where we create a new store and pass it to a `Provider` component.
```jsx
const textAtom = atom('')
const PrettyText = () => {
const [text] = useAtom(textAtom)
return (
<>
{text}
)
}
const UpdateTextInput = () => {
const [text, setText] = useAtom(textAtom)
const handleInputChange = (e) => {
setText(e.target.value)
}
return (
<>
)
}
const HydrateAtoms = ({ initialValues, children }) => {
// initialising on state with prop on render here
useHydrateAtoms(initialValues)
return children
}
export const TextDisplay = ({ initialTextValue }) => (
)
```
Now, we can easily reuse `TextDisplay` component with different initial text values despite them referencing the "same" atom.
```jsx
export default function App() {
return (
)
}
//This component contains all the states and the logic
function Component() {
const testAtomValue = useAtomValue(testAtom)
return {testAtomValue}
}
function AtomsHydrator({
atomValues,
children,
}: {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
atomValues: Iterable<
readonly [WritableAtom, unknown]
>
children: ReactNode
}) {
useHydrateAtoms(new Map(atomValues))
return children
}
```
---
### Guides Migrating To V2 Api (`docs/guides/migrating-to-v2-api.mdx`)
---
title: v2 API migration
description: New "Async" API
nav: 8.0
---
RFC: https://github.com/pmndrs/jotai/discussions/1514
Jotai v1 is released at June 2022, and there has been various feedbacks.
React also proposes first-class support for promises.
Jotai v2 will have a new API.
Unfortunately, there are some breaking changes along with new features.
### What are new features
#### Vanilla library
Jotai comes with vanilla (non-React) functions
and React functions separately.
They are provided from alternate entry points like `jotai/vanilla`.
#### Store API
Jotai exposes store interface so that you can directly manipulate atom values.
```js
import { createStore } from 'jotai' // or from 'jotai/vanilla'
const store = createStore()
store.set(fooAtom, 'foo')
console.log(store.get(fooAtom)) // prints "foo"
const unsub = store.sub(fooAtom, () => {
console.log('fooAtom value in store is changed')
})
// call unsub() to unsubscribe.
```
You can also create your own React Context to pass a store.
#### More flexible atom `write` function
The write function can accept multiple arguments,
and return a value.
```js
atom(
(get) => get(...),
(get, set, arg1, arg2, ...) => {
...
return someValue
}
)
```
### What are breaking
#### Async atoms are no longer special
Async atoms are just normal atoms with promise values.
Atoms getter functions don't resolve promises.
On the other hand, `useAtom` hook continues to resolve promises.
Some utils like `splitAtom` expects sync atoms,
and won't work with async atoms.
#### Writable atom type is changed (TypeScript only)
```ts
// Old
WritableAtom>
// New
WritableAtom
```
In general, we should avoid using `WritableAtom` type directly.
#### Some functions are dropped
- Provider's `initialValues` prop is removed, because `store` is more flexible.
- Provider's scope props is removed, because you can create own context.
- `abortableAtom` util is removed, because the feature is included by default
- `waitForAll` util is removed, because `Promise.all` just works
### Migration guides
#### Async atoms
`get` function for read function of async atoms
doesn't resolve promises, so you have to put `await` or `.then()`.
In short, the change is something like the following.
(If you are TypeScript users, types will tell where to changes.)
##### Previous API
```js
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom((get) => get(asyncAtom).toUppercase())
```
##### New API
```js
const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom(async (get) => (await get(asyncAtom)).toUppercase())
// or
const derivedAtom = atom((get) => get(asyncAtom).then((x) => x.toUppercase()))
```
#### Provider's `initialValues` prop
##### Previous API
```jsx
const countAtom = atom(0)
// in component
...
```
##### New API
```jsx
const countAtom = atom(0)
const HydrateAtoms = ({ initialValues, children }) => {
useHydrateAtoms(initialValues)
return children
}
// in component
...
```
#### Provider's `scope` prop
##### Previous API
```jsx
const myScope = Symbol()
// Parent component
...
// Child component
useAtom(..., myScope)
```
##### New API
```jsx
const MyContext = createContext()
const store = createStore()
// Parent component
...
// Child Component
const store = useContext(MyContext)
useAtom(..., { store })
```
#### `abortableAtom` util
You no longer need the previous `abortableAtom` util,
because it's now supported with the normal `atom`.
##### Previous API
```js
const asyncAtom = abortableAtom(async (get, { signal }) => {
...
}
```
##### New API
```js
const asyncAtom = atom(async (get, { signal }) => {
...
}
```
#### `waitForAll` util
You no longer need the previous `waitForAll` util,
because we can use native Promise APIs.
##### Previous API
```js
const allAtom = waitForAll([fooAtom, barAtom])
```
##### New API
```js
const allAtom = atom((get) => Promise.all([get(fooAtom), get(barAtom)]))
```
Note that creating an atom in render function can cause [infinite loop](../core/atom.mdx#note-about-creating-an-atom-in-render-function)
#### `splitAtom` util (or some other utils) with async atoms
`splitAtom` util only accepts sync atoms.
You need to unwrap async atoms before passing.
This applies to some other utils like `atomsWithQuery` from `jotai-tanstack-query`.
##### Previous API
```js
const splittedAtom = splitAtom(asyncArrayAtom)
```
##### New API
```js
const splittedAtom = splitAtom(unwrap(asyncArrayAtom, () => []))
```
As of writing, `unwrap` is unstable and not documented.
You can instead use `loadable`, which gives more control on loading status.
If you need to use ``, atoms-in-atom pattern would help.
For more information, refer the following discussions:
- https://github.com/pmndrs/jotai/discussions/1615
- https://github.com/jotaijs/jotai-tanstack-query/issues/21
- https://github.com/pmndrs/jotai/discussions/1751
### Some other changes
#### Utils
- `atomWithStorage` util's `delayInit` is removed as being default. Also it will always render `initialValue` on first render, and the stored value, if any, on subsequent renders. The new behavior differs from v1. See https://github.com/pmndrs/jotai/discussions/1737 for more information.
- `useHydrateAtoms` can only accept writable atoms.
#### Import statements
The v2 API is also provided from alternate entry points for library authors and non-React users.
- `jotai/vanilla`
- `jotai/vanilla/utils`
- `jotai/react`
- `jotai/react/utils`
```js
// Available since v1.11.0
import { atom } from 'jotai/vanilla'
import { useAtom } from 'jotai/react'
// Available since v2.0.0
import { atom } from 'jotai' // is same as 'jotai/vanilla'
import { useAtom } from 'jotai' // is same as 'jotai/react'
```
Note: If you are not using ESM, you want to prefer using `jotai/vanilla` etc. instead of `jotai`, for better tree shaking.
---
### Guides Migrating To V3 (`docs/guides/migrating-to-v3.mdx`)
---
title: v3 migration
description: How to migrate to Jotai v3
nav: 8.01
---
Roadmap: https://github.com/pmndrs/jotai/discussions/2889
Jotai v3 focuses on modernizing the package.
The public API is unchanged: `useAtom`, `useAtomValue` and `useSetAtom`
keep the same signatures and the same behavior for the vast majority of use cases.
If your app runs on Jotai v2 without deprecation warnings,
it should run on v3 as is.
There is one subtle timing change worth knowing about, see
[useAtomValue: a subtle mount-timing change](../core/use-atom.mdx#a-subtle-mount-timing-change-in-v3)
below.
### Requirement changes
The minimum requirements are raised:
- React 18 (v2 supports React 17)
- TypeScript 5.5 (v2 supports TypeScript 3.8)
- Node.js `>=22.12.0` (v2 supports Node.js 12.20)
### Packaging changes
#### ESM only
The CJS, UMD and SystemJS builds are no longer provided.
Modern bundlers work with the ESM build out of the box.
The supported Node.js versions can load it
even from CJS code with `require()`.
The package `exports` only expose the public entry points:
- `jotai`
- `jotai/utils`
- `jotai/vanilla`
- `jotai/vanilla/utils`
- `jotai/vanilla/internals`
- `jotai/react`
- `jotai/react/utils`
Importing other files in the package directly no longer works.
#### `process.env.NODE_ENV` is used directly
The published files read `process.env.NODE_ENV` directly
to omit development-only checks in production.
Bundlers handle it by default.
If you load Jotai in a browser without a bundler
(for example, with import maps),
you need to define it by yourself.
```js
globalThis.process ??= { env: { NODE_ENV: 'production' } }
```
#### ES2020 syntax
The published files are compiled with the ES2020 target.
If you need to support older browsers,
transpile the package in your build.
### Removed features
#### `atomFamily` util
It's moved to the `jotai-family` package.
##### Previous API
```js
import { atomFamily } from 'jotai/utils'
```
##### New API
```js
// npm install jotai-family
import { atomFamily } from 'jotai-family'
```
#### `loadable` util
Use the `unwrap` util instead.
The previous behavior can be implemented in userland:
```js
import { atom } from 'jotai'
import { unwrap } from 'jotai/utils'
function loadable(anAtom) {
const LOADING = { state: 'loading' }
const unwrappedAtom = unwrap(anAtom, () => LOADING)
return atom((get) => {
try {
const data = get(unwrappedAtom)
if (data === LOADING) {
return LOADING
}
return { state: 'hasData', data }
} catch (error) {
return { state: 'hasError', error }
}
})
}
```
#### `jotai/babel` plugins
They are moved to the `jotai-babel` package.
##### Previous API
```js
// babel config
plugins: ['jotai/babel/plugin-react-refresh']
```
##### New API
```js
// npm install jotai-babel
plugins: ['jotai-babel/plugin-react-refresh']
```
#### `setSelf` option in the read function
##### Previous API
```js
const anAtom = atom(async (get, { setSelf }) => {
// ...
})
```
##### New API
There is no direct replacement.
Depending on the use case,
`onMount` or [jotai-effect](https://github.com/jotaijs/jotai-effect)
would cover it.
#### `delay` option in `useAtom` and `useAtomValue`
##### Previous API
```js
const value = useAtomValue(anAtom, { delay: 100 })
```
##### New API
Create a custom hook:
```js
import { useEffect, useState } from 'react'
import { useStore } from 'jotai'
function useAtomValueWithDelay(anAtom, { delay }) {
const store = useStore()
const [value, setValue] = useState(() => store.get(anAtom))
useEffect(() => {
const unsub = store.sub(anAtom, () => {
setTimeout(() => setValue(store.get(anAtom)), delay)
})
return unsub
}, [store, anAtom, delay])
return value
}
```
### New hooks for advanced users
React 19 introduces `React.use()`, letting a component suspend by reading a
promise during render. `useAtomValue` uses it when available, and falls back
to the previous behavior on React 18. Splitting that logic out enables two
lower-level hooks:
- [`useAtomValueRaw`](../core/use-atom.mdx#useatomvalueraw): like
`useAtomValue`, but it never suspends. An async atom's value is returned
without being consumed through React's `use()`.
- [`useAtomValueRawSync`](../core/use-atom.mdx#useatomvaluerawsync): the same
idea, built on `useSyncExternalStore`. It trades concurrent rendering for
no tearing and no missed update around mount.
You don't need either hook to migrate. `useAtomValue` keeps working as the
default choice. See [Choosing a hook](../core/use-atom.mdx#choosing-a-hook)
for when to reach for them.
---
### Guides Nextjs (`docs/guides/nextjs.mdx`)
---
title: Next.js
description: How to use Jotai with Next.js
nav: 8.03
keywords: next,nextjs
---
### Hydration
Jotai has support for hydration of atoms with `useHydrateAtoms`. The documentation for the hook can be seen [here](../utilities/ssr.mdx).
### Browser storage
Next.js still prerenders client components during static export, so browser storage APIs such as `localStorage` and `sessionStorage` are not available during the server render.
If you use `atomWithStorage` with `createJSONStorage`, avoid referencing browser storage globals directly. Use `window` behind a server guard instead:
```js
import { atomWithStorage, createJSONStorage } from 'jotai/utils'
const storage = createJSONStorage(() =>
typeof window !== 'undefined' ? window.sessionStorage : undefined,
)
const someAtom = atomWithStorage('some-key', someInitialValue, storage)
```
If the rendered UI depends on the stored value, render that subtree only on the client to avoid hydration mismatches:
```js
import dynamic from 'next/dynamic'
const StoredPreferences = dynamic(
() => import('../components/StoredPreferences'),
{
ssr: false,
},
)
```
See the [storage documentation](../utilities/storage.mdx#server-side-rendering) for more details.
### Sync with router
It's possible to sync Jotai with the router. You can achieve this with `atomWithHash`:
```js
const pageAtom = atomWithHash('page', 1, {
replaceState: true,
subscribe: (callback) => {
Router.events.on('routeChangeComplete', callback)
window.addEventListener('hashchange', callback)
return () => {
Router.events.off('routeChangeComplete', callback)
window.removeEventListener('hashchange', callback)
}
},
})
```
This way you have full control over what [router event](https://nextjs.org/docs/api-reference/next/router#routerevents) you want to subscribe to.
> #### In Next.js 13
>
> As of Next.js 13 there have been some changes to the `Router.events.on()` which no longer expose events. There are plans in the [App Router Roadmap](https://beta.nextjs.org/docs/app-directory-roadmap#planned-features) for event intercepting and hash handling. However there is no ETA on when this will be available or what it will look like. For now when trying to the `atomWithHash()` you will not get the atom loading with any data when navigating using the router, only when the page is reloaded or the component is rerendered. It is also recommended that you set the `setHash` option to `replaceState` as Next.js appears to use window.history in the background and this will allow the user to use the browser back button.
### You can't return promises in server side rendering
It's important to note that you can't return promises with SSR - However, it's possible to guard against it inside the atom definition.
If possible use `useHydrateAtoms` to hydrate values from the server.
```js
const postData = atom((get) => {
const id = get(postId)
if (isSSR || prefetchedPostData[id]) {
return prefetchedPostData[id] || EMPTY_POST_DATA
}
return fetchData(id) // returns a promise
})
```
### Provider
By default, Jotai uses an implicit global store to keep track of atom values. This is what is referred to as "provider-less" mode. This becomes an issue in SSR scenario because this global store is kept alive and is shared between multiple requests, which can lead to bugs and security risks.
To limit the lifetime of the store to the scope of one request, you need to use a [Provider](../core/provider.mdx) at the root of your app (or a subtree if you're using Jotai only for a part of your application).
```typescript
import { Provider } from 'jotai'
function App({ Component, pageProps }: AppProps) {
return (
)
}
```
In this case:
1. `Provider` will hold the state of the atoms used in its subtree instead of the global store.
2. `Provider`'s lifetime will be the same as the app itself, and since the app is recreated on each SSR request we essentially limit the lifetime of the store to a single request as well.
### SWC plugins
Jotai provides SWC plugins for better DX while developing with Next.js. [Find more info in the SWC section.](../tools/swc.mdx)
### Examples
#### Clock
= {}
todos.forEach((id) => {
todoMap[id] = get(todoAtomFamily({ id }))
})
const obj = {
todos,
todoMap,
filter: get(filterAtom),
}
action.callback(JSON.stringify(obj))
} else if (action.type === 'deserialize') {
const obj = JSON.parse(action.value)
// needs error handling and type checking
set(filterAtom, obj.filter)
obj.todos.forEach((id: string) => {
const todo = obj.todoMap[id]
set(todoAtomFamily({ id, ...todo }), todo)
})
set(todosAtom, obj.todos)
}
})
const Persist = () => {
const [, dispatch] = useAtom(serializeAtom)
const save = () => {
dispatch({
type: 'serialize',
callback: (value) => {
localStorage.setItem('serializedTodos', value)
},
})
}
const load = () => {
const value = localStorage.getItem('serializedTodos')
if (value) {
dispatch({ type: 'deserialize', value })
}
}
return (
)
}
```
#### Examples
{todoList.map((todo) => (
- {todo.description}
))}
)
}
```
### Examples
Current balance ${dollars}
)
}
```
### Examples
{count}
)
}
```
`Counter.test.ts`:
```jsx
import React from 'react'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Counter } from './Counter'
test('should increment counter', () => {
// Arrange
render(
Hello, {name}! You have visited this page {count} times.
)
})
```
Compare that code with `async`–`await`:
```tsx
const namePromise = Promise.resolve('Visitor')
const countPromise = Promise.resolve(1)
const greetingPromise = (async function () {
const name = await namePromise
const count = await countPromise
return (
Hello, {name}! You have visited this page {count} times.
)
})()
```
This similarity is no coincidence. Both atoms and promises are **Monads**†, a
concept from functional programming. The syntax used in both `greetingAtom` and
`greetingPromise` is known as **do-notation**, a syntax sugar for the plainer
monad interface.
### About monads
The monad interface is responsible for the fluidity of the atom and promise
interfaces. The monad interface allowed us to define `greetingAtom` in terms of
`nameAtom` and `countAtom`, and allowed us to define `greetingPromise` in terms
of `namePromise` and `countPromise`.
If you're curious, a structure (like `Atom` or `Promise`) is a monad if you can
implement the following functions for it. A fun exercise is trying to implement
`of`, `map` and `join` for Arrays.
```ts
type SomeMonad
User Id: {userId}
)
}
const UserName = () => {
const [user] = useAtom(userAtom)
return User name: {user.name}
}
const App = () => (
<>
count: {count}
)
}
```
Similar to the `useSetAtom` hook, `useAtomValue` allows you to access a read-only atom. Nonetheless, it can also be used to access read-write atom's values.
Under the hood, `useAtomValue` is [`useAtomValueRaw`](#useatomvalueraw) plus React's `use()`: it resolves promises and suspends, instead of returning them as-is.
### A subtle mount-timing change in v3
In v2, `useAtomValue` always re-rendered once right after mounting, even without a value change. This caught updates that happened between the initial render and the subscription, for example a value written by a child's `useEffect` (which runs before the parent's).
In v3, that extra render is gone: `useAtomValue` only re-renders on an actual change. It's faster, but it can miss that specific kind of update until the next one. Use [`useAtomValueRawSync`](#useatomvaluerawsync) if you need to catch it.
## useAtomValueRaw
⚠️ This hook is only available since Jotai v3, and it's intended for advanced users.
```jsx
const countAtom = atom(0)
const Counter = () => {
const count = useAtomValueRaw(countAtom)
// ...
}
```
`useAtomValueRaw` is like `useAtomValue`, but it doesn't resolve promises: the value of an async atom is returned as a promise, and the component never suspends. It subscribes to the store in an effect, so it doesn't cause an extra re-render on initial mount. As a trade-off, a value change that happens between the initial render and the subscription is not picked up until the next change.
> "Raw" means the promise is returned without being consumed through React's `use()`.
## useAtomValueRawSync
⚠️ This hook is only available since Jotai v3, and it's intended for advanced users.
```jsx
const countAtom = atom(0)
const Counter = () => {
const count = useAtomValueRawSync(countAtom)
// ...
}
```
`useAtomValueRawSync` has the same signature as `useAtomValueRaw` and doesn't resolve promises either, but it's implemented with `useSyncExternalStore`. It avoids tearing and picks up values written during mount. As a trade-off, updates are always rendered synchronously without taking advantage of concurrent rendering features.
> "Sync" refers to `useSyncExternalStore`: rendering is always synchronous, with no concurrent-rendering support.
## useSetAtom
```jsx
const switchAtom = atom(false)
const SetTrueButton = () => {
const setCount = useSetAtom(switchAtom)
const setTrue = () => setCount(true)
return (
State: {state.toString()}
)
}
```
In case you need to update a value of an atom without reading it, you can use `useSetAtom()`.
This is especially useful when the performance is a concern, as the `const [, setValue] = useAtom(valueAtom)` will cause unnecessary rerenders on each `valueAtom` update.
---
### Extensions Cache (`docs/extensions/cache.mdx`)
---
title: Cache
description: This doc describes cache extension.
nav: 4.07
keywords: cache
---
Jotai provides primitive functions to optimize re-renders.
It's designed to hold only "current" atom values,
and it doesn't cache older values.
Caching is sometimes useful. For example, if an async atom
triggers network requests, we may want to cache the responses.
[jotai-cache](https://github.com/jotai-labs/jotai-cache) is
a third-party library to help such use cases.
### Install
```
npm install jotai-cache
```
## atomWithCache
```js
atomWithCache(read, options): Atom
```
`atomWithCache` creates a new read-only atom with cache.
### Parameters
**read**: read function to define the read-only atom.
**options** (optional): an object of options to customize the behavior of the atom
### Options
**size** (optional): maximum size of cache items.
**shouldRemove** (optional): a function to check if cache items should be removed.
**areEqual** (optional): a function to compare atom values.
### Examples
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Stackblitz
Example
```js atomEffect((get, set) => { // updates whenever `anAtom` changes value get(anAtom) }) ```Example
```js atomEffect((get, set) => { setTimeout(() => { // does not add `anAtom` as a dependency get(anAtom) }) }) ```Example
```js atomEffect((get, set) => { return () => { // does not add `anAtom` as a dependency get(anAtom) } }) ```Example
```js atomEffect((get, set) => { if (get(isEnabledAtom)) { // `isEnabledAtom` and `anAtom` are dependencies const aValue = get(anAtom) } else { // `isEnabledAtom` and `anotherAtom` are dependencies const anotherValue = get(anotherAtom) } }) ```Example
```js const logCounts = atomEffect((get, set) => { set(logAtom, `count is ${get(countAtom)}`) }) const actionAtom = atom(null, (get, set) => { get(logAtom) // 'count is 0' set(countAtom, (value) => value + 1) get(logAtom) // 'count is 0' - the effect runs once the write function completes }) store.sub(logCounts, () => {}) store.set(actionAtom) store.get(logAtom) // 'count is 1' - the effect ran before `store.set` returned ```Example
```js const tensAtom = atom(0) const onesAtom = atom(0) const updateTensAndOnes = atom(null, (get, set) => { set(tensAtom, (value) => value + 1) set(onesAtom, (value) => value + 1) }) const combos = atom([]) const effectAtom = atomEffect((get, set) => { const value = get(tensAtom) * 10 + get(onesAtom) set(combos, (arr) => [...arr, value]) }) store.sub(effectAtom, () => {}) store.set(updateTensAndOnes) store.get(combos) // [00, 11] ```Example
```js atomEffect((get, set) => { get(countAtom) set(countAtom, (value) => value + 1) // Will not loop }) ```Example
```js atomEffect((get, set) => { const intervalId = setInterval(() => set(clockAtom, Date.now())) return () => clearInterval(intervalId) }) ```Example
```js let i = 0 const effectAtom = atomEffect(() => { get(countAtom) i++ }) store.sub(effectAtom, () => {}) store.sub(effectAtom, () => {}) store.set(countAtom, (value) => value + 1) console.log(i) // 1 ```Example
```js atom((get) => { if (get(isEnabledAtom)) { get(effectAtom) } }) ```Example
```js const countAtom = atom(0) atomEffect((get, set) => { const count = get.peek(countAtom) // Will not add `countAtom` as a dependency }) ```Example
```js atomEffect((get, set) => { const count = get(countAtom) if (count % 10 === 0) { return } set.recurse(countAtom, (value) => value + 1) }) ```count: {count.value}
}
const Controls = () => {
const [, setCount] = useAtom(countAtom)
// setCount === update : (draft: Draftcount: {count.value}
}
const Controls = () => {
const [, setCount] = useAtom(countAtom)
// setCount === update : (draft: Draftcount: {count.value}
}
const Controls = () => {
const [, setCount] = useImmerAtom(primitiveAtom)
// setCount === update : (draft: Draftcount: {count}
Value of a: {a}
Value of b: {b}
)
}
```
#### Stackblitz
Loading...
if (isError) return Error
return {JSON.stringify(data)}
}
```
### atomWithInfiniteQuery usage
`atomWithInfiniteQuery` is very similar to `atomWithQuery`, however it is for an `InfiniteQuery`, which is used for data that is meant to be paginated. You can [read more about Infinite Queries here](https://tanstack.com/query/v5/docs/framework/react/guides/infinite-queries).
> Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. React Query supports a useful version of useQuery called useInfiniteQuery for querying these types of lists.
A notable difference between a standard query atom is the additional option `getNextPageParam` and `getPreviousPageParam`, which is what you'll use to instruct the query on how to fetch any additional pages.
```jsx
import { atom, useAtom } from 'jotai'
import { atomWithInfiniteQuery } from 'jotai-tanstack-query'
const postsAtom = atomWithInfiniteQuery(() => ({
queryKey: ['posts'],
queryFn: async ({ pageParam }) => {
const res = await fetch(`https://jsonplaceholder.typicode.com/posts?_page=${pageParam}`)
return res.json()
},
getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
initialPageParam: 1,
}))
const Posts = () => {
const [{ data, fetchNextPage, isPending, isError, isFetching }] =
useAtom(postsAtom)
if (isPending) return Loading...
if (isError) return Error
return (
<>
{data.pages.map((page, index) => (
{page.map((post: any) => (
))}
)
}
```
### atomWithMutation usage
`atomWithMutation` creates a new atom that implements a standard [`Mutation`](https://tanstack.com/query/v5/docs/framework/react/guides/mutations) from TanStack Query.
> Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
```tsx
const postAtom = atomWithMutation(() => ({
mutationKey: ['posts'],
mutationFn: async ({ title }: { title: string }) => {
const res = await fetch(`https://jsonplaceholder.typicode.com/posts`, {
method: 'POST',
body: JSON.stringify({
title,
body: 'body',
userId: 1,
}),
headers: {
'Content-type': 'application/json; charset=UTF-8',
},
})
const data = await res.json()
return data
},
}))
const Posts = () => {
const [{ mutate, status }] = useAtom(postAtom)
return (
{post.title}
))}
{JSON.stringify(status, null, 2)}
{JSON.stringify(data)}
}
```
### atomWithSuspenseInfiniteQuery usage
```jsx
import { atom, useAtom } from 'jotai'
import { atomWithSuspenseInfiniteQuery } from 'jotai-tanstack-query'
const postsAtom = atomWithSuspenseInfiniteQuery(() => ({
queryKey: ['posts'],
queryFn: async ({ pageParam }) => {
const res = await fetch(`https://jsonplaceholder.typicode.com/posts?_page=${pageParam}`)
return res.json()
},
getNextPageParam: (lastPage, allPages, lastPageParam) => lastPageParam + 1,
initialPageParam: 1,
}))
const Posts = () => {
const [{ data, fetchNextPage, isPending, isError, isFetching }] =
useAtom(postsAtom)
return (
<>
{data.pages.map((page, index) => (
{page.map((post: any) => (
))}
)
}
```
### Referencing the same instance of Query Client in your project
Perhaps you have some custom hooks in your project that utilises the `useQueryClient()` hook to obtain the `QueryClient` object and call its methods.
To ensure that you reference the same `QueryClient` object, be sure to wrap the root of your project in a `{post.title}
))}
-
{data.countries.map(({ name }) => (
- {name} ))}
count: {count}
another count: {anotherCount}
)
}
function App() {
return (
{count}
)
}
function App() {
return (
With initial value 1
With initial value 2
Default
ID: {data.id}
Height: {data.height}
Weight: {data.weight}
{operationResult.data?.increment}
Selected value: {value}
)
}
```
Note that we can pass atoms configs as props.
It might not make any sense, but we could create an atom config on demand.
```jsx
const Component = () => {
const [currentAtom, setCurrentAtom] = useState(() => atom(0))
const [count, setCount] = useAtom(currentAtom)
return (
Count: {count}
)
}
```
### Storing an atom config in atom
Likewise, we can store an atom config as a value of another atom.
```jsx
const firstNameAtom = atom('Tanjiro')
const lastNameAtom = atom('Kamado')
const showingNameAtom = atom(firstNameAtom)
const Component = () => {
const [nameAtom, setNameAtom] = useAtom(showingNameAtom)
const [name] = useAtom(nameAtom)
return (
Name: {name}
)
}
```
It's possible to create a derived atom.
```js
const derivedNameAtom = atom((get) => {
const nameAtom = get(showingNameAtom)
return get(nameAtom)
})
// Or a shorter version
const derivedNameAtom = atom((get) => get(get(showingNameAtom)))
```
To avoid confusing what is in atoms, naming atoms explicitly would be important.
Also, TypeScript type information would be helpful.
### Storing an array of atom configs in atom
Finally, the atoms in atom pattern is to store an array of atom config into an atom.
```jsx
const countsAtom = atom([atom(1), atom(2), atom(3)])
const Counter = ({ countAtom }) => {
const [count, setCount] = useAtom(countAtom)
return (
{count}
)
}
const Parent = () => {
const [counts, setCounts] = useAtom(countsAtom)
const addNewCount = () => {
const newAtom = atom(0)
setCounts((prev) => [...prev, newAtom])
}
return (
{counts.map((countAtom) => (
)
}
```
The benefit of this approach is, if you increment a count,
only the corresponding Counter component re-renders and no other components re-render.
It is important to note that `anAtom.toString()` returns a unique id, which can be used as a `key` in a map.
#### Hint for TypeScript users
```jsx
{name}: {price}
)
}
const Parent = () => {
const [prices] = useAtom(pricesAtom)
return (
{Object.keys(prices).map((name) => (
)
}
```
---
### Guides Composing Atoms (`docs/guides/composing-atoms.mdx`)
---
title: Composing atoms
nav: 8.11
---
The `atom` function provided by library is very primitive,
but it's also so flexible that you can combine multiple atoms
to implement a functionality.
> Note again that `atom()` creates an atom config, which is an object
> to define a behavior of the atom.
Let's recap how we can derive an atom.
### Basic derived atoms
Here's one of the simplest examples of a derived atom:
```js
export const textAtom = atom('hello')
export const textLenAtom = atom((get) => get(textAtom).length)
```
The `textLenAtom` is called read-only atom, because
it doesn't have a `write` function defined.
The following is another simple example with the `write` function:
```js
const textAtom = atom('hello')
export const textUpperCaseAtom = atom(
(get) => get(textAtom).toUpperCase(),
(_get, set, newText) => set(textAtom, newText),
)
```
In this case, `textUpperCaseAtom` is capable to set the original `textAtom`.
So, we can only export `textUpperCaseAtom` and can hide
`textAtom` in a smaller scope.
Now, let's see some real examples.
### Overriding default atom values
Suppose we have a read-only atom.
Obviously read-only atoms are not writable, but we can combine two atoms
to override the read-only atom value.
```js
const rawNumberAtom = atom(10.1) // can be exported
const roundNumberAtom = atom((get) => Math.round(get(rawNumberAtom)))
const overwrittenAtom = atom(null)
export const numberAtom = atom(
(get) => get(overwrittenAtom) ?? get(roundNumberAtom),
(get, set, newValue) => {
const nextValue =
typeof newValue === 'function' ? newValue(get(numberAtom)) : newValue
set(overwrittenAtom, nextValue)
},
)
```
The final `numberAtom` just works like a normal primitive atom like `atom(10)`.
If you set a number value, it will override the `overwrittenAtom` value,
and if you set `null`, it will be the `roundNumberAtom` value.
The reusable implementation is available as `atomWithDefault`
in `jotai/utils`. See [atomWithDefault](../utilities/resettable.mdx).
Next, let's see another example to sync with external value.
### Syncing atom values with external values
There are some external values we want to deal with.
`localStorage` is the one. Another is `window.title`.
Let's see how to create an atom that is in sync with `localStorage`.
```js
const baseAtom = atom(localStorage.getItem('mykey') || '')
export const persistedAtom = atom(
(get) => get(baseAtom),
(get, set, newValue) => {
const nextValue =
typeof newValue === 'function' ? newValue(get(baseAtom)) : newValue
set(baseAtom, nextValue)
localStorage.setItem('mykey', nextValue)
},
)
```
The `persistedAtom` works like a primitive atom, but its value
is persisted in `localStorage`.
The reusable implementation is available as `atomWithStorage`
in `jotai/utils`. See [atomWithStorage](../utilities/storage.mdx).
There is a caveat with this usage. While atom config doesn't hold a value,
the external value is a singleton value.
So, if we use this atom in two different Providers,
There will be an inconsistency between the two `persistedAtom` values.
This could be solved if the external value had a subscription mechanism.
For example, `atomWithProxy` in `jotai-valtio` comes with subscription,
so we don't have such a limitation. Values in different Providers
will be in sync.
Back to the main topic, let's explore another example.
### Extending atoms with `atomWith*` utils
We have several utils whose names start with `atomWith`.
They create an atom with a certain functionality.
Unfortunately, we can't combine two atom utils.
For example, `atomWithStorage` and `atomWithReducer`
can't be used to define a single atom.
In such a case, we need to derive an atom by ourselves.
Let's try adding reducer functionality to `atomWithStorage`:
```js
const reducer = ...
const baseAtom = atomWithStorage('mykey', '')
export const derivedAtom = atom(
(get) => get(baseAtom),
(get, set, action) => {
set(baseAtom, reducer(get(baseAtom), action))
}
)
```
This is easy, because in this case, `atomWithReducer`
is a simple implementation compared to `atomWithStorage`.
For more complex cases, it wouldn't be very easy.
It would still be a open research field.
Finally, let's see another example with actions.
### Action atoms
This should be known pattern as it's described in README.
Nonetheless, it might to be useful to revisit.
Let's create a counter that you can only increment or decrement by one.
One solution is `atomWithReducer`:
```js
const countAtom = atomWithReducer(0, (prev, action) => {
if (action === 'INC') {
return prev + 1
}
if (action === 'DEC') {
return prev - 1
}
throw new Error('unknown action')
})
```
This is fine, but not very atomic.
If we want to get benefit from code splitting / lazy loading,
We want to create write only atoms, or action atoms.
```js
const baseAtom = atom(0) // do not export
export const countAtom = atom((get) => get(baseAtom)) // read only
export const incAtom = atom(null, (_get, set) => {
set(baseAtom, (prev) => prev + 1)
})
export const decAtom = atom(null, (_get, set) => {
set(baseAtom, (prev) => prev - 1)
})
```
This is more atomic and looks like a Jotai way.
You can also create an action atom that will call another action atom:
```js
// continued from the previous code
export const dispatchAtom = atom(null, (_get, set, action) => {
if (action === 'INC') {
set(incAtom)
} else if (action === 'DEC') {
set(decAtom)
} else {
throw new Error('unknown action')
}
})
```
Why do we want it? Because it will be used only when needed.
It allows code splitting and dead code elimination.
### In summary
Atoms are building block.
By composing atoms based on other atoms,
we can implement complicated logic.
This is not only for read derived atoms, but also for write action atoms.
Essentially, atoms are like functions, so composing atoms is
like composing functions with other functions.
When you compose atoms, prefer a wide graph over a deep one: an atom that derives from a few others is fine, but a long chain where each atom derives from the previous one is bounded by the JavaScript call stack and can overflow when read. See [dependency graph depth](performance.mdx#dependency-graph-depth) in the performance guide for details and how to flatten such chains.
**Note**: We mentioned that our atoms can contain any kind of data, it can be a string, Blob, Observer, anything really. There is just one exception. Because derived atoms are defined using a function, Jotai will not understand if we pass it a function that isn't exactly a pure getter.
So what you can do is simply wrap your function in an object.
```js
const doublerAtom = atom({ callback: (n) => n * 2 })
// Usage
const [doubler] = useAtom(doublerAtom)
const doubledValue = doubler.callback(50) // Will compute to 100
```
---
### Guides Core Internals (`docs/guides/core-internals.mdx`)
---
title: Core internals
description: A simplified version of the core implementation
nav: 8.10
---
This guide is beneficial for those who want to understand the core implementation of Jotai. It's not meant to be a complete example of the
core implementation but rather a simplified version. It's inspired by the collection of tweets by Daishi Kato([@dai_shi](https://twitter.com/dai_shi)).
### First Version
Let's start with an easy example. An atom is just a function that will return a configuration object. We are using WeakMap to map atom with their state.
WeakMap doesn't keep its keys in memory, so if an atom is garbage collected, its state will be garbage collected too. This helps avoid memory leaks.
```js
import { useState, useEffect } from 'react'
// atom function returns a config object which contains initial value
export const atom = (initialValue) => ({ init: initialValue })
// we need to keep track of the state of the atom.
// we are using weakmap to avoid memory leaks
const atomStateMap = new WeakMap()
const getAtomState = (atom) => {
let atomState = atomStateMap.get(atom)
if (!atomState) {
atomState = { value: atom.init, listeners: new Set() }
atomStateMap.set(atom, atomState)
}
return atomState
}
// useAtom hook returns a tuple of the current value
// and a function to update the atom's value
export const useAtom = (atom) => {
const atomState = getAtomState(atom)
const [value, setValue] = useState(atomState.value)
useEffect(() => {
const callback = () => setValue(atomState.value)
// same atom can be used at multiple components, so we need to
// keep listening for atom's state change till component is unmounted.
atomState.listeners.add(callback)
callback()
return () => atomState.listeners.delete(callback)
}, [atomState])
const setAtom = (nextValue) => {
atomState.value = nextValue
// let all the subscribed components know that the atom's state has changed
atomState.listeners.forEach((l) => l())
}
return [value, setAtom]
}
```
Here's an example using our simplified atom implementation. [Counter example](https://codesandbox.io/s/zealous-field-z2xk6?file=/src/App.js)
Ref tweet: [Demystifying the internal of jotai](https://twitter.com/dai_shi/status/1484835169475653634)
### Second Version
Hang on! We can do better. In Jotai, we can create derived atom. A derived atom is an atom that depends on other atoms.
```js
const priceAtom = atom(10)
const readOnlyAtom = atom((get) => get(priceAtom) * 2)
const writeOnlyAtom = atom(
null, // it's a convention to pass `null` for the first argument
(get, set, args) => {
set(priceAtom, get(priceAtom) - args)
},
)
const readWriteAtom = atom(
(get) => get(priceAtom) * 2,
(get, set, newPrice) => {
set(priceAtom, newPrice / 2)
// you can set as many atoms as you want at the same time
},
)
```
To keep track of all the dependents, we need to add one more property to the atom's state. Let's say atom X depends on atom Y,
so when we update atom Y, we also update atom X. This is called dependency tracking.
```js
const atomState = {
value: atom.init,
listeners: new Set(),
dependents: new Set(),
}
```
We now need to create functions for reading and writing an atom that can handle updating dependent atoms' state.
```
/* Detailed source-code truncated for AI context efficiency. */
```
Here is an example using our derived atom implementation. [Derived counter example](https://codesandbox.io/s/affectionate-chandrasekhar-nuxms?file=/src/App.js)
Ref tweet: [Supporting derived atoms](https://twitter.com/dai_shi/status/1485434083778117632)
---
### Guides Debugging (`docs/guides/debugging.mdx`)
---
title: Debugging
nav: 8.07
keywords: debug,labels,devtools,freeze
---
In basic apps, `console.log` can be our best friend for debugging atoms, but when applications get bigger and we have more atoms to use, logging would not be a good way of debugging atoms.
Jotai provides two ways of debugging atoms, **React Dev Tools** and **Redux Dev tools**. For reading values and simple debugging, React Dev Tools might suit you, but for more complicated tasks like Time-travelling and setting values, Redux Dev Tools would be a better option.
## Debug labels
It is worth mentioning that we have a concept called **Debug labels** in Jotai which may help us with debugging.
By default each Jotai state has the label like `1:{testAtomValue}
}
function AtomsHydrator({
atomValues,
children,
}: {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
atomValues: Iterable<
readonly [WritableAtom{name}
{age}
)
}
```
Do's:
```jsx
const NameComponent = () => {
const [name] = useAtom(nameAtom)
return {name}
}
const AgeComponent = () => {
const [age] = useAtom(ageAtom)
return {age}
}
const Profile = () => {
return (
<>
-
{todoList.map((todo) => (
- {todo.description} ))}
Current balance ${dollars}
) } ``` ### Examples{count}
{time}
{count}
)
}
```
Style preview
{/* Clicking this button twice will only trigger one render */}
{/* Clicking this button twice will only trigger one render */}
{peopleAtoms.map((personAtom) => (
)
}
```
## selectAtom
> This function creates a derived atom whose value is a function of the original atom's value. [jotai/utils](../utilities/select.mdx)
This utility is like `focusAtom`, but it always returns a read-only atom.
Assume we want to consume the info data, and its data is always unchangeable. We can make a read-only atom from it and select that created atom.
```js
// first we create a derived atom based on initialData.info
const infoAtom = atom((get) => get(dataAtom).info)
```
Then we use it in our component:
```jsx
import { atom, useAtom } from 'jotai'
import { selectAtom, splitAtom } from 'jotai/utils'
const tagsSelector = (s) => s.tags
const Tags = () => {
const tagsAtom = selectAtom(infoAtom, tagsSelector)
const tagsAtomsAtom = splitAtom(tagsAtom)
const [tagAtoms] = useAtom(tagsAtomsAtom)
return (
{tagAtoms.map((tagAtom) => (
)
}
```
---
### Recipes Use Atom Effect (`docs/recipes/use-atom-effect.mdx`)
---
title: useAtomEffect
nav: 9.03
keywords: effect, atom effect, side effect, side-effect, sideeffect, hook, useAtomEffect
---
> `useAtomEffect` runs side effects in response to changes in atoms or props using [atomEffect](../extensions/effect.mdx).
The effectFn reruns whenever the atoms it depends on change or the effectFn itself changes. Be sure to memoize the effectFn if it's a function defined in the component.
⚠️ Note: always prefer to use a [stable version of useMemo and useCallback](https://github.com/alexreardon/use-memo-one) to avoid extra atomEffect recomputations. You may rely on useMemo as a performance optimization, but not as a semantic guarantee. In the future, React may choose to “forget” some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components.
```ts
import { useMemoOne as useStableMemo } from 'use-memo-one'
import { useAtomValue } from 'jotai/react'
import { atomEffect } from 'jotai-effect'
type EffectFn = ParametersYou have {messages.length} messages
{messages.map((message) => (
{message.text}
))}
)
}
```
---
### Recipes Use Reducer Atom (`docs/recipes/use-reducer-atom.mdx`)
---
title: useReducerAtom
nav: 9.11
keywords: reducer, hook, useReducerAtom
---
`useReducerAtom` is a custom hook to apply a reducer to a primitive atom.
It's useful to change the update behavior temporarily.
Also, consider [atomWithReducer](../utilities/reducer.mdx)
for the atom-level solution.
```ts
import { useCallback } from 'react'
import { useAtom } from 'jotai'
import type { PrimitiveAtom } from 'jotai'
export function useReducerAtom
{count}
)
}
```
Loading...
;
if (state.state === 'hasError') return Error: {state.error}
;
return {state.data}
;
```
## Handling Pending States with `withPending`
The `withPending` API wraps an atom to handle unresolved values by returning a fallback, providing an alternative to Jotai's `unwrap` with enhanced pending state management.
```ts
import { atom } from 'jotai'
import { withPending } from 'jotai-eager'
const asyncAtom = atom(Promise.resolve('data'))
const wrappedAtom = withPending(asyncAtom, () => 'Loading...')
// Returns 'Loading...' while pending, then 'data'
```
## Using `try` & `catch` inside eager atoms
Eager atoms internally use exceptions to suspend computation of the atom until an async dependency is fulfilled (similar to React's suspense behavior, but does not require React to function). This means that using exception handling inside eager atoms has to be instrumented with an additional call to `isEagerError`.
```ts
import { eagerAtom, isEagerError } from 'jotai-eager'
const fooAtom = eagerAtom((get) => {
try {
// ...
} catch (e) {
if (isEagerError(e)) {
// Rethrow the error to be handled by `jotai-eager`
throw e
}
// ...
}
})
```
## Awaiting a Promise that is created inside the atom
Since the read function is 'retried' after a Promise we await is fulfilled, the mechanism expects
the same promise to be passed into `get.await` the second time around. Since we are creating the
Promise inside of the read function itself, that will never be the case, and we'll be stuck in an infinite loop.
```ts
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
// This atom will be stuck in an infinite loop :(
const deferredNumberAtom = eagerAtom((get) => {
get.await(sleep(1000)) // Waiting for a second...
return 123
})
```
For this particular use case, since we're always deferring, using an `eagerAtom` over
a vanilla async atom is unnecessary.
## soon / soonAll
For more advanced usage, for example **conditional dependencies**, the `soon` and `soonAll` functions
can be used to perform sync/async transformations on data eagerly, on a more fine-grained level.
### Conditional dependency
```ts
import { soon } from 'jotai-eager'
// Given the following definitions:
// const queryAtom: AtomAtom count: {atoms.size}
{Array.from(atoms).map(([atom, atomValue]) => (
{`${atom.debugLabel}: ${atomValue}`}
))}count: {counter}
}
```
The `atomWithObservable` function creates an atom from a rxjs (or similar) `subject` or `observable`.
Its value will be last value emitted from the stream.
To use this atom, you need to wrap your component with `current count: {count}
}
```
### Stackblitz
count1: {count1}, count2: {count2}
)
}
```
This can be useful when an `atomWithDefault` atom value is overwritten
using the `set` function, in which case the provided `getter` function
is no longer used and any change in dependencies atoms will not trigger an update.
Resetting the value allows us to restore its original default value,
discarding changes made previously via the `set` function.
## atomWithRefresh
```ts
function atomWithRefresh-
{posts.map((post) => (
- {post.title} ))}
{
setTodo((oldValue) => ({ ...oldValue, task: e.target.value }))
}}
/>
{
setTodo((oldValue) => ({ ...oldValue, done: !oldValue.done }))
}}
/>
)
}
const TodoList = () => {
const [todoAtoms, dispatch] = useAtom(todoAtomsAtom)
return (
-
{todoAtoms.map((todoAtom) => (
Welcome to {darkMode ? 'dark' : 'light'} mode!
) } ``` The `atomWithStorage` function creates an atom with a value persisted in `localStorage` or `sessionStorage` for React or `AsyncStorage` for React Native. ### Parameters **key** (required): a unique string used as the key when syncing state with localStorage, sessionStorage, or AsyncStorage **initialValue** (required): the initial value of the atom **storage** (optional): an object with the following methods: - **getItem(key, initialValue)** (required): Reads an item from storage, or falls back to the `initialValue` - **setItem(key, value)** (required): Saves an item to storage - **removeItem(key)** (required): Deletes the item from storage - **subscribe(key, callback, initialValue)** (optional): A method which subscribes to external storage updates. **options** (optional): an object with the following properties: - **getOnInit** (optional, by default **false**): A boolean value indicating whether to get item from storage on initialization. Note that in an SPA with `getOnInit` either not set or `false` you will always get the initial value instead of the stored value on initialization. If the stored value is preferred set `getOnInit` to `true`. If not specified, the default storage implementation uses `localStorage` for storage/retrieval, `JSON.stringify()`/`JSON.parse()` for serialization/deserialization, and subscribes to `storage` events for cross-tab synchronization.Header is visible!
} ) } ``` ### React-Native implementation You can use any library that implements `getItem`, `setItem` & `removeItem`. Let's say you would use the standard AsyncStorage provided by the community. ```js import { atomWithStorage, createJSONStorage } from 'jotai/utils' import AsyncStorage from '@react-native-async-storage/async-storage' const storage = createJSONStorage(() => AsyncStorage) const content = {} // anything JSON serializable const storedAtom = atomWithStorage('stored-key', content, storage) ``` **Note** set `getOnInit` to `true` if you want the atom to return the stored value immediately on initialization instead of the default value. **getOnInit true vs. false example**
```jsx
// Assume localStorage already contains: { "symbol": "BTC_USDC" }
// Without getOnInit (default behavior)
const symbolAtom = atomWithStorage('symbol', 'SOL_USDC')
function App() {
const symbol = useAtomValue(symbolAtom)
useEffect(() => {
console.log('symbol', symbol)
}, [symbol])
return
#### Notes with AsyncStorage (since v2.2.0)
With AsyncStorage (as with any asynchronous storage), the atom value becomes async.
When updating the atom by referencing the current value, then you'll need to `await` it.
```js
const countAtom = atomWithStorage('count-key', 0, anyAsyncStorage)
const Component = () => {
const [count, setCount] = useAtom(countAtom)
const increment = () => {
setCount(async (promiseOrValue) => (await promiseOrValue) + 1)
}
// ...
}
```
### Validating stored values
To add runtime validation to your storage atoms, you will need to create a custom implementation of storage.
Below is an example that utilizes Zod to validate values stored in `localStorage` with cross-tab synchronization.
```js
import { atomWithStorage } from 'jotai/utils'
import { z } from 'zod'
const myNumberSchema = z.number().int().nonnegative()
const storedNumberAtom = atomWithStorage('my-number', 0, {
getItem(key, initialValue) {
const storedValue = localStorage.getItem(key)
try {
return myNumberSchema.parse(JSON.parse(storedValue ?? ''))
} catch {
return initialValue
}
},
setItem(key, value) {
localStorage.setItem(key, JSON.stringify(value))
},
removeItem(key) {
localStorage.removeItem(key)
},
subscribe(key, callback, initialValue) {
if (
typeof window === 'undefined' ||
typeof window.addEventListener === 'undefined'
) {
return
}
const handler = (e) => {
if (e.storageArea === localStorage && e.key === key) {
let newValue
try {
newValue = myNumberSchema.parse(JSON.parse(e.newValue ?? ''))
} catch {
newValue = initialValue
}
callback(newValue)
}
}
window.addEventListener('storage', handler)
return () => window.removeEventListener('storage', handler)
},
})
```
We also have a new util `unstable_withStorageValidator` to simplify some cases.
The above case would become:
```js
import {
atomWithStorage,
createJSONStorage,
unstable_withStorageValidator as withStorageValidator,
} from 'jotai/utils'
import { z } from 'zod'
const myNumberSchema = z.number().int().nonnegative()
const isMyNumber = (v) => myNumberSchema.safeParse(v).success
const storedNumberAtom = atomWithStorage(
'my-number',
0,
withStorageValidator(isMyNumber)(createJSONStorage()),
)
```
---
--- METRICS ---
- Files Extracted: 81
- Estimated Token Budget: ~67092 tokens
- Canonical Reference: https://codewiki.google/github.com/pmndrs/jotai
{symbol}
}
// Console output WITHOUT getOnInit:
// LOG "symbol" SOL_USDC (initial render)
// LOG "symbol" BTC_USDC (after storage loads)
// With getOnInit set to true
const symbolAtom = atomWithStorage('symbol', 'SOL_USDC', undefined, {
getOnInit: true,
})
function App() {
const symbol = useAtomValue(symbolAtom)
useEffect(() => {
console.log('symbol', symbol)
}, [symbol])
return {symbol}
}
// Console output WITH getOnInit:
// LOG "symbol" BTC_USDC (gets stored value immediately)
```