Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/jotai/docs/guides/persistence.mdx

👻 Primitive and flexible state management for React
Go to Latest
File
---title: Persistencedescription: How to persist atomsnav: 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.
(Note: This guide is a bit outdated and requires some rewrites.)
There are also several alternate implementations here:
### A simple pattern with localStorage
```jsconst 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
```jsconst 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#onmount-property).
```jsconst 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.
### Example with sessionStorage
Same as AsyncStorage, just use `atomWithStorage` util and override the default storage with the `sessionStorage`
```jsimport { atomWithStorage, createJSONStorage } from 'jotai/utils'
const storage = createJSONStorage(() => sessionStorage)const someAtom = atomWithStorage('some-key', someInitialValue, storage)```
### A serialize atom pattern
```tsxtype 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
<CodeSandbox id="g96xjx" />### A pattern with atomFamily
```tsxtype 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> )}```
#### Examples
<CodeSandbox id="oyiw5r" />