React Hooks Cheatsheet — All 17 Built-In Hooks Plus Custom Patterns, with Real Examples and Pitfalls

The bread-and-butter state hook. Returns a tuple of [current value, setter]. The setter is stable across renders; calling it triggers a re-render with the new value.

⚠ Common pitfall: Stale closure: if you call setState(count + 1) twice in a row, only one increment happens because both reads of `count` capture the same value. Always use the functional form setState(c => c + 1) when the next value depends on the previous.

const [count, setCount] = useState(0);
// functional form is mandatory when next depends on prev
const inc = () => setCount(c => c + 1);

// lazy initializer — fn runs once, not on every render
const [grid, setGrid] = useState(() => buildExpensiveGrid(1000));

State hook for state shapes with multiple transitions. The reducer is a (state, action) => state function. dispatch is stable, so it is safe to pass to children without breaking memoization.

⚠ Common pitfall: The reducer must be pure — no fetch, no setTimeout, no DOM access inside. Side effects belong in useEffect or the handler that calls dispatch.

type Action = { type: 'inc' } | { type: 'reset' };
function reducer(state: number, action: Action) {
  switch (action.type) {
    case 'inc': return state + 1;
    case 'reset': return 0;
  }
}
const [count, dispatch] = useReducer(reducer, 0);

// async flow modeled as a state machine
type S = { status: 'idle' | 'loading' | 'ok' | 'err'; data?: User };
type A = { type: 'start' } | { type: 'ok'; data: User } | { type: 'err' };

Run side effects AFTER the browser paints. The optional cleanup function runs before the next effect and on unmount. Deps array controls when the effect re-fires.

⚠ Common pitfall: Missing deps = stale closure: the effect captures the values from the render where it was DEFINED. Lint with `eslint-plugin-react-hooks` exhaustive-deps and either include every value you read, or move the value into a ref or out of the component.

useEffect(() => {
  const id = setInterval(() => setTick(t => t + 1), 1000);
  return () => clearInterval(id);   // cleanup is mandatory for timers
}, []);

// subscribe + cleanup pattern
useEffect(() => {
  const onResize = () => setWidth(window.innerWidth);
  window.addEventListener('resize', onResize);
  return () => window.removeEventListener('resize', onResize);
}, []);

// data fetching with abort to avoid setState-after-unmount warning
useEffect(() => {
  const ctrl = new AbortController();
  fetch(`/api/user/${id}`, { signal: ctrl.signal })
    .then(r => r.json()).then(setUser).catch(() => {});
  return () => ctrl.abort();
}, [id]);

Same signature as useEffect but fires SYNCHRONOUSLY after the DOM mutation and BEFORE the browser paints. Use to measure or mutate layout without a flash.

⚠ Common pitfall: It blocks paint. Long work here = jank. If you see "useLayoutEffect does nothing on the server" warnings during SSR, switch to useEffect or guard the import.

useLayoutEffect(() => {
  const { height } = ref.current!.getBoundingClientRect();
  setRowHeight(height);   // setState is safe — it batches before paint
}, []);

Niche hook designed for CSS-in-JS libraries. Fires synchronously BEFORE any DOM mutations so libraries can inject <style> tags without causing layout to thrash.

⚠ Common pitfall: Refs are not yet attached and you cannot use setState here — those are documented React contract. Treat this as a library-only hook.

// styled-components-style use case
useInsertionEffect(() => {
  const tag = document.createElement('style');
  tag.textContent = generatedCss;
  document.head.appendChild(tag);
  return () => tag.remove();
}, [generatedCss]);

Cache the return value of an expensive computation between renders. The function runs only when one of the deps changes.

⚠ Common pitfall: useMemo is a hint, not a guarantee — React may discard the cached value to free memory. Never put logic that MUST run only once inside; use useEffect with [] or a ref instead.

const visible = useMemo(
  () => items.filter(i => i.name.includes(query)).sort(byDate),
  [items, query],
);

// stabilize an object so memoized child does not re-render
const style = useMemo(() => ({ color, fontSize }), [color, fontSize]);

Memoize a function reference between renders so that React.memo children or downstream hooks see a stable callback. Equivalent to useMemo(() => fn, deps).

⚠ Common pitfall: Same closure trap as useEffect: missing a dep means the cached function reads STALE values. exhaustive-deps lint is mandatory.

