# Large Objects

> All of the examples and descriptions below are based on this [codesandbox](https://codesandbox.io/s/zealous-sun-f2qnl?file=/src/App.tsx), so it will give you a better understanding if you check it out along these examples.

Sometimes we have big data we need to keep into atoms, we may need to change that data in some levels, or we need to use part of that data, but we can't listen to all these changes or use all that data for just a specific part.

consider this example.

```jsx
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'],
  },
}
```

## `focusAtom`

> `focusAtom` creates a new atom, based on the focus that you pass to it. [jotai/optics](../api/optics.md#focusatom)

We use this utility to focus an atom and create an atom of a specific part of the data. For example we may need to consume the people property of the above data, Here's how we do it.

```jsx
import { atom } from 'jotai'
import { focusAtom } from 'jotai/optics'

const dataAtom = atom(initialData)

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

`focusAtom` returns `WritableAtom` which means it's possible to change the `peopleAtom` data.

If we change the `film` property of the above data example, the `peopleAtom` won't cause us a re-render, so that's one of the points of using `focusAtom`.

## `splitAtom`

> The `splitAtom` utility is useful, when you want to get an atom for each element in a list. [jotai/utils](../api/utils.md#splitatom)

We use this utility for atoms that return arrays as their values, for example the `peopleAtom` we made above returns the people property array, so we can return an atom for each item of that array. If the array atom is writable, `splitAtom` returned atoms are going to be writable, if the array atom is read-only, items atoms are going to be read-only too.

```jsx
import { splitAtom } from 'jotai/utils'

const peopleAtomsAtom = splitAtom(peopleAtom)
```

And that's how we use it in components.

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

## `selectAtom`

> This function creates a derived atom whose value is a function of the original atom's value. [jotai/utils](../api/utils.md#selectatom)

This utility is similar to `focusAtom`, but we use it when we have a read-only atom to select part of it, and it always returns a read-only atom.

Assume we want to consume the info data, and its data is always unchangeable, so we can make a read-only atom from it and select that created atom.

```jsx
// first we create a read-only atom based on initialData.info
const readOnlyInfoAtom = atom((get) => get(dataAtom).info)
```

Then we can going to consume it in our component:

```jsx
import { atom, useAtom } from 'jotai'
import { selectAtom, splitAtom } from 'jotai/utils'

const Tags: React.FC = () => {
  const tagsAtom = selectAtom(readOnlyInfoAtom, (s) => s.tags)
  const tagsAtomsAtom = splitAtom(tagsAtom)
  const [tagAtoms] = useAtom(tagsAtomsAtom)
  return (
    <div>
      {tagAtoms.map((tagAtom) => (
        <Tag key={`${tagAtom}`} tagAtom={tagAtom} />
      ))}
    </div>
  )
}
```


This doc describes core `jotai` bundle.

## atom

`atom` is a function to create an atom config. The atom config is an immutable object. The atom config itself doesn't hold an atom value. The atom value is stored in a Provider state.

```tsx
// primitive atom
function atom<Value>(initialValue: Value): PrimitiveAtom<Value>

// read-only atom
function atom<Value>(read: (get: Getter) => Value | Promise<Value>): Atom<Value>

// writable derived atom
function atom<Value, Update>(
  read: (get: Getter) => Value | Promise<Value>,
  write: (get: Getter, set: Setter, update: Update) => void | Promise<void>
): WritableAtom<Value, Update>

// write-only derived atom
function atom<Value, Update>(
  read: Value,
  write: (get: Getter, set: Setter, update: Update) => void | Promise<void>
): WritableAtom<Value, Update>
```

- `initialValue`: as the name says, it's an initial value which is the atom's going to return unless its value doesn't get changed.
- `read`: a function that's going to get called on every re-render. The signature of `read` is `(get) => Value | Promise<Value>`, and `get` is a function that takes an atom config and returns its value stored in Provider described below. Dependency is tracked, so if `get` is used for an atom at least once, the `read` will be reevaluated whenever the atom value is changed.
- `write`: a function mostly used for mutating atom's values, for a better description; it gets called whenever we call the second value of the returned pair of `useAtom`, the `useAtom()[1]`. The default value of this function in the primitive atom will change the value of that atom. The signature of `write` is `(get, set, update) => void | Promise<void>`. `get` is similar to the one described above, but it doesn't track the dependency. `set` is a function that takes an atom config and a new value which then updates the atom value in Provider. `update` is an arbitrary value that we receive from the updating function returned by `useAtom` described below.

```tsx
const primitiveAtom = atom(initialValue)
const derivedAtomWithRead = atom(read)
const derivedAtomWithReadWrite = atom(read, write)
const derivedAtomWithWriteOnly = atom(null, write)
```

There are two kinds of atoms: a writable atom and a read-only atom. Primitive atoms are always writable. Derived atoms are writable if the `write` is specified. The `write` of primitive atoms is equivalent to the `setState` of `React.useState`.

### debugLabel

The created atom config can have an optional property `debugLabel`. The debug label will be used to display the atom in debugging. See [Debugging guide](../guides/debugging.md) for more information.

Note: Technically, the debug labels don’t have to be unique. However, it’s generally recommended to make them distinguishable.

### onMount

The created atom config can have an optional property `onMount`. `onMount` is a function which takes a function `setAtom` and returns `onUnmount` function optionally.

The `onMount` function will be invoked when the atom is first used in a provider, and `onUnmount` will be invoked when it’s not used. In some edge cases, an atom can be unmounted and then mounted immediately.

```tsx
const anAtom = atom(1)
anAtom.onMount = (setAtom) => {
  console.log('atom is mounted in provider')
  setAtom(c => c + 1) // increment count on mount
  return () => { ... } // return optional onUnmount function
}
```

Invoking `setAtom` function will invoke the atom’s `write`. Customizing `write` allows changing the behavior.

```tsx
const countAtom = atom(1)
const derivedAtom = atom(
  (get) => get(countAtom),
  (get, set, action) => {
    if (action.type === 'init') {
      set(countAtom, 10)
    } else if (action.type === 'inc') {
      set(countAtom, (c) => c + 1)
    }
  }
)
derivedAtom.onMount = (setAtom) => {
  setAtom({ type: 'init' })
}
```

## Provider

```ts
const Provider: React.FC<{
  initialValues?: Iterable<readonly [AnyAtom, unknown]>
  scope?: Scope
}>
```

Atom configs don't hold values. Atom values reside in separate stores. A Provider is a component that contains a store and provides atom values under the component tree. A Provider works just like React context provider. If you don't use a Provider, it works as provider-less mode with a default store. A Provider will be necessary if we need to hold different atom values for different component trees. Provider also has some capabilities described below, which doesn't exist in the provider-less mode.

```jsx
const Root = () => (
  <Provider>
    <App />
  </Provider>
)
```

### `initialValues` prop

A Provider accepts an optional prop `initialValues` which you can specify
some initial atom values.
The use cases of this are testing and server side rendering.

#### Example

```jsx
const TestRoot = () => (
  <Provider initialValues=[[atom1, 1], [atom2, 'b']]>
    <Component />
  </Provider>
)
```

#### TypeScript

The `initialValues` prop is not type friendly.
We can mitigate it by using a helper function.

```ts
const createInitialValues = () => {
  const initialValues: (readonly [Atom<unknown>, unknonw])[] = []
  const get = () => initialValues
  const set = <Value>(anAtom: Atom<Value>, value: Value) => {
    initialValues.push([anAtom, value])
  }
  return { get, set }
}
```

### `scope` prop

A Provider accepts an optional prop `scope` which you can use for scoped atoms.
It works only for atoms with the same scope.
The recommendation for the scope value is a unique symbol.
The use case of scope is for library usage.

#### Example

```jsx
const myScope = Symbol()

const anAtom = atom('')
anAtom.scope = myScope

const LibraryRoot = () => (
  <Provider scope={myScope}>
    <Component />
  </Provider>
)
```

## useAtom

```ts
// primitive or writable derived atom
function useAtom<Value, Update>(
  atom: WritableAtom<Value, Update>
): [Value, SetAtom<Update>]

// read-only atom
function useAtom<Value>(atom: Atom<Value>): [Value, never]
```

The useAtom hook is to read an atom value stored in the Provider. It returns the atom value and an updating function as a tuple, just like useState. It takes an atom config created with `atom()`. Initially, there is no value stored in the Provider. The first time the atom is used via `useAtom`, it will add an initial value in the Provider. If the atom is a derived atom, the read function is executed to compute an initial value. When an atom is no longer used, meaning all the components using it is unmounted, and the atom config no longer exists, the value is removed from the Provider.

```js
const [value, updateValue] = useAtom(anAtom)
```

The `updateValue` takes just one argument, which will be passed to the third argument of writeFunction of the atom. The behavior totally depends on how the writeFunction is implemented.

---

## Notes

### How atom dependency works

To begin with, let's explain this. In the current implementation, every time we invoke the "read" function, we refresh the dependencies and dependents. For example, If A depends on B, it means that B has a dependency on A, and A is a dependent of B.

```js
const uppercaseAtom = atom((get) => get(textAtom).toUpperCase())
```

The read function is the first parameter of the atom.
The dependency will initially be empty. On first use, we run the read function and know that `uppercaseAtom` depends on `textAtom`. `textAtom` has a dependency on `uppercaseAtom`. So, add `uppercaseAtom` to the dependents of `textAtom`.
When we re-run the read function (because its dependency (=textAtom) is updated),
the dependency is built again, which is the same in this case. We then remove stale dependents and replace with the latest one.

### Atoms can be created on demand

Basic examples in readme only show defining atoms globally outside components.
There is no restrictions about when we create an atom.
As long as we know atoms are identified by their object referential identity,
it's okay to create them at anytime.

If you create atoms in render functions, you would typically want to use
a hook like `useRef` or `useMemo` for memoization. If not, the atom would be created everytime the component renders.

You can create an atom and store it wth `useState` or even in another atom.
See an example in [issue #5](https://github.com/pmndrs/jotai/issues/5).

You can cache atoms somewhere globally.
See [this example](https://twitter.com/dai_shi/status/1317653548314718208) or
[that example](https://github.com/pmndrs/jotai/issues/119#issuecomment-706046321).

Check [`atomFamily`](../api/utils.md#atomfamily) in utils for parameterized atoms.

### Some more notes about atoms

- If you create a primitive atom, it will use predefined read/write functions to emulate `useState` behavior.
- If you create an atom with read/write functions, they can provide any behavior with some restrictions as follows.
- `read` function will be invoked during React render phase, so the function has to be pure. What is pure in React is described [here](https://gist.github.com/sebmarkbage/75f0838967cd003cd7f9ab938eb1958f).
- `write` function will be invoked where you called initially and in useEffect for following invocations. So, you shouldn't call `write` in render.
- When an atom is initially used with `useAtom`, it will invoke `read` function to get the initial value, this is recursive process. If an atom value exists in Provider, it will be used instead of invoking `read` function.
- Once an atom is used (and stored in Provider), it's value is only updated if its dependencies are updated (including updating directly with useAtom).


This doc describes `jotai/devtool` bundle.

## useAtomDevtools

`useAtomDevtools` is a React hook that manages ReduxDevTools integration for a particular atom.

```ts
function useAtomDevtools<Value>(
  anAtom: WritableAtom<Value, Value>,
  name?: string
): void
```

The `useAtomDevtools` hook accepts a generic type parameter (mirroring the type stored in the atom). Additionally, the hook accepts two invocation parameters, `anAtom` and `name`.
`anAtom` is the atom that will be attached to the devtools instance. `name` is an optional parameter that defines the debug label for the devtools instance. If `name` is undefined, `atom.debugLabel` will be used instead.

### Example

```typescript
import { useAtomDevtools } from 'jotai/devtools'

// 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)')
}
```


This doc describes `jotai/immer` bundle.

## Install

You have to install `immer` to access this bundle and its functions.

```
npm install immer
# or
yarn add immer
```

## atomWithImmer

`atomWithImmer` creates a new atom similar to the regular [`atom`](../api/core.md#atom) [atom] with a different `writeFunction`. In this bundle, we don't have read-only atoms, because the point of these functions is the immer produce(mutability) function.
The signature of writeFunction is `(get, set, update: (draft: Draft<Value>) => void) => void`.

```js
import { useAtom } from 'jotai'
import { atomWithImmer } from 'jotai/immer'

const countAtom = atomWithImmer(0)

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

const Controls = () => {
  const [, setCount] = useAtom(setCountAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

### Examples

Check examples with atomWithImmer:

- https://codesandbox.io/s/jotai-immer-example-8zrqs

## withImmer

`withImmer` takes an atom and returns a derived atom, same as `atomWithImmer` it has a different `writeFunction`.

```js
import { useAtom, atom } from 'jotai'
import { withImmer } from 'jotai/immer'

const primitiveAtom = atom(0)
const countAtom = withImmer(primitiveAtom)

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

const Controls = () => {
  const [, setCount] = useAtom(setCountAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

## useImmerAtom

This hook takes an atom and replaces the atom's `writeFunction` with the new immer-like `writeFunction` like the previous helpers.

```jsx
import { useAtom } from 'jotai'
import { useImmerAtom } from 'jotai/immer'

const primitiveAtom = atom(0)

const Counter = () => {
  const [count] = useImmerAtom(primitiveAtom)
  return <div>count: {count}</div>
}

const Controls = () => {
  const [, setCount] = useImmerAtom(primitiveAtom)
  // setCount === update : (draft: Draft<Value>) => void
  const inc = () => setCount((c) => (c = c + 1))
  return <button onClick={inc}>+1</button>
}
```

It would be better if you don't use `withImmer` and `atomWithImmer` with `useImmerAtom` because they provide the immer-like `writeFunction` and we don't need to create a new one.

## Codesandbox

A good example of this bundle in [codesandbox](https://codesandbox.io/s/immer-jotai-doc-ms9pv?file=/src/App.tsx).


This doc describes `jotai/optics` bundle.

## Install

You have to install `optics-ts` to access this bundle and its functions.

```
npm install optics-ts
# or
yarn add optics-ts
```

## focusAtom

`focusAtom` creates a new atom, based on the focus that you pass to it. This creates a derived atom that will focus on the specified part of the atom,
and when the derived atom is updated, the derivee is notified of the update, and the equivalent update is done on the derivee.

See this:

```typescript
const baseAtom = atom({ a: 5 }) // PrimitiveAtom<{a: number}>
const derivedAtom = focusAtom(baseAtom, (optic) => optic.prop('a')) // PrimitiveAtom<number>
```

So basically, we started with a `PrimitiveAtom<{a: number}>`, which has a getter and a setter, and then used `focusAtom` to zoom in on the `a`-property of
the `baseAtom`, and got a `PrimitiveAtom<number>`. What is noteworthy here is that this `derivedAtom` is not only a getter, it is also a setter. If `derivedAtom` is updated, then
then equivalent update is done on the `baseAtom`.

The example below is simple, but it's a starting point. `focusAtom` supports many kinds of optics, including `Lens`, `Prism`, `Isomorphism`.

To see more advanced optics, please see the example at: https://github.com/akheron/optics-ts

### Example

```jsx
import { atom } from 'jotai'
import { focusAtom } from 'jotai/optics'

const objectAtom = atom({ a: 5, b: 10 })
const aAtom = focusAtom(objectAtom, (optic) => optic.prop('a'))
const bAtom = focusAtom(objectAtom, (optic) => optic.prop('b'))

const Controls = () => {
  const [a, setA] = useAtom(aAtom)
  const [b, setB] = useAtom(aAtom)
  return (
    <div>
      <span>Value of a: {a}</span>
      <span>Value of b: {b}</span>
      <button onClick={() => setA((oldA) => oldA + 1)}>Increment a</button>
      <button onClick={() => setA((oldB) => oldB + 1)}>Increment b</button>
    </div>
  )
}
```


This doc describes `jotai/query` bundle.

## Install

You have to install `react-query` to access this bundle and its functions.

```
yarn add react-query
```

## atomWithQuery

`atomWithQuery` creates a new atom with React Query. This function helps you use both atoms features and `useQuery` features in a single atom.

```js
import { useAtom } from 'jotai'
import { atomWithQuery } from 'jotai/query'

const idAtom = atom(1)
const userAtom = atomWithQuery((get) => ({
  queryKey: ['users', get(idAtom)],
  queryFn: async ({ queryKey: [, id] }) => {
    const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
    return res.json()
  },
}))

const UserData = () => {
  const [data] = useAtom(userAtom)
  return <div>{JSON.stringify(data)}</div>
}
```

### Examples

Basic demo: [codesandbox](https://codesandbox.io/s/jotai-query-demo-ij2sd)

Hackernews: [codesandbox](https://codesandbox.io/s/jotai-query-hacker-news-u4sli)


This doc describes `jotai/redux` bundle.

Jotai's state resides in React, but sometimes it would be nice
to intract with the world outside React.
Redux provides a store interface that can be used to store some values
and sync with atoms in jotai.

## Install

You have to install `redux` to access this bundle and its functions.

```
npm install redux
# or
yarn add redux
```

## atomWithStore

`atomWithStore` creates a new atom with redux store.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithStore } from 'jotai/redux'
import { createStore } from 'redux'

const initialState = { count: 0 }
const reducer = (state = initialState, action: { type: 'INC' }) => {
  if (action.type === 'INC') {
    return { ...state, count: state.count + 1 }
  }
  return state
}
const store = createStore(reducer)
const storeAtom = atomWithStore(store)

const Counter: React.FC = () => {
  const [state, dispatch] = useAtom(storeAtom)

  return (
    <>
      count: {state.count}
      <button onClick={() => dispatch({ type: 'INC' })}>button</button>
    </>
  )
}
```

### Examples

https://codesandbox.io/s/react-typescript-forked-cmlu5


This doc describes `jotai/utils` bundle.

## useUpdateAtom

Ref: https://github.com/pmndrs/jotai/issues/26

```jsx
import { atom, useAtom } from 'jotai'
import { useUpdateAtom } from 'jotai/utils'

const countAtom = atom(0)

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

const Controls = () => {
  const setCount = useUpdateAtom(countAtom)
  const inc = () => setCount((c) => c + 1)
  return <button onClick={inc}>+1</button>
}
```

https://codesandbox.io/s/react-typescript-forked-3q11k

## useAtomValue

Ref: https://github.com/pmndrs/jotai/issues/212

```jsx
import { atom, Provider, useAtom } from 'jotai'
import { useAtomValue } from 'jotai/utils'

const countAtom = atom(0)

const Counter = () => {
  const setCount = useUpdateAtom(countAtom)
  const count = useAtomValue(countAtom)
  return (
    <>
      <div>count: {count}</div>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </>
  )
}
```

https://codesandbox.io/s/react-typescript-forked-1x90m

## atomWithReset

Ref: https://github.com/pmndrs/jotai/issues/41

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

Creates an atom that could be reset to its `initialValue` with
[`useResetAtom`](./utils.md#useResetAtom) hook. It works exactly the same
way as primitive atom would, but you are also able to set it to a special value
[`RESET`](./utils.md#RESET). See examples in [Resettable atoms](../guides/resettable.md).

### Example

```js
import { atomWithReset } from 'jotai/utils'

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

## useResetAtom

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

Resets a [Resettable atom](../guides/resettable.md) to its initial value.

### Example

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

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

## RESET

Ref: https://github.com/pmndrs/jotai/issues/217

```ts
const RESET: unique symbol
```

Special value that is accepted by [Resettable atoms](../guides/resettable.md)
created with [`atomWithReset`](./utils.md#atomWithReset) or writable atom created
with `atom` if it accepts `RESET` symbol.

### Example

```jsx
import { atom } 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: React.FC = () => {
  const setDollars = useUpdateAtom(dollarsAtom)
  const resetCents = useResetAtom(centsAtom)

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

## useReducerAtom

```jsx
import { atom } from 'jotai'
import { useReducerAtom } 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 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>
  )
}
```

https://codesandbox.io/s/react-typescript-forked-eg0mw

## atomWithReducer

Ref: https://github.com/pmndrs/jotai/issues/38

```js
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)
```

https://codesandbox.io/s/react-typescript-forked-g3tsx

## atomWithDefault

Ref: https://github.com/pmndrs/jotai/issues/352

This is a function to create a primitive atom.
Its default value can be specified with a read function instead of a static initial value.

```js
import { atomWithDefault } from 'jotai/utils'

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

https://codesandbox.io/s/react-typescript-forked-unfro

## atomFamily

Ref: https://github.com/pmndrs/jotai/issues/23

### Usage

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

This will create a function that takes `param` and returns an atom.
If it's already created, it will return it from the cache.
`initializeAtom` is function that can return any kind of atom (`atom()`, `atomWithDefault()`, ...).
Note that `areEqual` is optional, which tell
if two params are equal (defaults to `Object.is`).

To reproduce the similar behavior to [Recoil's atomFamily/selectorFamily](https://recoiljs.org/docs/api-reference/utils/atomFamily),
specify a deepEqual function to `areEqual`. For example:

```js
import { atom } from 'jotai'
import deepEqual from 'fast-deep-equal'

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

### Examples

```js
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
```

```js
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)
      return { ...prev, [name]: { ...prev[name], ...arg } }
    }
  )
)
```

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

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

### Codesandbox

https://codesandbox.io/s/react-typescript-forked-8zfrn

## selectAtom

Ref: https://github.com/pmndrs/jotai/issues/36

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

This function creates a derived atom whose value is a function of the original atom's value,
determined by `selector.`
The selector function runs whenever the original atom changes; it updates the derived atom
only if `equalityFn` reports that the derived value has changed.
By default, `equalityFn` is reference equality, but you can supply your favorite deep-equals
function to stabilize the derived value where necessary.

### Examples

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

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

Ref: https://codesandbox.io/s/react-typescript-forked-8czek

## useAtomCallback

Ref: https://github.com/pmndrs/jotai/issues/60

### Usage

```js
useAtomCallback(
  callback: (get: Getter, set: Setter, arg: Arg) => Result
): (arg: Arg) => Promise<Result>
```

This hook allows to interact with atoms imperatively.
It takes a callback function that works like atom write function,
and returns a function that returns a promise.

The callback to pass in the hook must be stable (should be wrapped with useCallback).

### Examples

```jsx
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(await readCount())
    }, 1000)
    return () => {
      clearInterval(timer)
    }
  }, [readCount])
  return <div>current count: {count}</div>
}
```

### Codesandbox

https://codesandbox.io/s/react-typescript-forked-6ur43

## freezeAtom

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

const countAtom = freezeAtom(atom(0))
```

`freezeAtom` take an existing atom and return a new derived atom.
The returned atom is "frozen" which means when you use the atom
with `useAtom` in components or `get` in other atoms,
the atom value will be deeply freezed with Object.freeze.
It would be useful to find bugs where you accidentally tried
to mutate objects which can lead to unexpected behavior.

## atomFrozenInDev

```js
import { atomFrozenInDev as atom } from 'jotai/utils'

const countAtom = atom(0)
```

`atomFrozenInDev` is another function to create a frozen atom.
The atom is frozen only in the development mode.
In production, it works as the normal `atom`.

## splitAtom

The `splitAtom` utility is useful for when you want to get an atom for each element in a list.
It works for read/write atoms that contain a list. When used on such an atom, it returns an atom
which itself contains a list of atoms, each corresponding to the respective item in the original list.

A simplified type signature would be:

```ts
type SplitAtom = <Item>(arrayAtom: PrimitiveAtom<Array<Item>>): Atom<Array<PrimitiveAtom<Item>>>
```

Additionally, the atom returned by `splitAtom` contains a removal function in the `write` direction,
this is useful for when you want a simple way to remove each element in the original atom.

See the below example for usage.

### codesandbox

https://codesandbox.io/s/react-typescript-forked-7nir9?file=/src/App.tsx

```tsx
import * as React from 'react'
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)

const TodoList = () => {
  const [todoAtoms, removeTodoAtom] = useAtom(todoAtomsAtom)
  return (
    <ul>
      {todoAtoms.map((todoAtom) => (
        <TodoItem todoAtom={todoAtom} remove={() => removeTodoAtom(todoAtom)} />
      ))}
    </ul>
  )
}

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 App = () => (
  <Provider>
    <TodoList />
  </Provider>
)

export default App
```

## waitForAll

Sometimes you have multiple async atoms in your components:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const App = () => {
  const [dogs] = useAtom(dogsAtom)
  const [cats] = useAtom(catsAtom)
  // ...
}
```

However, this will start fetching one at the time, which is not optimal - It would be better if we can start fetching both as soon as possible.

The `waitForAll` utility is a concurrency helper, which allows us to evaluate multiple async atoms:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const App = () => {
  const [[dogs, cats]] = useAtom(waitForAll([dogsAtom, catsAtom]))
  // or ...
  const [dogs, cats] = useAtomValue(waitForAll([dogsAtom, catsAtom]))
  // ...
}
```

You can also use `waitForAll` inside an atom - It's also possible to name them for readability:

```tsx
const dogsAtom = atom(async (get) => {
  const response = await fetch('/dogs')
  return await response.json()
})
const catsAtom = atom(async (get) => {
  const response = await fetch('/cats')
  return await response.json()
})

const animalsAtom = atom((get) => {
  return get(
    waitForAll({
      dogs: dogsAtom,
      cats: catsAtom,
    })
  )
})

const App = () => {
  const [{ dogs, cats }] = useAtom(animalsAtom)
  // or ...
  const { dogs, cats } = useAtomValue(animalsAtom)
  // ...
}
```

### Codesandbox

https://codesandbox.io/s/react-typescript-forked-krwsv?file=/src/App.tsx


This doc describes `jotai/valtio` bundle.

Jotai's state resides in React, but sometimes it would be nice
to intract with the world outside React.
Valtio provides a proxy interface that can be used to store some values
and sync with atoms in jotai.
This only uses the vanilla api of valtio.

## Install

You have to install `valtio` to access this bundle and its functions.

```
npm install valtio
# or
yarn add valtio
```

## atomWithProxy

`atomWithProxy` creates a new atom with valtio proxy.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithProxy } from 'jotai/valtio'
import { proxy } from 'valtio/vanilla'

const proxyState = proxy({ count: 0 })
const stateAtom = atomWithProxy(proxyState)
const Counter: React.FC = () => {
  const [state, setState] = useAtom(stateAtom)

  return (
    <>
      count: {state.count}
      <button
        onClick={() =>
          setState((prev) => ({ ...prev, count: prev.count + 1 }))
        }>
        button
      </button>
    </>
  )
}
```

### Examples

https://codesandbox.io/s/react-typescript-forked-f5u4l


This doc describes `jotai/xstate` bundle.

Jotai's state management is privimite and flexible,
but that sometimes means too free.
XState is a sophisticated library to provide
a better and safer abstraction for state management.

## Install

You have to install `xstate` to access this bundle and its functions.

```
npm install xstate
# or
yarn add xstate
```

## atomWithMachine

`atomWithMachine` creates a new atom with XState machine.
It receives a function `getMachine` to create a new machine.
`getMachine` is invoked at the first use with `get` argument,
with which you can read other atom values.

```js
import { useAtom } from 'jotai'
import { atomWithMachine } from 'jotai/xstate'
import { assign, createMachine } from 'xstate'

const createEditableMachine = (value: string) =>
  createMachine <
  { value: string } >
  {
    id: 'editable',
    initial: 'reading',
    context: {
      value,
    },
    states: {
      reading: {
        on: {
          dblclick: 'editing',
        },
      },
      editing: {
        on: {
          cancel: 'reading',
          commit: {
            target: 'reading',
            actions: assign({
              value: (_, { value }) => value,
            }),
          },
        },
      },
    },
  }

const defaultTextAtom = atom('edit me')
const editableMachineAtom = atomWithMachine((get) =>
  // `get` is available only for initializing a machine
  createEditableMachine(get(defaultTextAtom))
)

const Toggle: React.FC = () => {
  const [state, send] = useAtom(editableMachineAtom)

  return (
    <div>
      {state.matches('reading') && (
        <strong onDoubleClick={send}>{state.context.value}</strong>
      )}
      {state.matches('editing') && (
        <input
          autoFocus
          defaultValue={state.context.value}
          onBlur={(e) => send({ type: 'commit', value: e.target.value })}
          onKeyDown={(e) => {
            if (e.key === 'Enter') {
              send({ type: 'commit', value: e.target.value })
            }
            if (e.key === 'Escape') {
              send('cancel')
            }
          }}
        />
      )}
      <br />
      <br />
      <div>
        Double-click to edit. Blur the input or press <code>enter</code> to
        commit. Press <code>esc</code> to cancel.
      </div>
    </div>
  )
}
```

### Examples

Check examples with atomWithMachine:

- https://codesandbox.io/s/react-typescript-forked-gxwnx


This doc describes `jotai/zustand` bundle.

Jotai's state resides in React, but sometimes it would be nice
to intract with the world outside React.
Zustand provides a store interface that can be used to hold some values
and sync with atoms in jotai.
This only uses the vanilla api of zustand.

## Install

You have to install `zustand` to access this bundle and its functions.

```
npm install zustand
# or
yarn add zustand
```

## atomWithStore

`atomWithStore` creates a new atom with zustand store.
It's two-way binding and you can change the value from both ends.

```js
import { useAtom } from 'jotai'
import { atomWithStore } from 'jotai/zustand'
import create from 'zustand/vanilla'

const store = create(() => ({ count: 0 }))
const stateAtom = atomWithStore(store)
const Counter: React.FC = () => {
  const [state, setState] = useAtom(stateAtom)

  return (
    <>
      count: {state.count}
      <button
        onClick={() =>
          setState((prev) => ({ ...prev, count: prev.count + 1 }))
        }>
        button
      </button>
    </>
  )
}
```

### Examples

https://codesandbox.io/s/react-typescript-forked-c6zi9


# Debugging

## Using React Dev Tools

You can use [React Dev Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
to inspect Jotai state. To achieve that [useDebugValue](https://reactjs.org/docs/hooks-reference.html#usedebugvalue)
is used inside custom hooks. Keep in mind that it only works in dev mode
(`NODE_ENV === 'development'`).

### Provider

If you select jotai `Provider` component in the React Dev Tools to see custom
hook "DebugState" which allows you to see all atom states,
which is a map of atom config and atom values & dependents.

By default each 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`.

```js
const countAtom = atom(0)
if (process.env.NODE_ENV !== 'production') {
  countAtom.debugLabel = 'count'
}
```

So it will show up as `1:count` instead.

### useAtom

`useAtom` calls `useDebugValue` for atom values, so if you select the component
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.

## Using Redux DevTools

You can use [Redux DevTools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
to inspect the state of a particular atom. Please refer to [`useAtomDevtools`](../api/devtools.md#useAtomDevtools) hook from `jotai/devtools` bundle.

## Frozen Atoms

To find bugs where you accidentally tried to mutate objects stored in atoms you
could use [`freezeAtom`](../api/utils.md#freezeAtom) or
[`atomFrozenInDev`](../api/utils.md#atomFrozenInDev) from `jotai/utils` bundle.
Which returns atoms value that is deeply freezed with `Object.freeze`.


# How to use jotai with next.js

### You can't return promises in server side rendering

```js
const postData = atom((get) => {
  const id = get(postId)
  if (isSSR || prefetchedPostData[id]) {
    return prefetchedPostData[id] || EMPTY_POST_DATA
  }
  return fetchData(id) // returns a promise
})
```

### Hydration is possible with care

Check the following examples.

## Examples

## Clock

https://codesandbox.io/s/nextjs-with-jotai-5ylrj

## HN Posts

https://codesandbox.io/s/nextjs-with-jotai-async-pm0l8


# No Suspense

> The content of this page would be easier if you have taken a look on the [introduction/async](../introduction/async.md) part of the docs.

Sometimes we need to wrap our components in suspense to use asynchronous atoms. Two kinds of atoms need Suspense.

- Derived async atoms (async `read` function)
- Asynchronous actions (async `write`)

But sometimes we're not allowed to wrap our components in Suspense, So we're going to do some hacks below and and make our async atoms synchronous.

## Async `read`

Check this derived async atom:

```tsx
const urlAtom = atom('https://json.host.com')
const fetchUrlAtom = atom(async (get) => {
  const response = await fetch(get(urlAtom))
  return await response.json()
})
```

It needs Suspense because the `read` function returns a promise(async function).

We shouldn't return a promise if we don't need it to suspend, so we have to change the structure slightly.

Here's the new code.

```tsx
const fetchResultAtom = atom({ loading: true, error: null, data: null })
const runFetchAtom = atom(
  (get) => get(fetchResultAtom),
  (_get, set, url) => {
    const fetchData = async () => {
      set(fetchResultAtom, (prev) => ({ ...prev, loading: true }))
      try {
        const response = await fetch(url)
        const data = await response.json()
        set(fetchResultAtom, { loading: false, error: null, data })
      } catch (error) {
        set(fetchResultAtom, { loading: false, error, data: null })
      }
    }
    fetchData()
  }
)
runFetchAtom.onMount = (runFetch) => {
  runFetch('https://json.host.com')
}

const Component = () => {
  const [result] = useAtom(runFetchAtom)

  console.log(result) // { loading: ..., error: ..., data: ... }
  return <div>...</div>
}
```

## Async `write`

The original code is:

```tsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  async (_get, set, url) => {
    const response = await fetch(url)
    set(countAtom, (await response.json()).count)
  }
)
```

The `write` function (2nd arg) returns a promise, which will suspend.

We just need to make it synchronous and returns nothing, just like this:

```tsx
const fetchCountAtom = atom(
  (get) => get(countAtom),
  (_get, set, url) => {
    const fetchData = async () => {
      const response = await fetch(url)
      set(countAtom, (await response.json()).count)
    }
    fetchData()
  }
)
```


# How to persist atoms

The core itself doesn't support persistence.
There are several patterns for persistence depending on requirements.

## A simple pattern with localStorage

```js
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

```js
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

This requires [onMount](../api/core.js#onmount).

```js
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
}
```

---

## A serialize atom pattern

```tsx
const serializeAtom = atom<
  null,
  | { type: 'serialize'; callback: (value: string) => void }
  | { type: 'deserialize'; value: string }
>(null, (get, set, action) => {
  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: React.FC = () => {
  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

https://codesandbox.io/s/jotai-todos-ijyxm

## A pattern with atomFamily

```tsx
const serializeAtom = atom<
  null,
  | { type: 'serialize'; callback: (value: string) => void }
  | { type: 'deserialize'; value: string }
>(null, (get, set, action) => {
  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: React.FC = () => {
  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

https://codesandbox.io/s/react-typescript-forked-eilkg


# How to use resettable atoms

The jotai core doesn't support resettable atoms.
But you can create those with helper functions from `jotai/utils`.

## Primitive resettable atom with [`atomWithReset`](../api/utils.md#atomWithReset) / [`useResetAtom`](../api/utils.md#useResetAtom)

```jsx
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>
    </>
  )
}
```

### Examples

https://codesandbox.io/s/react-typescript-forked-w91cq

## Derived atom with [`RESET`](../api/utils.md#RESET) symbol

```jsx
import { atom, useAtom } 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: React.FC = () => {
  const [dollars] = useAtom(dollarsAtom)
  const setCents = useUpdateAtom(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>
    </>
  )
}
```

### Examples

https://codesandbox.io/s/react-typescript-forked-41c0s


# How to use jotai with typescript

## Version requirement

jotai uses TypeScript 3.8+ syntax. Upgrade your TypeScript version if you're on 3.7.5 or lower.

## Notes

### Primitive atoms are basically type inferred

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

### Primitive atoms can be explicitly typed

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

### Derived atoms are also type inferred and explicitly typed

```ts
const asyncStrAtom = atom(async () => "foo")
const writeOnlyAtom = atom(null, (_get, set, str: string) => set(fooAtom, str)
const readWriteAtom = atom<string, number>(
  get => get(strAtom),
  (_get, set, num) => set(strAtom, String(num))
)
```

### useAtom is typed based on atom types

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


# Async

Async support is first class in jotai. It fully leverages React Suppense.

> Technically, Suspense usage other than React.lazy is still unsupported / undocumented in React 17. If this is blocking, check out [guides/no-suspense](../guides/no-suspense.md).

## Suspense

To use async atoms, you need to wrap your component tree with `<Suspense>`.
If you have `<Provider>` at least one `<Suspense>` is placed inside the `<Provider>`.

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

Having more `<Suspense>`s in the component tree is possible.

## Async read atom

The `read` function of an atom can return a promise.
It will suspend and re-render when the promise is fulfilled.

Most importantly, useAtom only returns a resolved value.

```js
const countAtom = atom(1)
const asyncCountAtom = atom(async (get) => get(countAtom) * 2)
// even though the read function returns a promise,

const Component = () => {
  const [num] = useAtom(asyncCountAtom)
  // `num` is guaranteed to be a number.
}
```

An atom becomes async not only if the atom read function is async,
but also one or more of its dependencies are async.

```js
const anotherAtom = atom((get) => get(asyncCountAtom) / 2)
// even though this atom doesn't return a promise,
// it is a read async atom because `asyncCountAtom` is async.
```

## Async write atom

There are another kind of async atoms, called async write atom.
When `write` function of atom returns a promise, it may suspend.
This happens only if the atom is used directly with useAtom,
regardless of its value. (The atom value can be just `null`.)

```js
const countAtom = atom(1)
const asyncIncrementAtom = atom(null, async (get, set) => {
  // await something
  set(countAtom, get(countAtom) + 1)
})

const Component = () => {
  const [, increment] = useAtom(asyncIncrementAtom)
  // it will suspend while `increment` is pending.
}
```

> There's no way to know as of now if an atom suspends because of `read` or `write`.


# How is jotai different from zustand?

## Name

Jotai means "state" in Japanese.
Zustand means "state" in German.

## Analogy

Jotai is close to Recoil.
Zustand is close to Redux.

## Where state resides

Jotai state is within React component tree.
Zustand state is in the store outside React.

## How to structure state

Jotai state consists of atoms (i.e. bottom-up).
Zustand state is one object (i.e. top-down).

## Technical difference

The major difference is the state model. Zustand is basically a single store (you could create multiple stores, but they are separated.) Jotai is primitive atoms and composing them. In this sense, it's the matter of programming mental model.

Jotai can be seen as a replacement for useState+useContext. Instead of creating multiple contexts, atoms share one big context.

Zustand is an external store and the hook is to connect the external world to the React world.

## When to use which

- If you need a replacement for useState+useContext, jotai fits well.
- If you want to update state outside React, zustand works better.
- If code splitting is important, jotai should perform well.
- If you prefer Redux devtools, zustand is good to go.
- If you want to make use of Suspense, jotai is the one.
- If you need a global store to bridge between two react reconcilers, zustand will only work.

---

# How is jotai different from recoil?

(Disclaimer: the author is not very familiar with Recoil, this can be biased and not accurate.)

## Developer

- Jotai is developed with collective work by a few developers in Poimandres (formerly react-spring) org.
- Recoil is developed by a team at Facebook.

## Basis

- Jotai is focusing on primitive APIs for lean learning, and it's unopinionated. (The same philosophy with Zustand)
- Recoil is full featured for big apps with various requirements.

## Technical difference

- Jotai depends on atom object referential identities.
- Recoil depends on atom string keys.

## When to use which

- If you want to learn something new, either should work.
- If you like Zustand, Jotai would also be pleasant.
- If your app heavily requires state serialization (storing state in storage, server, or URL), Recoil comes with good features.
- If you need React Context alternatives, Jotai comes with enough features.
- If you would try to create a new library, Jotai might give good primitives.
- Otherwise, both are pretty similar about the general goals and basic techniques, so please try both and give us a feedback.


# Concepts

Jotai was born to solve extra re-render issue in React.
Extra re-render is a render process that produces the same UI result,
with which users won't see any differences.

To tackle this issue naively with React context (useContext + useState),
one would probably require many contexts and face some issues.

- Provider hell: It's likely that your root component has many context providers, which is technically okay, and sometimes desirable to provide context in different subtree.
- Dynamic addition/deletion: Adding a new context at runtime is not very nice, because you need to add a new provider and its children will be re-mounted.

Traditionally, a top-down solution to this is to use selector interface.
The [use-context-selector](https://github.com/dai-shi/use-context-selector) library is one example.
The issue with this approach is the selector function needs to return
referentially equal values to prevent re-renders and often requires some memoization technique.

Jotai takes a bottom-up approach with atomic model, inspired by [Recoil](https://recoiljs.org/).
One can build state combining atoms and renders are optimized based on atom dependency.
This avoids requiring the memoization technique.

Jotai has two principles.

- Primitive: Its basic interface is pretty much like `useState`.
- Flexible: Derived atoms can combine other atoms and also allow `useReducer` style with side effects.

Jotai's core API is minimalistic and allows building various utils based on it.

Check out [comparison doc](./comparison.md) to see some differences with other libraries.


# Getting Started

State in jotai is a set of atoms.
An atom is a piece of state.
Unlike useState in React, atoms are not tied to specific components.
Let's see how to define and use atoms.

## atom

There's an exported function called `atom`, which is to create
an atom config. We call it "config" as it's just a definition
and it doesn't hold a value. We may just call it "atom" if the context is clear.

To create a primitive atom (config), all you need is pass an initial value.

```js
import { atom } from 'jotai'

const priceAtom = atom(10)
const messageAtom = atom('hello')
const productAtom = atom({ id: 12, name: 'good stuff' })
```

You can also create derived atoms. We have three patterns.

- Read-only atom
- Write-only atom
- Read-Write atom

To create derived atoms, we pass a read function and an optional write function.

```js
const readOnlyAtom = atom((get) => get(priceAtom) * 2)
const writeOnlyAtom = atom(
  null, // it's a convention to pass `null` for the first argument
  (get, set, update) => {
    // `update` is any single value we receive for updating this atom
    set(priceAtom, get(priceAtom) - update.discount)
  }
)
const readWriteAtom = atom(
  (get) => get(priceAtom) * 2,
  (get, set, newPrice) => {
    set(priceAtom, newPrice / 2)
    // you can set as many atoms as you want at the same time
  }
)
```

`get` in the read function is to read the atom value.
It's reactive and read dependencies are tracked.

`get` in the write function is also to read atom value, and it's not tracked.
Furthermore, it can't read unresolved async values.
For async behavior, please refer [./async.md](async.md).

`set` in the write function is to write atom value.
It will invoke the write function of the target atom.

Atom configs can be created anywhere, but referential equality is important.
They can be created dynamically too.
To create an atom in render function, `useMemo` or `useRef` is required to get a stable reference. If in doubt about using `useMemo` or `useRef` for memorization, use `useMemo`.

```jsx
const Component = ({ value }) => {
  const valueAtom = useMemo(() => atom({ value }), [value])
  // ...
}
```

## useAtom

The `useAtom` hook is to read an atom value in the state.
The state can be seen as a WeakMap of atom configs and atom values.

The `useAtom` function returns the atom value and an updating function as a tuple,
just like React's `useState`.
It takes an atom config created with `atom()`.

Initially, there is no value stored in the state.
The first time the atom is used via `useAtom`,
the initial value is stored in the state.
If the atom is a derived atom, the read function is executed to compute an initial value.
When an atom is no longer used, meaning all the components using it is unmounted,
and the atom config no longer exists, the value in the state is garbage collected.

```js
const [value, updateValue] = useAtom(anAtom)
```

The `updateValue` takes just one argument, which will be passed
to the third argument of write function of the atom.
The behavior totally depends on how the write function is implemented.

## Provider

Provider is to provide a state for component sub tree.
Multiple Providers can be used for multiple subtrees, even nested.
This works just like the normal React Context.

If an atom is used in a tree which no Providers exist,
it will use the default state. This is so-called provider-less mode.

Providers are usefule for some reasons.

1. It can provide a different state for each sub tree.
2. Provider can hold some debug information.
3. Provider can accept initial values of atoms.

```jsx
const SubTree = () => (
  <Provider>
    <Child />
  </Provider>
)
```


# Showcase

- Text Length example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/text_length)

  Count the length and show the uppercase of any text.

- Hacker News example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/hacker_news)

  Demonstrate a news articles with jotai, hit next to see more articles.

- Todos example [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/todos)

  Record your todo list by typing them into this app, check them if you have completed the task, and switch between `Completed` and `Incompleted` to see the status of your task.

- Todos example with atomFamily and localStorage [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://githubbox.com/pmndrs/jotai/tree/master/examples/todos_with_atomFamily)

  Implement a todo list using atomFamily and localStorage, you can store your todo list to localStorage by click `Save to localStorage`, then remove your todo list and restore them by click `Load from localStorage`.

- Clock with Next.js [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/nextjs-with-jotai-5ylrj)

  An UTC time eletronic clock implement using Next.js and jotai.

- Tic Tac Toe game [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/jotai-tic-tac-6cg3h)

  A game of tic tac toe implemented with jotai.

- React Three Fiber demo [![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?style=flat-square&logo=codesandbox)](https://codesandbox.io/s/jotai-r3f-fri9d)

  A simple demo to use jotai with react-three-fiber


Jotai Docs