jotai Documentation

Guides Async (`docs/guides/async.mdx`) Copy Section

title: Async nav: 8.99 keywords: async published: false Copy Chapter

Using async atoms, you gain access to real-world data while still managing them directly from your atoms and with incredible ease.

We can separate them in two main categories:

• Async read atoms: async request is started instantly as soon as you try to get its value. You could relate to them as "smart getters".
• Async write atoms: async request is started at a specific moment. You could relate to them as "actions".

Async read atom Copy Chapter

The read function of an atom can return a promise.

const countAtom = atom(1)
const asyncAtom = atom(async (get) => get(countAtom) * 2)

Jotai is inherently leveraging Suspense to handle asynchronous flows.

const ComponentUsingAsyncAtoms = () => {
  const [num] = useAtom(asyncAtom)
  // here `num` is always `number` even though asyncAtom returns a Promise
}
const App = () => {
  return (
    <Suspense fallback={/* What to show while suspended */}>
      <ComponentUsingAsyncAtoms />
    </Suspense>
  )
}

Alternatively, you could avoid the inherent suspending that Jotai does for you, by wrapping your atoms with the loadable API, or by reading the atom with 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.

const anotherAtom = atom(async (get) => (await get(asyncAtom)) / 2)

This also applies to an atom with write function.

const asyncAtom = atom(async (get) => ...)
const writeAtom = atom(null, async (get, set, payload) => {
  await get(asyncAtom)
  // ...
})

Async write atom Copy Chapter

Async write atoms are another kind of async atom. When the write function of atom returns a promise.

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 Copy Chapter

An interesting pattern that can be achieved with Jotai is switching from async to sync to trigger suspending when wanted.

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 Copy Section

In TypeScript atom(0) is inferred as PrimitiveAtom<number>. It cannot accept Promise<number> as a value so preceding code would not typecheck. To accommodate for that you need to type your atom explicitly and add Promise<number> as accepted value.

const baseAtom = atom<number | Promise<number>>(0) // Will accept sync and async values

Async forever Copy Chapter

Sometimes you may want to suspend until an unpredetermined moment (or never).

const baseAtom = atom(new Promise(() => {})) // Will be suspend until set otherwise

Suspense Copy Chapter

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 to avoid suspending

To use async atoms, you need to wrap your component tree with <Suspense>.

If you have a , place **at least one** `<Suspense>` inside said ; otherwise, it may cause an endless loop while rendering the components.

const App = () => (
  <Provider>
    <Suspense fallback="Loading...">
      <Layout />
    </Suspense>
  </Provider>
)

Having more <Suspense>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`) Copy Section

title: Atoms in atom nav: 8.12 Copy Chapter

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 Copy Section

First things first, we can store an atom config in useState.

const Component = ({ atom1, atom2 }) => {
  const [selectedAtom, setSelectedAtom] = useState(atom1)
  const [value] = useAtom(selectedAtom)
  return (
    <div>
      Selected value: {value}
      <button onClick={() => setSelectedAtom(atom1)}>Select an atom</button>
      <button onClick={() => setSelectedAtom(atom2)}>
        Select another atom
      </button>
    </div>
  )
}

Note that we can pass atoms configs as props.

It might not make any sense, but we could create an atom config on demand.

const Component = () => {
  const [currentAtom, setCurrentAtom] = useState(() => atom(0))
  const [count, setCount] = useAtom(currentAtom)
  return (
    <div>
      Count: {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
      <button onClick={() => setCurrentAtom(atom(0))}>Create new</button>
    </div>
  )
}

Storing an atom config in atom Copy Section

Likewise, we can store an atom config as a value of another atom.

const firstNameAtom = atom('Tanjiro')
const lastNameAtom = atom('Kamado')

const showingNameAtom = atom(firstNameAtom)

const Component = () => {
  const [nameAtom, setNameAtom] = useAtom(showingNameAtom)
  const [name] = useAtom(nameAtom)
  return (
    <div>
      Name: {name}
      <button onClick={() => setNameAtom(firstNameAtom)}>
        Show First Name
      </button>
      <button onClick={() => setNameAtom(lastNameAtom)}>Show Last Name</button>
    </div>
  )
}

It's possible to create a derived atom.

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 Copy Section

Finally, the atoms in atom pattern is to store an array of atom config into an atom.

const countsAtom = atom([atom(1), atom(2), atom(3)])

const Counter = ({ countAtom }) => {
  const [count, setCount] = useAtom(countAtom)
  return (
    <div>
      {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  )
}

const Parent = () => {
  const [counts, setCounts] = useAtom(countsAtom)
  const addNewCount = () => {
    const newAtom = atom(0)
    setCounts((prev) => [...prev, newAtom])
  }
  return (
    <div>
      {counts.map((countAtom) => (
        <Counter countAtom={countAtom} key={countAtom} />
      ))}
      <button onClick={addNewCount}>Add</button>
    </div>
  )
}

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

<Counter countAtom={countAtom} key={`${countAtom}`} />

Storing a map of atom configs in atom Copy Section

Likewise, we can store an object map instead of an array.

const pricesAtom = atom({
  apple: atom(15),
  orange: atom(12),
  pineapple: atom(25),
})

const Fruit = ({ name, priceAtom }) => {
  const [price] = useAtom(priceAtom)
  return (
    <div>
      {name}: {price}
    </div>
  )
}

const Parent = () => {
  const [prices] = useAtom(pricesAtom)
  return (
    <div>
      {Object.keys(prices).map((name) => (
        <Fruit name={name} priceAtom={prices[name]} key={name} />
      ))}
    </div>
  )
}

Guides Composing Atoms (`docs/guides/composing-atoms.mdx`) Copy Section

title: Composing atoms nav: 8.11 Copy Chapter

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 Copy Section

Here's one of the simplest examples of a derived atom:

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:

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 Copy Section

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.

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.

Next, let's see another example to sync with external value.

Syncing atom values with external values Copy Section

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.

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.

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 Copy Section

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:

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 Copy Section

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:

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.

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:

// 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 Copy Section

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

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`) Copy Section

title: Core internals nav: 8.10 Copy Chapter

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

First Version Copy Section

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.

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

Ref tweet: Demystifying the internal of jotai

Second Version Copy Section

Hang on! We can do better. In Jotai, we can create derived atom. A derived atom is an atom that depends on other atoms.

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.

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

Ref tweet: Supporting derived atoms

Guides Debugging (`docs/guides/debugging.mdx`) Copy Section

title: Debugging nav: 8.07 keywords: debug,labels,devtools,freeze Copy Chapter

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 Copy Chapter

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:<no debugLabel> 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.

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 and @swc-jotai/debug-label

Using React Dev Tools Copy Chapter

You can use React Dev Tools
to inspect Jotai state. To achieve that useDebugValue
is used inside custom hooks. Keep in mind that it only works in dev mode
(such as NODE_ENV === 'development').

useAtom Copy Section

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 Copy Section

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:

const DebugAtoms = () => {
  useAtomsDebugValue()
  return null
}

const Root = () => (
  <Provider>
    <DebugAtoms />
    <App />
  </Provider>
)

Using Redux DevTools Copy Chapter

You can also use Redux DevTools
to inspect atoms, with many features like Time-travelling and value dispatching.