const onSelect = useCallback(
  (id: string) => setSelected(s => ({ ...s, [id]: true })),
  [],   // setSelected from useState is already stable
);

Returns a mutable .current object that survives re-renders WITHOUT triggering them. Two uses: (1) DOM node reference via the ref attribute, (2) mutable instance value (like a class field).

⚠ Common pitfall: Reading ref.current during render is fragile — for DOM refs the value is null on first render. Read in useEffect / useLayoutEffect or event handlers, not the render body.

const inputRef = useRef<HTMLInputElement>(null);
useEffect(() => { inputRef.current?.focus(); }, []);
return <input ref={inputRef} />;

// instance value pattern — no re-render on change
const lastSeenRef = useRef(0);
function onScroll() { lastSeenRef.current = window.scrollY; }

Customize the value exposed to a parent via ref. Pair with forwardRef. Use to expose a narrow imperative API like { focus, scrollIntoView } instead of the raw DOM node.

⚠ Common pitfall: Without forwardRef, ref does nothing on a function component. Forgetting the deps array means the imperative API is re-created every render.

const Input = forwardRef<{ focus: () => void }, Props>((props, ref) => {
  const inner = useRef<HTMLInputElement>(null);
  useImperativeHandle(ref, () => ({
    focus: () => inner.current?.focus(),
  }), []);
  return <input ref={inner} {...props} />;
});

Read the value of a Context inside a function component. The component re-renders whenever the nearest Provider above it pushes a new value.

⚠ Common pitfall: Putting an inline object as Provider value re-creates it every render and re-renders every consumer. Memoize the value with useMemo: <Ctx.Provider value={useMemo(() => ({a, b}), [a, b])}>.

const ThemeCtx = createContext<'light' | 'dark'>('light');
function Toolbar() {
  const theme = useContext(ThemeCtx);
  return <div className={theme}>...</div>;
}

Mark a state update as non-urgent. React keeps the previous UI interactive while the transition renders in the background, and isPending tells you it is running.

⚠ Common pitfall: Wrapping a fetch call does nothing — only the state UPDATES inside the callback are deferred. Use Suspense + use() for data, useTransition for the resulting state.

const [isPending, startTransition] = useTransition();
function onChange(e: ChangeEvent<HTMLInputElement>) {
  setQuery(e.target.value);                 // urgent: input updates now
  startTransition(() => setList(filter(e.target.value))); // non-urgent
}

Return a deferred copy of a value. The deferred copy lags behind the real one during expensive renders, letting urgent updates win. Like useTransition but for values you do not own (props).

⚠ Common pitfall: Without React.memo on the heavy consumer, useDeferredValue still triggers the slow render — just slightly later. The memo is what makes it work.

function Search({ query }: { query: string }) {
  const deferred = useDeferredValue(query);
  const isStale = deferred !== query;
  return (
    <div style={{ opacity: isStale ? 0.5 : 1 }}>
      <HeavyList query={deferred} />
    </div>
  );
}

Subscribe to an external (non-React) data source — Redux store, browser API, observable — without tearing under concurrent rendering. Returns the current snapshot and re-renders when the store notifies.

⚠ Common pitfall: getSnapshot MUST return a referentially stable value when nothing changed — returning a fresh object every call causes an infinite render loop. Cache snapshots in a closure.

function useOnline() {
  return useSyncExternalStore(
    (cb) => {
      window.addEventListener('online', cb);
      window.addEventListener('offline', cb);
      return () => {
        window.removeEventListener('online', cb);
        window.removeEventListener('offline', cb);
      };
    },
    () => navigator.onLine,
    () => true,  // SSR snapshot
  );
}

Generate a unique, deterministic id that is stable across server and client renders. Designed for accessibility attributes that need to associate a label with an input.

⚠ Common pitfall: The id contains colons (e.g. `:r1:`) — fine in HTML attributes but breaks naive querySelector(`#${id}`) calls. Use document.getElementById, which accepts any string.

function Field({ label }: { label: string }) {
  const id = useId();
  return <><label htmlFor={id}>{label}</label><input id={id} /></>;
}

React 19+. Show an immediate, optimistic UI while a server action is in flight. Returns a temporary state computed from the real state plus pending optimistic updates; reconciles when the action resolves.

