useSyncExternalStore

The Problem: Tearing in Concurrent React

Here's a subtle problem that didn't exist before React 18. Concurrent rendering can pause a render mid-way and resume later. If your component reads from an external mutable source (not React state), different parts of the same render might see different values — a bug called tearing.

// UNSAFE in concurrent React:
let externalCounter = 0;

function Counter() {
  // This reads a mutable external value during render.
  // In concurrent mode, React may pause between rendering
  // Child1 and Child2. If externalCounter changes during
  // the pause, Child1 shows 5 and Child2 shows 6.
  return (
    <div>
      <Child1 value={externalCounter} />
      <Child2 value={externalCounter} />
    </div>
  );
}

useSyncExternalStore solves this by forcing synchronous reads from external stores during render, preventing tearing.

The API

const snapshot = useSyncExternalStore(
  subscribe,      // Function to subscribe to store changes
  getSnapshot,    // Function to read the current value
  getServerSnapshot // Optional: Function to read value during SSR
);

Three requirements:

1. subscribe(callback): registers a listener, returns an unsubscribe function
2. getSnapshot(): returns the current value. Must return the same reference if nothing changed
3. getServerSnapshot(): returns the value for server rendering

Basic Example: Window Width

function useWindowWidth() {
  return useSyncExternalStore(
    // subscribe: listen for resize events
    (callback) => {
      window.addEventListener('resize', callback);
      return () => window.removeEventListener('resize', callback);
    },
    // getSnapshot: read current width
    () => window.innerWidth,
    // getServerSnapshot: default for SSR
    () => 1024
  );
}

function ResponsiveLayout() {
  const width = useWindowWidth();
  return width > 768 ? <DesktopLayout /> : <MobileLayout />;
}

Subscribing to External Stores

Browser Online Status

function useOnlineStatus() {
  return useSyncExternalStore(
    (callback) => {
      window.addEventListener('online', callback);
      window.addEventListener('offline', callback);
      return () => {
        window.removeEventListener('online', callback);
        window.removeEventListener('offline', callback);
      };
    },
    () => navigator.onLine,
    () => true // Assume online during SSR
  );
}

Custom External Store

function createStore(initialState) {
  let state = initialState;
  const listeners = new Set();

  return {
    getState: () => state,
    setState: (newState) => {
      state = typeof newState === 'function' ? newState(state) : newState;
      listeners.forEach(listener => listener());
    },
    subscribe: (listener) => {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
  };
}

const counterStore = createStore({ count: 0 });

function CounterDisplay() {
  const { count } = useSyncExternalStore(
    counterStore.subscribe,
    counterStore.getState,
    counterStore.getState
  );

  return <p>Count: {count}</p>;
}

function IncrementButton() {
  return (
    <button onClick={() => counterStore.setState(s => ({ count: s.count + 1 }))}>
      Increment
    </button>
  );
}

The getSnapshot Contract

This is the part that trips people up. getSnapshot has a strict requirement: it must return the same reference if nothing has changed:

// WRONG — new object every call
const getSnapshot = () => ({
  count: store.count,
  name: store.name,
});
// This creates an infinite loop! Each call returns a new object,
// React thinks the store changed, re-renders, calls getSnapshot again...

// CORRECT — return the store object directly
const getSnapshot = () => store.getState();
// Same reference if nothing changed

// CORRECT — memoize selector results
function useStoreSelector(selector) {
  const prevRef = useRef();
  const getSnapshot = useCallback(() => {
    const next = selector(store.getState());
    if (Object.is(prevRef.current, next)) {
      return prevRef.current;
    }
    prevRef.current = next;
    return next;
  }, [selector]);

  return useSyncExternalStore(store.subscribe, getSnapshot);
}

Production Scenario: Media Query Hook

function useMediaQuery(query) {
  const subscribe = useCallback(
    (callback) => {
      const mql = window.matchMedia(query);
      mql.addEventListener('change', callback);
      return () => mql.removeEventListener('change', callback);
    },
    [query]
  );

  const getSnapshot = useCallback(
    () => window.matchMedia(query).matches,
    [query]
  );

  return useSyncExternalStore(
    subscribe,
    getSnapshot,
    () => false // Default for SSR
  );
}

function Navigation() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  return isMobile ? <HamburgerMenu /> : <FullNavBar />;
}

Challenge: Build a Local Storage Hook

Challenge: Synchronized Local Storage

// Build a hook that syncs state with localStorage,
// using useSyncExternalStore so it works across browser tabs.
// When one tab updates the value, other tabs should reflect the change.

function useLocalStorage(key, initialValue) {
  // Your implementation here
  // Hint: Use the 'storage' event for cross-tab sync
}

// Usage:
function App() {
  const [name, setName] = useLocalStorage('username', 'Anonymous');
  return <input value=`{name}` onChange=`{e => setName(e.target.value)}` />;
}

function useLocalStorage(key, initialValue) {
  const getSnapshot = useCallback(() => {
    const stored = localStorage.getItem(key);
    return stored !== null ? JSON.parse(stored) : initialValue;
  }, [key, initialValue]);

  const subscribe = useCallback((callback) => {
    const handler = (e) => {
      if (e.key === key || e.key === null) {
        callback();
      }
    };
    window.addEventListener('storage', handler);
    return () => window.removeEventListener('storage', handler);
  }, [key]);

  const getServerSnapshot = useCallback(() => initialValue, [initialValue]);

  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);

  const setValue = useCallback((newValue) => {
    const resolved = typeof newValue === 'function' ? newValue(getSnapshot()) : newValue;
    localStorage.setItem(key, JSON.stringify(resolved));
    // Dispatch storage event for same-tab notification
    // (storage event only fires in OTHER tabs by default)
    window.dispatchEvent(new StorageEvent('storage', { key }));
  }, [key, getSnapshot]);

  return [value, setValue];
}