[useAtomDevtools](https://jotai.org/docs/api/devtools#use-atom-devtools) Copy Section

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.

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

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:

{
  "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 Copy Chapter

To find bugs where you accidentally tried to mutate objects stored in atoms you
could use freezeAtom or freezeAtomCreatorfrom jotai/utils bundle.
Which returns atoms value that is deeply freezed with Object.freeze.

freezeAtom Copy Section

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

import { atom } from 'jotai'
import { freezeAtom } from 'jotai/utils'

const objAtom = freezeAtom(atom({ count: 0 }))

freezeAtomCreator Copy Section

If you need, you can define a factory for freezeAtom.

import { freezeAtom } from 'jotai/utils'

export function freezeAtomCreator<
  CreateAtom extends (...args: unknown[]) => Atom<unknown>,
>(createAtom: CreateAtom): CreateAtom {
  return ((...args: unknown[]) => freezeAtom(createAtom(...args))) as never
}

Guides Initialize Atom On Render (`docs/guides/initialize-atom-on-render.mdx`) Copy Section

title: Initializing state on render nav: 8.13 Copy Chapter

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 Copy Section

CodeSandbox link: codesandbox.

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.

const textAtom = atom('')

const PrettyText = () => {
  const [text] = useAtom(textAtom)
  return (
    <>
      <text
        style={{
          color: 'blue',
        }}
      >
        {text}
      </text>
    </>
  )
}

const UpdateTextInput = () => {
  const [text, setText] = useAtom(textAtom)
  const handleInputChange = (e) => {
    setText(e.target.value)
  }
  return (
    <>
      <input onChange={handleInputChange} value={text} />
    </>
  )
}

const HydrateAtoms = ({ initialValues, children }) => {
  // initialising on state with prop on render here
  useHydrateAtoms(initialValues)
  return children
}

export const TextDisplay = ({ initialTextValue }) => (
  <Provider>
    <HydrateAtoms initialValues={[[textAtom, initialTextValue]]}>
      <PrettyText />
      <br />
      <UpdateTextInput />
    </HydrateAtoms>
  </Provider>
)

Now, we can easily reuse TextDisplay component with different initial text values despite them referencing the "same" atom.

export default function App() {
  return (
    <div className="App">
      <TextDisplay initialTextValue="initial text value 1" />

      <TextDisplay initialTextValue="initial text value 2" />
    </div>
  )
}

This behavior is due to our child components looking for the lowest common Provider ancestor to derive its value.

For more information on Provider behavior, please read the docs here.

For more complex use cases, check out Scope extension.

Using Typescript Copy Section

useHydrateAtoms has overloaded types and typescript cannot extract types from overloaded function. It is recommended to use a Map when passing initial atom values to the useHydrateAtoms.

Here is a working example:

import type { ReactNode } from 'react'
import { Provider, atom, useAtomValue } from 'jotai'
import type { WritableAtom } from 'jotai'
import { useHydrateAtoms } from 'jotai/utils'

const testAtom = atom('')

export default function App() {
  return (
    <Provider>
      <AtomsHydrator atomValues={[[testAtom, 'hello']]}>
        <Component />
      </AtomsHydrator>
    </Provider>
  )
}

//This component contains all the states and the logic
function Component() {
  const testAtomValue = useAtomValue(testAtom)
  return <div>{testAtomValue}</div>
}

function AtomsHydrator({
  atomValues,
  children,
}: {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  atomValues: Iterable<
    readonly [WritableAtom<unknown, [any], unknown>, unknown]
  >
  children: ReactNode
}) {
  useHydrateAtoms(new Map(atomValues))
  return children
}

Guides Migrating To V2 Api (`docs/guides/migrating-to-v2-api.mdx`) Copy Section

title: v2 API migration nav: 8.0 Copy Chapter

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 Copy Section

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.

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.

atom(
  (get) => get(...),
  (get, set, arg1, arg2, ...) => {
    ...
    return someValue
  }
)

What are breaking Copy Section

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)

// Old
WritableAtom<Value, Arg, Result extends void | Promise<void>>

// New
WritableAtom<Value, Args extends unknown[], Result>

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 Copy Section

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

const asyncAtom = atom(async () => 'hello')
const derivedAtom = atom((get) => get(asyncAtom).toUppercase())

New API

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

const countAtom = atom(0)

  // in component
  <Provider initialValues={[[countAtom, 1]]}>
    ...

New API

const countAtom = atom(0)

const HydrateAtoms = ({ initialValues, children }) => {
  useHydrateAtoms(initialValues)
  return children
}

  // in component
  <Provider>
    <HydrateAtoms initialValues={[[countAtom, 1]]}>
      ...

Provider's `scope` prop

Previous API

const myScope = Symbol()

  // Parent component
  <Provider scope={myScope}>
    ...
  </Provider>

  // Child component
  useAtom(..., myScope)

New API

const MyContext = createContext()
const store = createStore()

  // Parent component
  <MyContext.Provider value={store}>
    ...
  </MyContext.Provider>

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

const asyncAtom = abortableAtom(async (get, { signal }) => {
 ...
}

New API

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

const allAtom = waitForAll([fooAtom, barAtom])

New API

const allAtom = atom((get) => Promise.all([get(fooAtom), get(barAtom)]))

Note that creating an atom in render function can cause infinite loop

`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

const splittedAtom = splitAtom(asyncArrayAtom)

New API

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 <Suspense>, 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 Copy Section

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

// 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`) Copy Section

title: v3 migration nav: 8.01 Copy Chapter

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
below.

Requirement changes Copy Section

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 Copy Section

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.

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 Copy Section

`atomFamily` util

It's moved to the jotai-family package.

Previous API

import { atomFamily } from 'jotai/utils'

New API

// npm install jotai-family
import { atomFamily } from 'jotai-family'

`loadable` util

Use the unwrap util instead.
The previous behavior can be implemented in userland:

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

// babel config
plugins: ['jotai/babel/plugin-react-refresh']

New API

// npm install jotai-babel
plugins: ['jotai-babel/plugin-react-refresh']

`setSelf` option in the read function

Previous API

const anAtom = atom(async (get, { setSelf }) => {
  // ...
})

New API

There is no direct replacement.
Depending on the use case,
onMount or jotai-effect
would cover it.

`delay` option in `useAtom` and `useAtomValue`

Previous API

const value = useAtomValue(anAtom, { delay: 100 })

New API

Create a custom hook:

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 Copy Section

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: like
  useAtomValue, but it never suspends. An async atom's value is returned
  without being consumed through React's use().
• 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
for when to reach for them.

Guides Nextjs (`docs/guides/nextjs.mdx`) Copy Section

title: Next.js nav: 8.03 keywords: next,nextjs Copy Chapter

Hydration Copy Section

Jotai has support for hydration of atoms with useHydrateAtoms. The documentation for the hook can be seen here.

Browser storage Copy Section

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:

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:

import dynamic from 'next/dynamic'

const StoredPreferences = dynamic(
  () => import('../components/StoredPreferences'),
  {
    ssr: false,
  },
)

See the storage documentation for more details.

Sync with router Copy Section

It's possible to sync Jotai with the router. You can achieve this with atomWithHash:

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 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 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 Copy Section

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.

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 Copy Section

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 at the root of your app (or a subtree if you're using Jotai only for a part of your application).

import { Provider } from 'jotai'

function App({ Component, pageProps }: AppProps) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

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 Copy Section

Jotai provides SWC plugins for better DX while developing with Next.js. Find more info in the SWC section.

Examples Copy Section

Clock

HN Posts

Page Router demo:

App Router demo on Stackblitz

Next.js repo

npx create-next-app --example with-jotai with-jotai-app

Here's a link.

Guides Performance (`docs/guides/performance.mdx`) Copy Section

title: Performance nav: 8.08 keywords: performance Copy Chapter

Note: This guide has room for improvement. Consider it as FYI for now.

Jotai & React gives us quite a few tools to manage the re-renders that happen in the app lifecycle.
First, please read about the difference between render & commit, because that's very important to understand before going further.

Cheap renders Copy Section

As seen in the core section, due to React 18 default behaviour (but overall good practice), you have to make sure your component functions are idempotent.
They will be called multiple times during the render phase, even at mount. So we need to keep our renders cheap at all cost!

Heavy computation

Always make heavy computation outside of the React lifecycle (in actions for example)

Dont's:

// Heavy computation for each item
const selector = (s) => s.filter(heavyComputation)
const Profile = () => {
  const [computed] = useAtom(selectAtom(friendsAtom, selector))
}

Do's:

const friendsAtom = atom([])
const fetchFriendsAtom = atom(null, async (get, set, payload) => {
  // Fetch all friends
  const res = await fetch('https://jsonplaceholder.typicode.com/users')
  const data = await res.json()

  // Make heavy computation once only
  const computed = data.filter(heavyComputation)
  set(friendsAtom, computed)
})
// Usage in components
const Profile = () => {
  const [friends] = useAtom(friendsAtom)
}

Small components

Observed atoms should only re-render small parts of your application that required an update. The less comparison React has to make, the shorter your render time will be.

Dont's:

const Profile = () => {
  const [name] = useAtom(nameAtom)
  const [age] = useAtom(ageAtom)
  return (
    <>
      <div>{name}</div>
      <div>{age}</div>
    </>
  )
}

Do's:

const NameComponent = () => {
  const [name] = useAtom(nameAtom)
  return <div>{name}</div>
}
const AgeComponent = () => {
  const [age] = useAtom(ageAtom)
  return <div>{age}</div>
}
const Profile = () => {
  return (
    <>
      <NameComponent />
      <AgeComponent />
    </>
  )
}

Render on demand Copy Section

Usually, the main performance overhead will come from re-rendering parts of your app that did not need to, or way more than they should.

We have a few tools to deal with "when" React should render our components. If you have not seen the usage of useMemo and useCallback, please check the official React documentation for more info before going further.
They are of great use to reduce un-necessary renders where your app is not fluid.

But Jotai also provides its set of tools to handle the "when" our atoms should trigger a re-render.

• Out of the box, Jotai encourages you to split your data into atomic parts, hence each atom is stored separately and will only trigger a re-render when their own value change
• selectAtom allows you to subscribe to specific part of a large object and only re-render on value change
• focusAtom same as selectAtom, but creating a new atom for the part, giving a setter to update that specific part easily
• splitAtom does the work of selectAtom/focusAtom for a dynamic list

While this seems simplistic, it is simple to reason about. That was the goal, let's keep it simple to keep it fast.

Frequent or rare updates

Ask yourself whether your atom is usually going to be frequently update or more rarely.
Let's imagine an atom containing an object that changes almost every second, it may not be best suited to "focus" on a specific properties of this object using focusAtom, because anyway they will all re-render in the same time, so best adding no overhead and not create any more atoms.

On the other hand, if your object has properties that rarely change, and most importantly, that change independently from the other properties, then you may want to use focusAtom or selectAtom to prevent un-necessary renders.

Dependency graph depth Copy Section

Jotai computes a derived atom by running its read function and synchronously reading each dependency it gets, which in turn reads their dependencies. This recursion runs on the JavaScript call stack, so the depth of a dependency chain is bounded by the engine's stack size, typically a few thousand levels depending on the engine and how much work each read does.

This is almost never a problem, because real graphs are wide rather than deep: an atom usually depends on a handful of others, not on a chain thousands of atoms long. Breadth is essentially unlimited; only chain length matters.

You can hit the limit by accident if you model a collection as a chain of derived atoms (each atom deriving from the previous one) instead of as data inside a single atom. Reading the end of a long enough chain throws a RangeError: Maximum call stack size exceeded (or too much recursion on Firefox). As of v2, this surfaces at the call site that triggered the read, rather than being silently swallowed, so you find out immediately instead of getting a corrupted graph.

Dont's:

// A linear chain: each atom depends on the previous one. Reading `last`
// recurses once per link, so a few thousand items can overflow the stack.
let prev = atom(0)
for (const value of veryLongList) {
  const node = prev
  prev = atom((get) => get(node) + value)
}
const last = prev

Do's:

// Keep the collection in one atom and derive over it in a single read.
// The depth is constant (1) no matter how long the list is.
const listAtom = atom(veryLongList)
const totalAtom = atom((get) => get(listAtom).reduce((a, b) => a + b, 0))

For a dynamic list whose items each need to be their own atom (for example, to render and update rows independently), reach for splitAtom rather than chaining. It gives you one atom per item that all derive directly from the source atom, so the graph stays one level deep instead of growing with the list.

If you genuinely need a deep computation, run it as a plain reduction inside a single atom's read (or in a write action) rather than spreading it across many chained atoms.

Guides Persistence (`docs/guides/persistence.mdx`) Copy Section

title: Persistence nav: 8.14 Copy Chapter

Jotai has an atomWithStorage function in the utils bundle for persistence that supports persisting state in sessionStorage, localStorage, AsyncStorage, or the URL hash.

(Note: This guide is a bit outdated and requires some rewrites.)

There are also several alternate implementations here:

A simple pattern with localStorage Copy Section

const strAtom = atom(localStorage.getItem('myKey') ?? 'foo')

const strAtomWithPersistence = atom(
  (get) => get(strAtom),
  (get, set, newStr) => {
    set(strAtom, newStr)
    localStorage.setItem('myKey', newStr)
  },
)

A helper function with localStorage and JSON parse Copy Section

const atomWithLocalStorage = (key, initialValue) => {
  const getInitialValue = () => {
    const item = localStorage.getItem(key)
    if (item !== null) {
      return JSON.parse(item)
    }
    return initialValue
  }
  const baseAtom = atom(getInitialValue())
  const derivedAtom = atom(
    (get) => get(baseAtom),
    (get, set, update) => {
      const nextValue =
        typeof update === 'function' ? update(get(baseAtom)) : update
      set(baseAtom, nextValue)
      localStorage.setItem(key, JSON.stringify(nextValue))
    },
  )
  return derivedAtom
}

(Error handling should be added.)

A helper function with AsyncStorage and JSON parse Copy Section

This requires onMount.

const atomWithAsyncStorage = (key, initialValue) => {
  const baseAtom = atom(initialValue)
  baseAtom.onMount = (setValue) => {
    ;(async () => {
      const item = await AsyncStorage.getItem(key)
      setValue(JSON.parse(item))
    })()
  }
  const derivedAtom = atom(
    (get) => get(baseAtom),
    (get, set, update) => {
      const nextValue =
        typeof update === 'function' ? update(get(baseAtom)) : update
      set(baseAtom, nextValue)
      AsyncStorage.setItem(key, JSON.stringify(nextValue))
    },
  )
  return derivedAtom
}

Don't forget to check out the Async documentation for more details on how to use async atoms.

Example with sessionStorage Copy Section

Same as AsyncStorage, just use atomWithStorage util and override the default storage with the sessionStorage

import { atomWithStorage, createJSONStorage } from 'jotai/utils'

const storage = createJSONStorage(() =>
  typeof window !== 'undefined' ? window.sessionStorage : undefined,
)
const someAtom = atomWithStorage('some-key', someInitialValue, storage)

A serialize atom pattern Copy Section

type Actions =
  | { type: 'serialize'; callback: (value: string) => void }
  | { type: 'deserialize'; value: string }

const serializeAtom = atom(null, (get, set, action: Actions) => {
  if (action.type === 'serialize') {
    const obj = {
      todos: get(todosAtom).map(get),
    }
    action.callback(JSON.stringify(obj))
  } else if (action.type === 'deserialize') {
    const obj = JSON.parse(action.value)
    // needs error handling and type checking
    set(
      todosAtom,
      obj.todos.map((todo: Todo) => atom(todo)),
    )
  }
})

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 (
    <div>
      <button onClick={save}>Save to localStorage</button>
      <button onClick={load}>Load from localStorage</button>
    </div>
  )
}

Examples

type Actions =
  | { type: 'serialize'; callback: (value: string) => void }
  | { type: 'deserialize'; value: string }

const serializeAtom = atom(null, (get, set, action: Actions) => {
  if (action.type === 'serialize') {
    const todos = get(todosAtom)
    const todoMap: Record<string, { title: string; completed: boolean }> = {}
    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 (
    <div>
      <button onClick={save}>Save to localStorage</button>
      <button onClick={load}>Load from localStorage</button>
    </div>
  )
}

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

const todoListAtom = atomWithReset([
  { description: 'Add a todo', checked: false },
])

const TodoList = () => {
  const [todoList, setTodoList] = useAtom(todoListAtom)
  const resetTodoList = useResetAtom(todoListAtom)

  return (
    <>
      <ul>
        {todoList.map((todo) => (
          <li>{todo.description}</li>
        ))}
      </ul>

      <button
        onClick={() =>
          setTodoList((l) => [
            ...l,
            {
              description: `New todo ${new Date().toDateString()}`,
              checked: false,
            },
          ])
        }
      >
        Add todo
      </button>
      <button onClick={resetTodoList}>Reset</button>
    </>
  )
}

import { atom, useAtom, useSetAtom } from 'jotai'
import { atomWithReset, useResetAtom, RESET } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const centsAtom = atom(
  (get) => get(dollarsAtom) * 100,
  (get, set, newValue: number | typeof RESET) =>
    set(dollarsAtom, newValue === RESET ? newValue : newValue / 100)
)

const ResetExample = () => {
  const [dollars] = useAtom(dollarsAtom)
  const setCents = useSetAtom(centsAtom)
  const resetCents = useResetAtom(centsAtom)

  return (
    <>
      <h3>Current balance ${dollars}</h3>
      <button onClick={() => setCents(100)}>Set $1</button>
      <button onClick={() => setCents(200)}>Set $2</button>
      <button onClick={resetCents}>Reset</button>
    </>
  )
}

import { atom, useAtom } from 'jotai'

export const countAtom = atom(0)

export function Counter() {
  const [count, setCount] = useAtom(countAtom)
  return (
    <h1>
      <p>{count}</p>
      <button onClick={() => setCount((c) => c + 1)}>one up</button>
    </h1>
  )
}

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(<Counter />)

  const counter = screen.getByText('0')
  const incrementButton = screen.getByText('one up')
  // Act
  await userEvent.click(incrementButton)
  // Assert
  expect(counter.textContent).toEqual('1')
})

import React from 'react'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { useHydrateAtoms } from 'jotai/utils'
import { countAtom, Counter } from './Counter'
import { Provider } from 'jotai'

const HydrateAtoms = ({ initialValues, children }) => {
  useHydrateAtoms(initialValues)
  return children
}

const TestProvider = ({ initialValues, children }) => (
  <Provider>
    <HydrateAtoms initialValues={initialValues}>{children}</HydrateAtoms>
  </Provider>
)

const CounterProvider = () => {
  return (
    <TestProvider initialValues={[[countAtom, 100]]}>
      <Counter />
    </TestProvider>
  )
}

test('should not increment on max (100)', () => {
  render(<CounterProvider />)

  const counter = screen.getByText('100')
  const incrementButton = screen.getByText('one up')
  await userEvent.click(incrementButton)
  expect(counter.textContent).toEqual('100')
})

import { useAtom } from 'jotai'
import { atomWithReducer } from 'jotai/utils'

const reducer = (state: number, action?: 'INCREASE' | 'DECREASE') => {
  switch (action) {
    case 'INCREASE':
      return state + 1
    case 'DECREASE':
      return state - 1
    case undefined:
      return state
  }
}
export const countAtom = atomWithReducer(0, reducer)

import { renderHook, act } from '@testing-library/react-hooks'
import { useAtom } from 'jotai'
import { countAtom } from './countAtom'

test('should increment counter', () => {
  const { result } = renderHook(() => useAtom(countAtom))

  act(() => {
    result.current[1]('INCREASE')
  })

  expect(result.current[0]).toBe(1)
})

import React from 'react'
import { render, fireEvent } from '@testing-library/react-native'
import { Counter } from './counter'

test('should increment counter', () => {
  // Arrange
  const { getByText } = render(<Counter />)
  const counter = getByText('0')
  const incrementButton = getByText('one up')
  // Act
  fireEvent.press(incrementButton)
  // Assert
  expect(counter.props.children.toString()).toEqual('1')
})

const numAtom = atom(0) // primitive number atom
const strAtom = atom('') // primitive string atom

const numAtom = atom<number>(0)
const numAtom = atom<number | null>(0)
const arrAtom = atom<string[]>([])

# Read only derived atoms
const readOnlyAtom = atom((get) => get(numAtom))
const asyncReadOnlyAtom = atom(async (get) => await get(someAsyncAtom))

# Write only atoms
const writeOnlyAtom = atom(null, (_get, set, str: string) => set(fooAtom, str))
const multipleArgumentsAtom = atom(
  null,
  (_get, set, valueOne: number, valueTwo: number) =>
    set(fooAtom, Math.max(valueOne, valueTwo))
);

# Read/Write atoms
const readWriteAtom = atom(
  (get) => get(strAtom),
  (_get, set, num: number) => set(strAtom, String(num))
)
const asyncReadWriteAtom = atom(
  async (get) => await get(asyncStrAtom),
  (_get, set, num: number) => set(strAtom, String(num))
)

const asyncStrAtom = atom<Promise<string>>(async () => 'foo')

/**
 * For write only atoms you'll need to supply three type parameters.
 * The first type parameter describes the value returned from the atom. In the following example this is `null`.
 * The second type parameter describes the arguments (plural) you will pass to the "write" function. Even if you only
 * plan to have one argument, this type must be an array as show in the example.
 * The third type parameter describes the return value of the "write" function. Normally, there is no return value,
 * which is why we use `void` in the example below.
 */
const writeOnlyAtom = atom<null, [string, number], void>(
  null,
  (_get, set, stringValue, numberValue) => set(fooAtom, stringValue),
)

/**
 * Read/Write atoms also take the same three type parameters.
 * Just for the sake of completeness, in this example, we show that the first type parameter
 * can also describe an async atom.
 */
const readWriteAtom = atom<Promise<string>, [number], void>(
  async (get) => await get(asyncStrAtom),
  (_get, set, num) => set(strAtom, String(num)),
)

const [num, setNum] = useAtom(primitiveNumAtom)
const [num] = useAtom(readOnlyNumAtom)
const [, setNum] = useAtom(writeOnlyNumAtom)

import { ExtractAtomValue, useAtomValue } from 'jotai'
import { userAtom } from 'state'
import { useQuery } from '@tanstack/react-query'

export default function WriteReview(hid) {
  const user = useAtomValue(userAtom)
  const res = useGetReviewQuery(user)
}

function useGetReviewQuery(user: ExtractAtomValue<typeof userAtom>) {
  return fetch('/api/user/' + user.id + '/review')
}

import { atom, useAtomValue, createStore, Provider } from 'jotai'

const timeAtom = atom(0)
const store = createStore()

store.set(timeAtom, (prev) => prev + 1) // Update atom's value
store.get(timeAtom) // Read atom's value

function Component() {
  const time = useAtomValue(timeAtom) // Inside React
  return (
    <div className="App">
      <h1>{time}</h1>
    </div>
  )
}

export default function App() {
  return (
    <Provider store={store}>
      <Component />
    </Provider>
  )
}

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import babel from '@rolldown/plugin-babel'
import jotaiDebugLabel from 'jotai-babel/plugin-debug-label'
import jotaiReactRefresh from 'jotai-babel/plugin-react-refresh'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    babel({
      plugins: [jotaiDebugLabel, jotaiReactRefresh],
    }),
  ],
  // ... The rest of your configuration
})

