persistence.mdx

---
title: Persistence
description: How to persist atoms
nav: 7.14
---

Jotai has an [atomWithStorage function in the utils bundle](../utilities/storage.mdx) for persistence that supports persisting state in `sessionStorage`, `localStorage`, `AsyncStorage`, or the URL hash.

There are also several alternate implementations here:

## 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](../core/atom.mdx#on-mount).

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

Don't forget to check out the [Async documentation](../guides/async.mdx) for more details on how to use async atoms.

### Usage in Async actions

When using an asynchronous storage, the reading of the created atoms are asynchronous too. That comes with some limitations. Before `useAtom` has been called at least once, the value is not set.
This can cause an issue, for example, if you want to retrieve the value of your stored atom in an async action (write-only atom).

Let's use the [atomWithStorage function in the utils bundle](../utilities/storage.mdx) for the examples, so that we have more options available.

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

const storage = createJSONStorage(() => AsyncStorage)
const userId = atomWithStorage('user-id-key', null, storage)
const userInfo = atom({})
const fetchUserInfo = atom(null, async (get, set, payload: any) => {
  const id = get(userId) // This throws an error if "userId" is not loaded yet
  const info = await fetch('https://jotai.org/users/' + id)
  set(userInfo, info)
})
```

We want to make sure the action will never fail. As always with asynchronous flow in Jotai, we have 2 options: with or without **Suspense**.

#### With Suspense

You may want to preload atoms at root level of your app directly:

```js
const Preloader = () => {
  useAtomValue(userId) // Trigger the "onMount" function that will load the data from the store
  return null
}
```

```jsx
const Root = () => {
  return (
    <Suspense fallback={<Text>Hydrating...<Text>}>
      <Preloader /> {/* Wait for atoms to preload */}
      <App /> {/* Rest of your app */}
    </Suspense>
  )
}
```

#### Without Suspense

```js
// We add the "delayInit: true" option to tell jotai not to use Suspense
const storage = { ...createJSONStorage(() => AsyncStorage), delayInit: true }
const userId = atomWithStorage('user-id-key', null, storage)
const userInfo = atom({})
const fetchUserInfo = atom(null, async (get, set, payload) => {
  let id = get(userId)
  if (id === null) {
    // We make sure to preload if no value has yet been loaded
    id = await AsyncStorage.getItem('user-id-key')
  }
  const info = await fetch('https://jotai.org/users/' + id)
  set(userInfo, info)
})
```

But always remember jotai is un-opinionated and your workflow may not need preloading at all.

---

## Example with sessionStorage

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

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

const storage = createJSONStorage(() => sessionStorage)
const someAtom = atomWithStorage('some-key', someInitialValue, storage)
```

## 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 = () => {
  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

<CodeSandbox id="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 = () => {
  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

<CodeSandbox id="eilkg" />