use-hydrate-atoms.mdx

title
useHydrateAtoms

Ref: pmndrs#340

Usage

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

The primary use case for useHydrateAtoms are SSR apps like Next.js, where an initial value is e.g. fetched on the server, which can be passed to a component by props.

// Definition
function useHydrateAtoms(
  values: Iterable<readonly [Atom<unknown>, unknown]>,
  scope?: Scope
): void

The hook takes an iterable of tuples containing [atom, value] as an argument and optionally scope.

// Usage with an array, specifying a scope
useHydrateAtoms(
  [
    [countAtom, 42],
    [frameworkAtom, 'Next.js'],
  ],
  myScope
)
// Or with a map
const [initialValues] = useState(() => new Map([[count, 42]]))
useHydrateAtoms(initialValues)

Atoms can only be hydrated once per scope. Therefore, if the initial value used is changed during rerenders, it won't update the atom value.

If there's a need to hydrate in multiple scopes, use multiple useHydrateAtoms hooks to achieve that.

useHydrateAtoms([
  [countAtom, 42],
  [frameworkAtom, 'Next.js'],
])
useHydrateAtoms(
  [
    [countAtom, 17],
    [frameworkAtom, 'Gatsby'],
  ],
  myScope
)

Codesandbox

There's more examples in the Next.js section.