import { atom, SetStateAction } from 'jotai'

export function atomWithBroadcast<Value>(key: string, initialValue: Value) {
  const baseAtom = atom(initialValue)
  const listeners = new Set<(event: MessageEvent<any>) => void>()
  const channel = new BroadcastChannel(key)

  channel.onmessage = (event) => {
    listeners.forEach((l) => l(event))
  }

  const broadcastAtom = atom(
    (get) => get(baseAtom),
    (get, set, update: { isEvent: boolean; value: SetStateAction<Value> }) => {
      set(baseAtom, update.value)

      if (!update.isEvent) {
        channel.postMessage(get(baseAtom))
      }
    },
  )

  broadcastAtom.onMount = (setAtom) => {
    const listener = (event: MessageEvent<any>) => {
      setAtom({ isEvent: true, value: event.data })
    }

    listeners.add(listener)

    return () => {
      listeners.delete(listener)
    }
  }

  const returnedAtom = atom(
    (get) => get(broadcastAtom),
    (_get, set, update: SetStateAction<Value>) => {
      set(broadcastAtom, { isEvent: false, value: update })
    },
  )

  return returnedAtom
}

const broadAtom = atomWithBroadcast('count', 0)

const ListOfThings = () => {
  const [count, setCount] = useAtom(broadAtom)

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

import { atomWithReducer } from 'jotai/utils'

export function atomWithCompare<Value>(
  initialValue: Value,
  areEqual: (prev: Value, next: Value) => boolean,
) {
  return atomWithReducer(initialValue, (prev: Value, next: Value) => {
    if (areEqual(prev, next)) {
      return prev
    }

    return next
  })
}

import { atomWithCompare } from 'XXX'
import { shallowEquals } from 'YYY'
import { CSSProperties } from 'react'

const styleAtom = atomWithCompare<CSSProperties>(
  { backgroundColor: 'blue' },
  shallowEquals,
)

const StylePreview = () => {
  const [styles, setStyles] = useAtom(styleAtom)

  return (
    <div>
      <div styles={styles}>Style preview</div>

      {/* Clicking this button twice will only trigger one render */}
      <button onClick={() => setStyles({ ...styles, backgroundColor: 'red' })}>
        Set background to red
      </button>

      {/* Clicking this button twice will only trigger one render */}
      <button onClick={() => setStyles({ ...styles, fontSize: 32 })}>
        Enlarge font
      </button>
    </div>
  )
}

/* Detailed source-code truncated for AI context efficiency. */

import { useEffect } from 'react'
import {
  atom,
  useAtom,
  useSetAtom,
  Getter,
  Setter,
  SetStateAction,
} from 'jotai'

type Callback<Value> = (
  get: Getter,
  set: Setter,
  newVal: Value,
  prevVal: Value,
) => void

export function atomWithListeners<Value>(initialValue: Value) {
  const baseAtom = atom(initialValue)
  const listenersAtom = atom<Callback<Value>[]>([])
  const anAtom = atom(
    (get) => get(baseAtom),
    (get, set, arg: SetStateAction<Value>) => {
      const prevVal = get(baseAtom)
      set(baseAtom, arg)
      const newVal = get(baseAtom)
      get(listenersAtom).forEach((callback) => {
        callback(get, set, newVal, prevVal)
      })
    },
  )
  const useListener = (callback: Callback<Value>) => {
    const setListeners = useSetAtom(listenersAtom)
    useEffect(() => {
      setListeners((prev) => [...prev, callback])
      return () =>
        setListeners((prev) => {
          const index = prev.indexOf(callback)
          return [...prev.slice(0, index), ...prev.slice(index + 1)]
        })
    }, [setListeners, callback])
  }
  return [anAtom, useListener] as const
}

const [countAtom, useCountListener] = atomWithListeners(0)

function EvenCounter() {
  const [evenCount, setEvenCount] = useAtom(countAtom)

  useCountListener(
    useCallback(
      (get, set, newVal, prevVal) => {
        // Every time `countAtom`'s value is set, we check if its new value
        // is even, and if it is, we increment `evenCount`.
        if (newVal % 2 === 0) {
          setEvenCount((c) => c + 1)
        }
      },
      [setEvenCount],
    ),
  )

  return <>Count was set to an even number {evenCount} times.</>
}

const refreshCountAtom = atom(0)

const baseDataAtom = atom(1) // original data, e.g. base count1Atom
const dataAtom = atom(
  (get) => {
    get(refreshCountAtom) // it's introduced at atomWithRefresh
    return get(baseDataAtom)
  },
  (get, set, update) => {
    set(baseDataAtom, update)
  },
)

const atomWithRefreshAndDefault = (refreshAtom, getDefault) => {
  const overwrittenAtom = atom(null)
  return atom(
    (get) => {
      const lastState = get(overwrittenAtom)
      if (lastState && lastState.refresh === get(refreshAtom)) {
        return lastState.value
      }
      return getDefault(get)
    },
    (get, set, update) => {
      set(overwrittenAtom, { refresh: get(refreshAtom), value: update })
    },
  )
}

// This is an alternative of `atomWithDefault((get) => get(count1Atom) * 2)`
const refreshableAtom = atomWithRefreshAndDefault(
  refreshCountAtom,
  (get) => get(dataAtom) * 2,
)

// You can reset by updating just one atom
const resetRootAtom = atom(null, (get, set) => {
  set(refreshCountAtom, get(refreshCountAtom) + 1)
})

import { WritableAtom, atom } from 'jotai'
import { atomWithStorage } from 'jotai/utils'

export function atomWithToggleAndStorage(
  key: string,
  initialValue?: boolean,
  storage?: any,
): WritableAtom<boolean, [boolean?], void> {
  const anAtom = atomWithStorage(key, initialValue, storage)
  const derivedAtom = atom(
    (get) => get(anAtom),
    (get, set, nextValue?: boolean) => {
      const update = nextValue ?? !get(anAtom)
      void set(anAtom, update)
    },
  )

  return derivedAtom as WritableAtom<boolean, [boolean?], void>
}

import { atomWithToggleAndStorage } from 'XXX'

// will have an initial value set to false & get stored in localStorage under the key "isActive"
const isActiveAtom = atomWithToggleAndStorage('isActive')

import { WritableAtom, atom } from 'jotai'

export function atomWithToggle(
  initialValue?: boolean,
): WritableAtom<boolean, [boolean?], void> {
  const anAtom = atom(initialValue, (get, set, nextValue?: boolean) => {
    const update = nextValue ?? !get(anAtom)
    set(anAtom, update)
  })

  return anAtom as WritableAtom<boolean, [boolean?], void>
}

import { atomWithToggle } from 'XXX'

// will have an initial value set to true
const isActiveAtom = atomWithToggle(true)

const Toggle = () => {
  const [isActive, toggle] = useAtom(isActiveAtom)

  return (
    <>
      <button onClick={() => toggle()}>
        isActive: {isActive ? 'yes' : 'no'}
      </button>
      <button onClick={() => toggle(true)}>force true</button>
      <button onClick={() => toggle(false)}>force false</button>
    </>
  )
}

import { useAtomValue } from 'jotai'
import { selectAtom } from 'jotai/utils'

export function useSelectAtom(anAtom, selector) {
  const selectorAtom = selectAtom(
    anAtom,
    selector,
    // Alternatively, you can customize `equalityFn` to determine when it will rerender
    // Check selectAtom's signature for details.
  )
  return useAtomValue(selectorAtom)
}

// how to use it
function useN(n) {
  const selector = useCallback((v) => v[n], [n])
  return useSelectAtom(arrayAtom, selector)
}

import { useAtom } from 'jotai'
import { freezeAtom } from 'jotai/utils'

export function useFreezeAtom(anAtom) {
  return useAtom(freezeAtom(anAtom))
}

import { useAtom } from 'jotai'
import { splitAtom } from 'jotai/utils'

export function useSplitAtom(anAtom) {
  return useAtom(splitAtom(anAtom))
}

import { useAtom } from 'jotai'
import { focusAtom } from 'jotai-optics'

/* if an atom is created here, please use `useMemo(() => atom(initValue), [initValue])` instead. */
export function useFocusAtom(anAtom, keyFn) {
    return useAtom(focusAtom(anAtom, keyFn))
}

// how to use it
useFocusAtom(anAtom) {
    useMemo(() => atom(initValue), [initValue]),
    useCallback((optic) => optic.prop('key'), [])
}

const initialData = {
  people: [
    {
      name: 'Luke Skywalker',
      information: { height: 172 },
      siblings: ['John Skywalker', 'Doe Skywalker'],
    },
    {
      name: 'C-3PO',
      information: { height: 167 },
      siblings: ['John Doe', 'Doe John'],
    },
  ],
  films: [
    {
      title: 'A New Hope',
      planets: ['Tatooine', 'Alderaan'],
    },
    {
      title: 'The Empire Strikes Back',
      planets: ['Hoth'],
    },
  ],
  info: {
    tags: ['People', 'Films', 'Planets', 'Titles'],
  },
}

import { atom } from 'jotai'
import { focusAtom } from 'jotai-optics'

const dataAtom = atom(initialData)

const peopleAtom = focusAtom(dataAtom, (optic) => optic.prop('people'))

import { splitAtom } from 'jotai/utils'

const peopleAtomsAtom = splitAtom(peopleAtom)

const People = () => {
  const [peopleAtoms] = useAtom(peopleAtomsAtom)
  return (
    <div>
      {peopleAtoms.map((personAtom) => (
        <Person personAtom={personAtom} key={`${personAtom}`} />
      ))}
    </div>
  )
}

// first we create a derived atom based on initialData.info
const infoAtom = atom((get) => get(dataAtom).info)

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 (
    <div>
      {tagAtoms.map((tagAtom) => (
        <Tag key={`${tagAtom}`} tagAtom={tagAtom} />
      ))}
    </div>
  )
}