⚠ Common pitfall: Must be called inside a transition or a server action — calling it from a normal event handler does nothing visible. The optimistic value disappears as soon as the action resolves; sync to local state if you need to keep it.

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: number) => current + 1,
);
async function onLike() {
  addLike(1);                   // UI updates immediately
  await serverLike(postId);     // real call
}

React 19+. Manage state that transitions via an async action — typically a form submit. Combines a reducer-style update, automatic pending flag, and progressive enhancement with form actions.

⚠ Common pitfall: The reducer signature is (state, formData) => Promise<state>, NOT the classic (state, action). isPending is true even if the user navigates away mid-action — clean up in an effect if it matters.

async function login(prev: State, fd: FormData): Promise<State> {
  const res = await api.login(fd.get('email'), fd.get('password'));
  return res.ok ? { user: res.user } : { error: res.message };
}
const [state, action, isPending] = useActionState(login, { user: null });
return <form action={action}>...</form>;

React 19+. Read the submission status of the PARENT <form>. Designed to be called from a button/input INSIDE a form so it can disable itself or show a spinner without prop-drilling.

⚠ Common pitfall: Returns false / null if the component is NOT a descendant of the form. Calling it on the same component as the <form> always returns false — it reads the PARENT form, not the current one.

function SubmitButton() {
  const { pending } = useFormStatus();
  return <button type="submit" disabled={pending}>
    {pending ? 'Saving…' : 'Save'}
  </button>;
}

React 19+. The unified read primitive — pass a Promise to suspend until it resolves, or a Context to read its value. Unlike other hooks, use() can be called inside if/loop/early-return.

⚠ Common pitfall: use(somePromise) reads CACHED promises. If you do not stabilize the Promise (in a parent, via cache(), or React Query), you cause an infinite suspend-resolve-render loop.

function User({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);   // suspends until resolved
  return <div>{user.name}</div>;
}

// conditional context read — useContext cannot do this
const value = condition ? use(CtxA) : use(CtxB);

Three-element tuple for boolean state: current value, a stable toggle function, and the raw setter. The toggle ignores arguments so it can be passed directly as onClick.

⚠ Common pitfall: If you pass toggle to onClick and TypeScript complains about MouseEvent vs void — overload the signature so it ignores its argument: () => void.

function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn(o => !o), []);
  return [on, toggle, setOn] as const;
}
const [open, toggleOpen] = useToggle();
<button onClick={toggleOpen}>{open ? 'Hide' : 'Show'}</button>

Same shape as useState but persists to window.localStorage and rehydrates on mount. Should serialize via JSON and guard against SSR (window undefined).

⚠ Common pitfall: JSON.parse throws on bad data — wrap in try/catch and fall back to initial. typeof window === "undefined" check is mandatory in Next.js / Astro SSR or the build crashes.

function useLocalStorage<T>(key: string, initial: T) {
  const [v, setV] = useState<T>(() => {
    if (typeof window === 'undefined') return initial;
    try { const raw = localStorage.getItem(key); return raw ? JSON.parse(raw) : initial; }
    catch { return initial; }
  });
  useEffect(() => { localStorage.setItem(key, JSON.stringify(v)); }, [key, v]);
  return [v, setV] as const;
}

Returns a value that lags behind the input by delayMs of "quiet time" — every change resets the timer. Use to throttle expensive work driven by frequently-changing values.

⚠ Common pitfall: Returning a stale value on dependency change — make sure the cleanup clears the timer. Debounce delay too short is a no-op; too long feels broken. 200-500 ms is the sweet spot for search.

function useDebounce<T>(value: T, delay = 300): T {
  const [v, setV] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setV(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return v;
}

Toy hook for one-off GET requests. Returns { data, error, loading } and aborts in-flight requests when url or component unmounts. NOT a replacement for React Query / SWR — those handle cache, retry, dedupe.

⚠ Common pitfall: Without AbortController, a fast-changing url leaves you with race conditions where an OLDER response overwrites a newer one. Always abort in the cleanup.

function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    const ctrl = new AbortController();
    setLoading(true);
    fetch(url, { signal: ctrl.signal })
      .then(r => r.json()).then(d => { setData(d); setLoading(false); })
      .catch(e => { if (e.name !== 'AbortError') { setError(e); setLoading(false); } });
    return () => ctrl.abort();
  }, [url]);
  return { data, error, loading };
}

