Mastering Recoil: Advanced State Management Techniques for React

Overview

Recoil is a state‑management library released by Facebook for React. It models state as a directed graph where atoms are root nodes and selectors are pure functions that derive values. This enables incremental and distributed definition of state.

Installation & Setup

Install the package: npm install recoil Wrap the root of the React tree with RecoilRoot (imported from recoil):

import { RecoilRoot } from 'recoil';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <RecoilRoot>
    <App />
  </RecoilRoot>,
  document.getElementById('root')
);

Atoms

Atoms hold primitive state. Each atom requires a unique key and a default value.

import { atom } from 'recoil';

const firstNameAtom = atom({
  key: 'firstName',
  default: '',
});

const lastNameAtom = atom({
  key: 'lastName',
  default: '',
});

Selectors

Selectors compute derived values. They also need a unique key. A selector can be read‑only (only get) or writable (provide a set function).

import { selector } from 'recoil';

const fullNameSelector = selector({
  key: 'fullName',
  get: ({ get }) => {
    return `${get(firstNameAtom)} ${get(lastNameAtom)}`;
  },
  set: ({ set }, newValue) => {
    const [first, last] = newValue.split(' ');
    set(firstNameAtom, first ?? '');
    set(lastNameAtom, last ?? '');
  },
});

Hooks

Recoil provides React hooks that mirror the standard useState API. useRecoilState(atom) – read and write. useRecoilValue(atom|selector) – read‑only. useSetRecoilState(atom) – write‑only.

function UserProfile() {
  const [firstName, setFirstName] = useRecoilState(firstNameAtom);
  return <p>First name: {firstName}</p>;
}

Family APIs for Parameterised State

atomFamily

and selectorFamily return factory functions that create atoms or selectors based on a parameter. This is useful when many components need independent but structurally identical state.

import { atomFamily, selectorFamily } from 'recoil';

const nodeAtom = atomFamily({
  key: 'node',
  default: {},
});

function Node({ nodeId }) {
  const [node, setNode] = useRecoilState(nodeAtom(nodeId));
  // …
}

Async Selectors and Suspense

A selector may return a Promise. When such a selector is read, React Suspense automatically suspends rendering until the promise resolves.

const userSelector = selector({
  key: 'user',
  get: async () => {
    const response = await fetch('/api/user');
    return response.json();
  },
});

Consume the selector inside a Suspense boundary:

function App() {
  const user = useRecoilValue(userSelector);
  return <p>Hello, {user.name}</p>;
}

// In the component tree
<Suspense fallback={<span>Loading…</span>}>
  <App />
</Suspense>

If you need to handle loading and error states manually, use useRecoilValueLoadable, which returns a Loadable object with state ('loading', 'hasValue', 'hasError') and getValue().

const loadable = useRecoilValueLoadable(userSelector);
if (loadable.state === 'loading') {
  // render loading UI
} else if (loadable.state === 'hasError') {
  // render error UI
} else {
  const user = loadable.getValue();
  // render user data
}

Snapshot API (SSR & Time‑Travel)

The Snapshot object lets you set initial values for server‑side rendering or capture a point‑in‑time state that can be restored later.

function initState({ set }) {
  set(firstNameAtom, 'Alice');
  set(lastNameAtom, 'Smith');
}

function Root() {
  return (
    <RecoilRoot initializeState={initState}>
      {/* application components */}
    </RecoilRoot>
  );
}

Example of a time‑machine component that saves and restores a snapshot:

function TimeMachine() {
  const snapshotRef = useRef(null);
  const [count, setCount] = useRecoilState(countAtom);

  const save = useRecoilCallback(({ snapshot }) => () => {
    snapshot.retain();
    snapshotRef.current = snapshot;
  });

  const restore = useRecoilCallback(({ gotoSnapshot }) => () => {
    if (snapshotRef.current) {
      gotoSnapshot(snapshotRef.current);
    }
  });

  return (
    <div>
      <button onClick={save}>Save</button>
      <button onClick={restore}>Restore</button>
      <button onClick={() => setCount(c => c + 1)}>Add {count}</button>
    </div>
  );
}

External Synchronisation (recoil‑sync)

The recoil-sync package can bind atoms to external sources such as URL history, databases, or animation libraries. It optionally uses @recoiljs/refine for schema validation and migration.

// Example: sync an atom with the browser URL query string
import { syncEffect } from 'recoil-sync';

const queryAtom = atom({
  key: 'query',
  default: '',
  effects_UNSTABLE: [
    syncEffect({
      sync: url => new URLSearchParams(url.search).get('q') ?? '',
      read: ({ setSelf }, newValue) => setSelf(newValue),
    }),
  ],
});

Async‑to‑Sync Trick

When a selector’s get contains asynchronous code, Recoil treats a rejected promise as a thrown exception. If all async selectors are executed before any synchronous selector that depends on their result, the same selector can be used synchronously after the data has been cached.

Loadable API Details

The Loadable object returned by useRecoilValueLoadable has the following shape: state: one of 'loading', 'hasValue', 'hasError'. contents: the resolved value (when state === 'hasValue') or the error (when state === 'hasError'). getValue(): returns the value or throws if not available.

Performance & Mental Load

Recoil’s concepts map directly onto familiar React hooks ( useState, useEffect, useCallback, Suspense). Consequently the API surface adds little cognitive overhead compared with other state‑management solutions.