import { useMemoOne as useStableMemo } from 'use-memo-one'
import { useAtomValue } from 'jotai/react'
import { atomEffect } from 'jotai-effect'

type EffectFn = Parameters<typeof atomEffect>[0]

export function useAtomEffect(effectFn: EffectFn) {
  useAtomValue(useStableMemo(() => atomEffect(effectFn), [effectFn]))
}

import { useCallbackOne as useStableCallback } from 'use-memo-one'
import { atom, useAtom } from 'jotai'
import { atomFamily } from 'jotai/utils'
import { useAtomEffect } from './useAtomEffect'

const channelSubscriptionAtomFamily = atomFamily<Channel>(
  (channelId: string) => {
    return atom(new Channel(channelId))
  },
)
const messagesAtom = atom<Message[]>([])

function Messages({ channelId }: { channelId: string }) {
  const [messages] = useAtom(messagesAtom)
  useAtomEffect(
    useStableCallback(
      (get, set) => {
        const channel = get(channelSubscriptionAtomFamily(channelId))
        const unsubscribe = channel.subscribe((message) => {
          set(messagesAtom, (prev) => [...prev, message])
        })
        return unsubscribe
      },
      [channelId],
    ),
  )
  return (
    <>
      <h1>You have {messages.length} messages</h1>
      <hr />
      {messages.map((message) => (
        <div key={message.id}>{message.text}</div>
      ))}
    </>
  )
}

