Storage

atomWithStorage

Ref: https://github.com/pmndrs/jotai/pull/394

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

The atomWithStorage function creates an atom with a value persisted in localStorage or sessionStorage for React or AsyncStorage for React Native.

Parameters

key (required): a unique string used as the key when syncing state with localStorage, sessionStorage, or AsyncStorage

initialValue (required): the initial value of the atom

storage (optional): an object with the following methods:

• getItem(key, initialValue) (required): Reads an item from storage, or falls back to the intialValue
• setItem(key, value) (required): Saves an item to storage
• removeItem(key) (required): Deletes the item from storage
• subscribe(key, callback, initialValue) (optional): A method which subscribes to external storage updates.

options (optional): an object with the following properties:

• getOnInit (optional, by default false): A boolean value indicating whether to get item from storage on initialization. Note that in an SPA with getOnInit either not set or false you will always get the initial value instead of the stored value on initialization. If the stored value is preferred set getOnInit to true.

If not specified, the default storage implementation uses localStorage for storage/retrieval, JSON.stringify()/JSON.parse() for serialization/deserialization, and subscribes to storage events for cross-tab synchronization.

createJSONStorage util

To create a custom storage implementation with JSON.stringify()/JSON.parse() for the storage option, createJSONStorage util is provided.

Usage:

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

Note: JSON.parse is not type safe. If it can't accept any types, some kind of validation would be necessary for production apps.

Server-side rendering

Any JSX markup that depends on the value of a stored atom (e.g., a className or style prop) will use the initialValue when rendered on the server (since localStorage and sessionStorage are not available on the server).

This means that there will be a mismatch between what is originally served to the user's browser as HTML and what is expected by React during the rehydration process if the user has a storedValue that differs from the initialValue.

The suggested workaround for this issue is to only render the content dependent on the storedValue client-side by wrapping it in a custom <ClientOnly> wrapper, which only renders after rehydration. Alternative solutions are technically possible, but would require a brief "flicker" as the initialValue is swapped to the storedValue, which can result in an unpleasant user experience, so this solution is advised.

Deleting an item from storage

For the case you want to delete an item from storage, the atom created with atomWithStorage accepts the RESET symbol on write.

See the following example for the usage:

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

If needed, you can also do conditional resets based on previous value.

This can be particularly useful if you wish to clear keys in localStorage if previous values meet a condition.

Below exemplifies this usage that clears the visible key whenever the previous value is true.

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

React-Native implementation

You can use any library that implements getItem, setItem & removeItem. Let's say you would use the standard AsyncStorage provided by the community.

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)

Notes with AsyncStorage (since v2.2.0)

If you use any kinds of AsyncStorage, the atom value can become async. Hence, if you are to update the value, you need to possibly resolve the promise.

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

Validating stored values

To add runtime validation to your storage atoms, you will need to create a custom implementation of storage.

Below is an example that utilizes Zod to validate values stored in localStorage with cross-tab synchronization.

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
    }
    window.addEventListener('storage', (e) => {
      if (e.storageArea === localStorage && e.key === key) {
        let newValue
        try {
          newValue = myNumberSchema.parse(JSON.parse(e.newValue ?? ''))
        } catch {
          newValue = initialValue
        }
        callback(newValue)
      }
    })
  },
})

We also have a new util unstable_withStorageValidator to simplify some cases. The above case would become:

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