Return whether a CSS media query currently matches. Subscribes via window.matchMedia and re-renders on change. Pair with useSyncExternalStore for concurrent safety.

⚠ Common pitfall: SSR returns false because window is undefined — that causes a layout flash. Wrap in useSyncExternalStore with a sane server snapshot, or render only on the client.

function useMediaQuery(query: string) {
  const subscribe = (cb: () => void) => {
    const mql = window.matchMedia(query);
    mql.addEventListener('change', cb);
    return () => mql.removeEventListener('change', cb);
  };
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    () => false,
  );
}
const isMobile = useMediaQuery('(max-width: 768px)');

Wrapper around addEventListener that pairs the listener with the React lifecycle and uses a ref to keep the handler fresh without re-subscribing on every render.

⚠ Common pitfall: Without the handler-in-ref trick, every render re-subscribes and the listener cost balloons. Capture deps explicitly and ref the latest handler.

function useEventListener<K extends keyof WindowEventMap>(
  event: K,
  handler: (e: WindowEventMap[K]) => void,
) {
  const ref = useRef(handler);
  useEffect(() => { ref.current = handler; }, [handler]);
  useEffect(() => {
    const fn = (e: WindowEventMap[K]) => ref.current(e);
    window.addEventListener(event, fn);
    return () => window.removeEventListener(event, fn);
  }, [event]);
}

Run handler when a mousedown / touchstart fires OUTSIDE the referenced element. Canonical pattern for closing popovers, dropdowns, modals.

⚠ Common pitfall: click event fires too late (the click target may already be removed). Use mousedown / pointerdown / touchstart so the close happens BEFORE the next click handler runs.

function useOnClickOutside(
  ref: RefObject<HTMLElement>,
  handler: (e: MouseEvent | TouchEvent) => void,
) {
  useEffect(() => {
    const fn = (e: MouseEvent | TouchEvent) => {
      const el = ref.current;
      if (!el || el.contains(e.target as Node)) return;
      handler(e);
    };
    document.addEventListener('mousedown', fn);
    document.addEventListener('touchstart', fn);
    return () => {
      document.removeEventListener('mousedown', fn);
      document.removeEventListener('touchstart', fn);
    };
  }, [ref, handler]);
}

Return the value from the PREVIOUS render. Implemented with a ref written in useEffect so the read during render returns the value from one render ago.

⚠ Common pitfall: Because the ref is set in useEffect AFTER render, on the very first render it returns undefined. Code must handle the undefined case explicitly.

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
  useEffect(() => { ref.current = value; }, [value]);
  return ref.current;
}
const prevCount = usePrevious(count);
const direction = prevCount === undefined ? 'init' : count > prevCount ? 'up' : 'down';

Return live window dimensions. Subscribes to resize and updates on change. SSR-safe variant uses useSyncExternalStore with a server snapshot.

⚠ Common pitfall: resize fires at 60+ Hz on some platforms. Without throttling, the entire subtree re-renders on every pixel of drag. Throttle to 16-100 ms or use rAF batching.

function useWindowSize() {
  const [size, setSize] = useState(() => ({
    width: typeof window === 'undefined' ? 0 : window.innerWidth,
    height: typeof window === 'undefined' ? 0 : window.innerHeight,
  }));
  useEffect(() => {
    let raf = 0;
    const onResize = () => {
      cancelAnimationFrame(raf);
      raf = requestAnimationFrame(() => {
        setSize({ width: window.innerWidth, height: window.innerHeight });
      });
    };
    window.addEventListener('resize', onResize);
    return () => { cancelAnimationFrame(raf); window.removeEventListener('resize', onResize); };
  }, []);
  return size;
}

Declarative setInterval. Pass null as delay to pause. Uses a ref to always call the LATEST callback closure without re-creating the interval on every render.

⚠ Common pitfall: A naive `useEffect(() => { setInterval(cb, d); }, [cb])` re-creates the interval whenever cb identity changes — usually every render. The ref-the-callback pattern is the fix Dan Abramov's blog made famous.

function useInterval(cb: () => void, delay: number | null) {
  const ref = useRef(cb);
  useEffect(() => { ref.current = cb; }, [cb]);
  useEffect(() => {
    if (delay === null) return;
    const id = setInterval(() => ref.current(), delay);
    return () => clearInterval(id);
  }, [delay]);
}
useInterval(() => setNow(Date.now()), running ? 1000 : null);