import { useCallback } from 'react'
import { useAtom } from 'jotai'
import type { PrimitiveAtom } from 'jotai'

export function useReducerAtom<Value, Action>(
  anAtom: PrimitiveAtom<Value>,
  reducer: (v: Value, a: Action) => Value,
) {
  const [state, setState] = useAtom(anAtom)
  const dispatch = useCallback(
    (action: Action) => setState((prev) => reducer(prev, action)),
    [setState, reducer],
  )
  return [state, dispatch] as const
}

import { atom } from 'jotai'

const countReducer = (prev, action) => {
  if (action.type === 'inc') return prev + 1
  if (action.type === 'dec') return prev - 1
  throw new Error('unknown action type')
}

const countAtom = atom(0)

const Counter = () => {
  const [count, dispatch] = useReducerAtom(countAtom, countReducer)
  return (
    <div>
      {count}
      <button onClick={() => dispatch({ type: 'inc' })}>+1</button>
      <button onClick={() => dispatch({ type: 'dec' })}>-1</button>
    </div>
  )
}

npm install bunja

import { bunja } from 'bunja'
import { useBunja } from 'bunja/react'

const countBunja = bunja(() => {
  const countAtom = atom(0)

  bunja.effect(() => {
    console.log('mounted')
    return () => console.log('unmounted')
  })

  return { countAtom }
})

function MyComponent() {
  const { countAtom } = useBunja(countBunja)
  const [count, setCount] = useAtom(countAtom)
  // Your component logic here
}

const formBunja = bunja.withSeed({ title: '' }, (seed) => {
  const titleAtom = atom(seed.title)
  return { titleAtom }
})

useBunja({ bunja: formBunja, seed: { title: 'Draft' } })

const pageBunja = bunja(() => {
  const pageStateAtom = atom({})
  return { pageStateAtom }
})

const childBunja = bunja(() => {
  const { pageStateAtom } = bunja.use(pageBunja)
  const childStateAtom = atom((get) => ({
    ...get(pageStateAtom),
    child: 'state',
  }))
  return { childStateAtom }
})

const modalBunja = bunja(() => {
  const { pageStateAtom } = bunja.use(pageBunja)
  const modalStateAtom = atom((get) => ({
    ...get(pageStateAtom),
    modal: 'state',
  }))

  bunja.effect(() => {
    console.log('modal opened')
    return () => console.log('modal closed')
  })

  return { modalStateAtom }
})

function Page() {
  const [modalOpen, setModalOpen] = useState(false)
  return (
    <>
      <Child />
      {modalOpen && <Modal />}
    </>
  )
}

function Child() {
  const { childStateAtom } = useBunja(childBunja)
  const childState = useAtomValue(childStateAtom)
  // ...
}

function Modal() {
  const { modalStateAtom } = useBunja(modalBunja)
  const modalState = useAtomValue(modalStateAtom)
  // ...
}

import { bunja, createScope } from 'bunja'

const UrlScope = createScope()

const fetchBunja = bunja(() => {
  const url = bunja.use(UrlScope)

  const queryAtom = atomWithQuery((get) => ({
    queryKey: [url],
    queryFn: async () => (await fetch(url)).json(),
  }))

  return { queryAtom }
})

import { createContext } from 'react'
import { bunja, createScope } from 'bunja'
import { bindScope } from 'bunja/react'

const UrlContext = createContext('https://example.com/')
const UrlScope = createScope()
bindScope(UrlScope, UrlContext)

const fetchBunja = bunja(() => {
  const url = bunja.use(UrlScope)

  const queryAtom = atomWithQuery((get) => ({
    queryKey: [url],
    queryFn: async () => (await fetch(url)).json(),
  }))

  return { queryAtom }
})

function ParentComponent() {
  return (
    <>
      <UrlContext value="https://example.com/foo">
        <ChildComponent />
      </UrlContext>
      <UrlContext value="https://example.com/bar">
        <ChildComponent />
      </UrlContext>
    </>
  )
}

function ChildComponent() {
  const { queryAtom } = useBunja(fetchBunja)
  const { data, isPending, isError } = useAtomValue(queryAtom)
  // Your component logic here
}

import { createContext } from 'react'
import { createScopeFromContext } from 'bunja/react'

const UrlContext = createContext('https://example.com/')
const UrlScope = createScopeFromContext(UrlContext)

function MyComponent() {
  const { queryAtom } = useBunja(fetchBunja, [
    UrlScope.bind('https://example.com/'),
  ])
  const { data, isPending, isError } = useAtomValue(queryAtom)
  // Your component logic here
}

const myBunja = bunja(() => {
  const fooData = bunja.use(fetchBunja, [
    UrlScope.bind('https://example.com/foo'),
  ])
  const barData = bunja.use(fetchBunja, [
    UrlScope.bind('https://example.com/bar'),
  ])

  return { fooData, barData }
})

npm install jotai-eager

const petsAtom = atom<Promise<string[]>>(...);
const filterAtom = atom('cat');

const filteredPetsAtom = atom(async (get) => {
  const filter = get(filterAtom)
  const pets = await get(petsAtom)
  return pets.filter((name) => name.includes(filter))
}) // => Atom<Promise<string[]>>

import { eagerAtom } from 'jotai-eager'

const filteredPetsAtom = eagerAtom((get) => {
  const filter = get(filterAtom)
  const pets = get(petsAtom) // ✨ no await ✨
  return pets.filter((name) => name.includes(filter))
}) // => Atom<Promise<string[]> | string[]>

const myMessages = eagerAtom((get) => {
  const [user, messages] = get.all([userAtom, messagesAtom])
  return messages.filter((msg) => msg.authorId === user.id)
}) // => Atom<Message[] | Promise<Message[]>>

const statusAtom = eagerAtom((get) => {
  const statusPromise = get(currentInvoiceAtom).getStatus() // => Promise<InvoiceStatus>
  const status = get.await(statusPromise)
  //    ^? InvoiceStatus
  return status
})

import { atom } from 'jotai';
import { loadable } from 'jotai-eager';

const asyncAtom = atom(async () => 'data');
const loadableAtom = loadable(asyncAtom);

// Use in component:
const state = useAtom(loadableAtom);
if (state.state === 'loading') return <div>Loading...</div>;
if (state.state === 'hasError') return <div>Error: {state.error}</div>;
return <div>{state.data}</div>;

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'

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
    }

    // ...
  }
})

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

import { soon } from 'jotai-eager'

// Given the following definitions:
//   const queryAtom: Atom<RestrictedItem | Promise<RestrictedItem>>;
//   const isAdminAtom: Atom<boolean | Promise<boolean>>;

// Atom<RestrictedItem | null | Promise<RestrictedItem | null>>
const restrictedItemAtom = atom((get) => {
  const isAdmin = get(isAdminAtom)
  return soon(isAdmin, (isAdmin) => (isAdmin ? get(queryAtom) : null))
})

import { soon, soonAll } from 'jotai-eager'

// Given the following definitions:
//   const queryAtom: Atom<RestrictedItem | Promise<RestrictedItem>>;
//   const isAdminAtom: Atom<boolean | Promise<boolean>>;
//   const enabledAtom: Atom<boolean | Promise<boolean>>;

// Atom<RestrictedItem | null | Promise<RestrictedItem | null>>
const restrictedItemAtom = atom((get) => {
  return soon(
    soonAll(get(isAdminAtom), get(enabledAtom)),
    ([isAdmin, enabled]) => (isAdmin && enabled ? get(queryAtom) : null),
  )
})

npm install jotai-history

import { withHistory } from 'jotai-history'

const targetAtom = atom(0)
const limit = 2
const historyAtom = withHistory(targetAtom, limit)

function Component() {
  const [current, previous] = useAtomValue(historyAtom)
  ...
}

{
  "plugins": ["jotai-babel/plugin-react-refresh"]
}

{
  "plugins": [
    ["jotai-babel/plugin-react-refresh", { "customAtomNames": ["customAtom"] }]
  ]
}

export const countAtom = atom(0)

export const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'

// countAtom.ts
export default atom(0)

// countAtom.ts
const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'
export default countAtom

{
  "plugins": ["jotai-babel/plugin-debug-label"]
}

{
  "plugins": [
    ["jotai-babel/plugin-debug-label", { "customAtomNames": ["customAtom"] }]
  ]
}

{
  "presets": ["jotai-babel/preset"]
}

{
  "presets": [["jotai-babel/preset", { "customAtomNames": ["customAtom"] }]]
}

npm install jotai-devtools

npm install -D jotai-babel

{
  "presets": [
    // The preset includes two plugins:
    // - jotai-babel/plugin-react-refresh to enable hot reload for atoms
    // - jotai-babel/plugin-debug-label to automatically adds debug labels to atoms
    'jotai-babel/preset'
  ]
}

// vite.config.ts

export default defineConfig({
  plugins: [
    react({
      babel: {
        presets: ['jotai-babel/preset'],
      },
    }),
  ],
})

npm install -D @rolldown/plugin-babel @babel/core

// vite.config.ts
import babel from '@rolldown/plugin-babel';

export default defineConfig({
  plugins: [
    react(),
    babel({
      presets: ['jotai-babel/preset'],
    })
  ],
})

// next.config.ts
const nextConfig = {
  // Learn more here - https://nextjs.org/docs/advanced-features/compiler#module-transpilation
  // Required for UI css to be transpiled correctly 👇
  transpilePackages: ['jotai-devtools'],
}
module.exports = nextConfig

type DevToolsProps = {
  // defaults to false
  isInitialOpen?: boolean
  // pass a custom store
  store?: Store
  // Defaults to light
  theme?: 'dark' | 'light'
  // Set the position of the trigger button
  // Defaults to `bottom-left`
  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
  // Custom nonce to allowlist jotai-devtools specific inline styles via CSP
  nonce?: string
  options?: {
    // Private atoms are used internally in atom creators like `atomWithStorage`
    // or `atomWithLocation`, etc. to manage the internal state.
    // Defaults to `false`
    shouldShowPrivateAtoms?: boolean
    // Expands the JSON tree view on initial render on Atom Viewer tab, Timeline tab, etc.
    // Defaults to `false`
    shouldExpandJsonTreeViewInitially?: boolean
    // The interval (in milliseconds) between each step of the time travel playback.
    // Defaults to `750ms`
    timeTravelPlaybackInterval?: number
    // The maximum number of snapshots to keep in the history.
    // The higher the number the more memory it will consume.
    // Defaults to `Infinity`. Recommended: `~30`
    snapshotHistoryLimit?: number
  }
}

import { DevTools } from 'jotai-devtools'
import 'jotai-devtools/styles.css'

const App = () => {
  return (
    <>
      <DevTools />
      {/* your app */}
    </>
  )
}

import { createStore } from 'jotai'
import { DevTools } from 'jotai-devtools'
import 'jotai-devtools/styles.css'

const customStore = createStore()

const App = () => {
  return (
    <Provider store={customStore}>
      <DevTools store={customStore} />
      {/* your app */}
    </Provider>
  )
}

function useAtomsDebugValue(options?: {
  store?: Store
  enabled?: boolean
}): void

import { useAtomsDebugValue } from 'jotai-devtools/utils'

const textAtom = atom('hello')
textAtom.debugLabel = 'textAtom'

const lenAtom = atom((get) => get(textAtom).length)
lenAtom.debugLabel = 'lenAtom'

const TextBox = () => {
  const [text, setText] = useAtom(textAtom)
  const [len] = useAtom(lenAtom)
  return (
    <span>
      <input value={text} onChange={(e) => setText(e.target.value)} />({len})
    </span>
  )
}

const DebugAtoms = () => {
  useAtomsDebugValue()
  return null
}

const App = () => (
  <Provider>
    <DebugAtoms />
    <TextBox />
  </Provider>
)

function useAtomDevtools<Value>(
  anAtom: WritableAtom<Value, Value>,
  options?: {
    store?: Store
    name?: string
    enabled?: boolean
  },
): void

import { useAtomDevtools } from 'jotai-devtools/utils'

// The interface for the type stored in the atom.
export interface Task {
  label: string
  complete: boolean
}

// The atom to debug.
export const tasksAtom = atom<Task[]>([])

// If the useAtomDevtools name parameter is undefined, this value will be used instead.
tasksAtom.debugLabel = 'Tasks'

export const useTasksDevtools = () => {
  // The hook can be called simply by passing an atom for debugging.
  useAtomDevtools(tasksAtom)

  // Specify a custom type parameter
  useAtomDevtools<Task[]>(tasksAtom)

  // You can attach two devtools instances to the same atom and differentiate them with custom names.
  useAtomDevtools(tasksAtom, 'Tasks (Instance 1)')
  useAtomDevtools(tasksAtom, 'Tasks (Instance 2)')
}

function useAtomsDevtools(
  name: string,
  options?: {
    store?: Store
    enabled?: boolean
  },
): void

const countAtom = atom(0);
const doubleCountAtom = atom((get) => get(countAtom) * 2);

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

  ...
}

const AtomsDevtools = ({ children }) => {
  useAtomsDevtools('demo')
  return children
}

export default function App()  {
  return (
    <AtomsDevtools>
      <Counter />
    </AtomsDevtools>
  )
 }

function useAtomsSnapshot(options?: { store?: Store }): AtomsSnapshot

import { Provider } from 'jotai'
import { useAtomsSnapshot } from 'jotai-devtools/utils'

const RegisteredAtoms = () => {
  const atoms = useAtomsSnapshot()

  return (
    <div>
      <p>Atom count: {atoms.size}</p>
      <div>
        {Array.from(atoms).map(([atom, atomValue]) => (
          <p key={`${atom}`}>{`${atom.debugLabel}: ${atomValue}`}</p>
        ))}
      </div>
    </div>
  )
}

const App = () => (
  <Provider>
    <RegisteredAtoms />
  </Provider>
)

function useGotoAtomsSnapshot(options?: {
  store?: Store
}): (values: Iterable<readonly [AnyAtom, unknown]>) => void

import { Provider } from 'jotai'
import { useAtomsSnapshot, useGotoAtomsSnapshot } from 'jotai-devtools/utils'

const petAtom = atom('cat')
const colorAtom = atom('blue')

const UpdateSnapshot = () => {
  const snapshot = useAtomsSnapshot()
  const goToSnapshot = useGotoAtomsSnapshot()
  return (
    <button
      onClick={() => {
        const newSnapshot = new Map(snapshot)
        newSnapshot.set(petAtom, 'dog')
        newSnapshot.set(colorAtom, 'green')
        goToSnapshot(newSnapshot)
      }}
    >
      Go to snapshot
    </button>
  )
}

npm install --save-dev jotai-rolldown

import jotai from 'jotai-rolldown'
import { defineConfig } from 'rolldown'

export default defineConfig({
  plugins: [jotai()],
})

import jotai from 'jotai-rolldown'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [jotai()],
})

export const countAtom = atom(0)

export const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'

// countAtom.ts
export default atom(0)

// countAtom.ts
const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'
export default countAtom

npx skills add jotaijs/jotai-skills --skill jotai

npx skills add jotaijs/jotai-skills --skill jotai --agent codex
npx skills add jotaijs/jotai-skills --skill jotai --agent claude-code

npx skills add jotaijs/jotai-skills --skill jotai --global

Review the form atom design.

Refactor React Context state into atoms.

Reduce unrelated atom rerenders.

npm install --save-dev @swc-jotai/react-refresh

{
  "jsc": {
    "experimental": {
      "plugins": [["@swc-jotai/react-refresh", {}]]
    }
  }
}

module.exports = {
  experimental: {
    swcPlugins: [['@swc-jotai/react-refresh', {}]],
  },
}

export const countAtom = atom(0)

export const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'

// countAtom.ts
export default atom(0)

// countAtom.ts
const countAtom = atom(0)
countAtom.debugLabel = 'countAtom'
export default countAtom

npm install --save-dev @swc-jotai/debug-label

{
  "jsc": {
    "experimental": {
      "plugins": [["@swc-jotai/debug-label", {}]]
    }
  }
}

module.exports = {
  experimental: {
    swcPlugins: [['@swc-jotai/debug-label', {}]],
  },
}

module.exports = {
  experimental: {
    swcPlugins: [
      ['@swc-jotai/debug-label', { atomNames: ['customAtom'] }],
      ['@swc-jotai/react-refresh', { atomNames: ['customAtom'] }],
    ],
  },
}

{
	state: 'loading' | 'hasData' | 'hasError',
	data?: any,
	error?: any,
}

import { loadable } from "jotai/utils"

const asyncAtom = atom(async (get) => ...)
const loadableAtom = loadable(asyncAtom)
// Does not need to be wrapped by a <Suspense> element
const Component = () => {
  const [value] = useAtom(loadableAtom)
  if (value.state === 'hasError') return <Text>{value.error}</Text>
  if (value.state === 'loading') {
    return <Text>Loading...</Text>
  }
  console.log(value.data) // Results of the Promise
  return <Text>Value: {value.data}</Text>
}

import { useAtom } from 'jotai'
import { atomWithObservable } from 'jotai/utils'
import { interval } from 'rxjs'
import { map } from 'rxjs/operators'

const counterSubject = interval(1000).pipe(map((i) => `#${i}`))
const counterAtom = atomWithObservable(() => counterSubject)

const Counter = () => {
  const [counter] = useAtom(counterAtom)
  return <div>count: {counter}</div>
}

const counterAtom = atomWithObservable(() => counterSubject, {
  initialValue: 10,
})

const counterAtom2 = atomWithObservable(() => counterSubject, {
  initialValue: () => Math.random(),
})

function unwrap<Value, Args extends unknown[], Result>(
  anAtom: WritableAtom<Value, Args, Result>,
): WritableAtom<Awaited<Value> | undefined, Args, Result>

function unwrap<Value, Args extends unknown[], Result, PendingValue>(
  anAtom: WritableAtom<Value, Args, Result>,
  fallback: (prev?: Awaited<Value>) => PendingValue,
): WritableAtom<Awaited<Value> | PendingValue, Args, Result>

function unwrap<Value>(anAtom: Atom<Value>): Atom<Awaited<Value> | undefined>

function unwrap<Value, PendingValue>(
  anAtom: Atom<Value>,
  fallback: (prev?: Awaited<Value>) => PendingValue,
): Atom<Awaited<Value> | PendingValue>

import { atom } from 'jotai'
import { unwrap } from 'jotai/utils'

const countAtom = atom(0)
const delayedCountAtom = atom(async (get) => {
  await new Promise((r) => setTimeout(r, 500))
  return get(countAtom)
})

const unwrapped1Atom = unwrap(delayedCountAtom)
// The value is `undefined` while pending

const unwrapped2Atom = unwrap(delayedCountAtom, (prev) => prev ?? 0)
// The value is `0` initially, and subsequent updates keep the previous value.

useAtomCallback<Result, Args extends unknown[]>(
  callback: (get: Getter, set: Setter, ...arg: Args) => Result,
  options?: Options
): (...args: Args) => Result

import { useEffect, useState, useCallback } from 'react'
import { Provider, atom, useAtom } from 'jotai'
import { useAtomCallback } from 'jotai/utils'

const countAtom = atom(0)

const Counter = () => {
  const [count, setCount] = useAtom(countAtom)
  return (
    <>
      {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </>
  )
}

const Monitor = () => {
  const [count, setCount] = useState(0)
  const readCount = useAtomCallback(
    useCallback((get) => {
      const currCount = get(countAtom)
      setCount(currCount)
      return currCount
    }, []),
  )
  useEffect(() => {
    const timer = setInterval(async () => {
      console.log(readCount())
    }, 1000)
    return () => {
      clearInterval(timer)
    }
  }, [readCount])
  return <div>current count: {count}</div>
}

npm install jotai-family

// Before
import { atomFamily } from 'jotai/utils'

// After
import { atomFamily } from 'jotai-family'

atomFamily(initializeAtom, areEqual): (param) => Atom

import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'
import deepEqual from 'fast-deep-equal'

const fooFamily = atomFamily((param) => atom(param), deepEqual)

import type { PrimitiveAtom } from 'jotai'

/**
 * here the atom(id) returns a PrimitiveAtom<number>
 * and PrimitiveAtom<number> is a WritableAtom<number, SetStateAction<number>>
 */
const myFamily = atomFamily((id: number) => atom(id))

atomFamily<Param, AtomType extends Atom<unknown>>(
  initializeAtom: (param: Param) => AtomType,
  areEqual?: (a: Param, b: Param) => boolean
): AtomFamily<Param, AtomType>

import { atom } from 'jotai'
import type { PrimitiveAtom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const myFamily = atomFamily<number, PrimitiveAtom<number>>((id: number) =>
  atom(id),
)

const todoFamily = atomFamily((name) => atom(name))

todoFamily('foo')
todoFamily('bar')

for (const param of todoFamily.getParams()) {
  console.log(param) // 'foo', 'bar'
}

todoFamily.remove('foo')

// Remove atoms older than 1 hour
todoFamily.setShouldRemove((createdAt, param) => {
  return Date.now() - createdAt > 60 * 60 * 1000
})

const cleanup = todoFamily.unstable_listen((event) => {
  console.log(event.type) // 'CREATE' or 'REMOVE'
  console.log(event.param) // the param
  console.log(event.atom) // the atom
})

// Later, stop listening
cleanup()

import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily((name) => atom(name))

todoFamily('foo')
// this will create a new atom('foo'), or return the one if already created

import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily((name) =>
  atom(
    (get) => get(todosAtom)[name],
    (get, set, arg) => {
      const prev = get(todosAtom)
      set(todosAtom, { ...prev, [name]: { ...prev[name], ...arg } })
    },
  ),
)

import { atom } from 'jotai'
import { atomFamily } from 'jotai/utils'

const todoFamily = atomFamily(
  ({ id, name }) => atom({ name }),
  (a, b) => a.id === b.id,
)

const imageDataAtom = atom(initializeExpensiveImage()) // 1) has to be computed here

function Home() {
  ...
}

function ImageEditor() {
  // 2) used only in this route
  const [imageData, setImageData] = useAtom(imageDataAtom);
  ...
}

function App() {
  return (
    <Router>
      <Route path="/" component={Home} />
      <Route path="/edit" component={ImageEditor} />
    </Router>
  )
}

import { atomWithLazy } from 'jotai/utils'

// passing the initialization function
const imageDataAtom = atomWithLazy(initializeExpensiveImage)

function Home() {
  ...
}

function ImageEditor() {
  // only gets initialized if user goes to `/edit`.
  const [imageData, setImageData] = useAtom(imageDataAtom);
  ...
}

function App() {
  return (
    <Router>
      <Route path="/" component={Home} />
      <Route path="/edit" component={ImageEditor} />
    </Router>
  )
}

type RGB = [number, number, number];

function randomRGB(): RGB {
  ...
}

const lift = (value: number) => ([r, g, b]: RGB) => {
  return [r + value, g + value, b + value]
}

const colorAtom = lazyAtom(randomRGB)

let store = createStore()

console.log(store.get(colorAtom)) // [0, 36, 128]
store.set(colorAtom, lift(8))
console.log(store.get(colorAtom)) // [8, 44, 136]

// recreating store, sometimes done when logging out or resetting the app in some way
store = createStore()

console.log(store.get(colorAtom)) // [255, 12, 46] -- a new random color

import { atomWithReducer } from 'jotai/utils'

const countReducer = (prev, action) => {
  if (action.type === 'inc') return prev + 1
  if (action.type === 'dec') return prev - 1
  throw new Error('unknown action type')
}

const countReducerAtom = atomWithReducer(0, countReducer)

function atomWithReset<Value>(
  initialValue: Value,
): WritableAtom<Value, SetStateAction<Value> | typeof RESET>

import { atomWithReset } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const todoListAtom = atomWithReset([
  { description: 'Add a todo', checked: false },
])

const RESET: unique symbol

import { atom, useSetAtom } from 'jotai'
import { atomWithReset, useResetAtom, RESET } from 'jotai/utils'

const dollarsAtom = atomWithReset(0)
const centsAtom = atom(
  (get) => get(dollarsAtom) * 100,
  (get, set, newValue: number | typeof RESET) =>
    set(dollarsAtom, newValue === RESET ? newValue : newValue / 100)
)

const ResetExample = () => {
  const setDollars = useSetAtom(dollarsAtom)
  const resetCents = useResetAtom(centsAtom)

  return (
    <>
      <button onClick={() => setDollars(RESET)}>Reset dollars</button>
      <button onClick={resetCents}>Reset cents</button>
    </>
  )
}

function useResetAtom<Value>(
  anAtom: WritableAtom<Value, typeof RESET>,
): () => void | Promise<void>

import { useResetAtom } from 'jotai/utils'
import { todoListAtom } from './store'

const TodoResetButton = () => {
  const resetTodoList = useResetAtom(todoListAtom)
  return <button onClick={resetTodoList}>Reset</button>
}

import { atomWithDefault } from 'jotai/utils'

const count1Atom = atom(1)
const count2Atom = atomWithDefault((get) => get(count1Atom) * 2)

import { useAtom } from 'jotai'
import { atomWithDefault, useResetAtom, RESET } from 'jotai/utils'

const count1Atom = atom(1)
const count2Atom = atomWithDefault((get) => get(count1Atom) * 2)

const Counter = () => {
  const [count1, setCount1] = useAtom(count1Atom)
  const [count2, setCount2] = useAtom(count2Atom)
  const resetCount2 = useResetAtom(count2Atom)

  return (
    <>
      <div>
        count1: {count1}, count2: {count2}
      </div>
      <button onClick={() => setCount1((c) => c + 1)}>increment count1</button>
      <button onClick={() => setCount2((c) => c + 1)}>increment count2</button>
      <button onClick={() => resetCount2()}>Reset with useResetAtom</button>
      <button onClick={() => setCount2(RESET)}>Reset with RESET const</button>
    </>
  )
}

function atomWithRefresh<Value>(
  read: Read<Value, [], void>,
): WritableAtom<Value, [], void>

function atomWithRefresh<Value, Args extends unknown[], Result>(
  read: Read<Value, Args, Result>,
  write: Write<Value, Args, Result>,
): WritableAtom<Value, Args | [], Result | void>

import { atomWithRefresh } from 'jotai/utils'

const postsAtom = atomWithRefresh((get) =>
  fetch('https://jsonplaceholder.typicode.com/posts').then((r) => r.json()),
)

const PostsList = () => {
  const [posts, refreshPosts] = useAtom(postsAtom)

  return (
    <div>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>

      {/* Clicking this button will re-fetch the posts */}
      <button type="button" onClick={() => refreshPosts()}>
        Refresh posts
      </button>
    </div>
  )
}

function selectAtom<Value, Slice>(
  anAtom: Atom<Value>,
  selector: (v: Value, prevSlice?: Slice) => Slice,
  equalityFn: (a: Slice, b: Slice) => boolean = Object.is,
): Atom<Slice>

const defaultPerson = {
  name: {
    first: 'Jane',
    last: 'Doe',
  },
  birth: {
    year: 2000,
    month: 'Jan',
    day: 1,
    time: {
      hour: 1,
      minute: 1,
    },
  },
}

// Original atom.
const personAtom = atom(defaultPerson)

// Tracks person.name. Updated when person.name object changes, even
// if neither name.first nor name.last actually change.
const nameAtom = selectAtom(personAtom, (person) => person.name)

// Tracks person.birth. Updated when year, month, day, hour, or minute changes.
// Use of deepEquals means that this atom doesn't update if birth field is
// replaced with a new object containing the same data. E.g., if person is re-read
// from a database.
const birthAtom = selectAtom(personAtom, (person) => person.birth, deepEquals)

const [value] = useAtom(selectAtom(atom(0), (val) => val)) // So this will cause an infinite loop

const baseAtom = atom(0) // Stable
const baseSelector = (v) => v // Stable
const Component = () => {
  // Solution 1: Memoize the whole resulting atom with "useMemo"
  const [value] = useAtom(useMemo(() => selectAtom(baseAtom, (v) => v), []))

  // Solution 2: Memoize the inline callback with "useCallback"
  const [value] = useAtom(
    selectAtom(
      baseAtom,
      useCallback((v) => v, []),
    ),
  )

  // Solution 3: All constraints are already satisfied
  const [value] = useAtom(selectAtom(baseAtom, baseSelector))
}

type SplitAtom = <Item, Key>(
  arrayAtom: PrimitiveAtom<Array<Item>>,
  keyExtractor?: (item: Item) => Key
): Atom<Array<PrimitiveAtom<Item>>>

export function splitAtom<Item, Key>(
  arrAtom: WritableAtom<Item[], [Item[]], void> | Atom<Item[]>,
  keyExtractor?: (item: Item) => Key,
)

import { Provider, atom, useAtom, PrimitiveAtom } from 'jotai'
import { splitAtom } from 'jotai/utils'
import './styles.css'

const initialState = [
  {
    task: 'help the town',
    done: false,
  },
  {
    task: 'feed the dragon',
    done: false,
  },
]

const todosAtom = atom(initialState)
const todoAtomsAtom = splitAtom(todosAtom)

type TodoType = (typeof initialState)[number]

const TodoItem = ({
  todoAtom,
  remove,
}: {
  todoAtom: PrimitiveAtom<TodoType>
  remove: () => void
}) => {
  const [todo, setTodo] = useAtom(todoAtom)
  return (
    <div>
      <input
        value={todo.task}
        onChange={(e) => {
          setTodo((oldValue) => ({ ...oldValue, task: e.target.value }))
        }}
      />
      <input
        type="checkbox"
        checked={todo.done}
        onChange={() => {
          setTodo((oldValue) => ({ ...oldValue, done: !oldValue.done }))
        }}
      />
      <button onClick={remove}>remove</button>
    </div>
  )
}

const TodoList = () => {
  const [todoAtoms, dispatch] = useAtom(todoAtomsAtom)
  return (
    <ul>
      {todoAtoms.map((todoAtom) => (
        <TodoItem
          todoAtom={todoAtom}
          remove={() => dispatch({ type: 'remove', atom: todoAtom })}
        />
      ))}
    </ul>
  )
}

const App = () => (
  <Provider>
    <TodoList />
  </Provider>
)

export default App

import { atom, useAtom } from 'jotai'
import { useHydrateAtoms } from 'jotai/utils'

const countAtom = atom(0)
const CounterPage = ({ countFromServer }) => {
  useHydrateAtoms([[countAtom, countFromServer]])
  const [count] = useAtom(countAtom)
  // count would be the value of `countFromServer`, not 0.
}

// Definition
function useHydrateAtoms(
  values: Iterable<readonly [Atom<unknown>, unknown]>,
  options?: { store?: Store },
): void

// Usage with an array, specifying a store
useHydrateAtoms(
  [
    [countAtom, 42],
    [frameworkAtom, 'Next.js'],
  ],
  { store: myStore },
)
// Or with a map
useHydrateAtoms(new Map([[count, 42]]))

useHydrateAtoms(
  [
    [countAtom, 42],
    [frameworkAtom, 'Next.js'],
  ],
  {
    dangerouslyForceHydrate: true,
  },
)

useHydrateAtoms([
  [countAtom, 42],
  [frameworkAtom, 'Next.js'],
])
useHydrateAtoms(
  [
    [countAtom, 17],
    [frameworkAtom, 'Gatsby'],
  ],
  { store: myStore },
)

useHydrateAtoms([
  [countAtom, 42],
  [frameworkAtom, 'Next.js'],
] as const)

import { useAtom } from 'jotai'
import { atomWithStorage } from 'jotai/utils'

const darkModeAtom = atomWithStorage('darkMode', false)

const Page = () => {
  const [darkMode, setDarkMode] = useAtom(darkModeAtom)

  return (
    <>
      <h1>Welcome to {darkMode ? 'dark' : 'light'} mode!</h1>
      <button onClick={() => setDarkMode(!darkMode)}>toggle theme</button>
    </>
  )
}

const storage = createJSONStorage(
  // getStringStorage
  () => window.localStorage, // or window.sessionStorage, asyncStorage or alike
  // options (optional)
  {
    reviver, // optional reviver option for JSON.parse
    replacer, // optional replacer option for JSON.stringify
  },
)

import { atomWithStorage, createJSONStorage } from 'jotai/utils'

const storage = createJSONStorage(() =>
  typeof window !== 'undefined' ? window.sessionStorage : undefined,
)

const someAtom = atomWithStorage('some-key', someInitialValue, storage)

import { useAtom } from 'jotai'
import { atomWithStorage, RESET } from 'jotai/utils'

const textAtom = atomWithStorage('text', 'hello')

const TextBox = () => {
  const [text, setText] = useAtom(textAtom)

  return (
    <>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => setText(RESET)}>Reset (to 'hello')</button>
    </>
  )
}

import { useAtom } from 'jotai'
import { atomWithStorage, RESET } from 'jotai/utils'

const isVisibleAtom = atomWithStorage('visible', false)

const TextBox = () => {
  const [isVisible, setIsVisible] = useAtom(isVisibleAtom)

  return (
    <>
      {isVisible && <h1>Header is visible!</h1>}
      <button onClick={() => setIsVisible((prev) => (prev ? RESET : true))}>
        Toggle visible
      </button>
    </>
  )
}

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)

// 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 <div>{symbol}</div>
}

// 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 <div>{symbol}</div>
}

// Console output WITH getOnInit:
// LOG "symbol" BTC_USDC  (gets stored value immediately)

const countAtom = atomWithStorage('count-key', 0, anyAsyncStorage)
const Component = () => {
  const [count, setCount] = useAtom(countAtom)
  const increment = () => {
    setCount(async (promiseOrValue) => (await promiseOrValue) + 1)
  }
  // ...
}

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

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