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);

Declarative setTimeout. Fires the callback once after delayMs; pass null to cancel. Like useInterval, it refs the latest callback so changing it never re-arms the timer.

⚠ Common pitfall: Like useInterval, putting the callback in the deps re-arms the timer on every render and the timeout never fires. Ref the callback and depend only on delay.

function useTimeout(cb: () => void, delay: number | null) {
  const ref = useRef(cb);
  useEffect(() => { ref.current = cb; }, [cb]);
  useEffect(() => {
    if (delay === null) return;
    const id = setTimeout(() => ref.current(), delay);
    return () => clearTimeout(id);
  }, [delay]);
}
useTimeout(() => setVisible(false), visible ? 4000 : null);

Return a getter that reports whether the component is still mounted. Useful before calling setState at the end of an async task to avoid the legacy "update on unmounted component" warning.

⚠ Common pitfall: Returning a boolean snapshot instead of a getter is wrong — the value is captured at render time and goes stale. Return a function that reads the ref at call time.

function useIsMounted() {
  const mounted = useRef(false);
  useEffect(() => {
    mounted.current = true;
    return () => { mounted.current = false; };
  }, []);
  return useCallback(() => mounted.current, []);
}
const isMounted = useIsMounted();
await save(); if (isMounted()) setDone(true);

Like useEffect but skips the FIRST run (mount). Runs only on subsequent dependency updates. Implemented with a ref flag that flips after the initial render.

⚠ Common pitfall: In React 18 StrictMode dev, effects run twice on mount — a naive boolean flag can mis-skip. Use a ref initialized to false and set it true at the end of the effect, not a module-level flag.

function useUpdateEffect(effect: () => void | (() => void), deps?: any[]) {
  const isFirst = useRef(true);
  useEffect(() => {
    if (isFirst.current) { isFirst.current = false; return; }
    return effect();
  }, deps);
}
useUpdateEffect(() => { syncUrl(filter); }, [filter]);

Manage a Set in state with stable helper actions. Each action returns a NEW Set (immutability) so React detects the change. Common for multi-select / checkbox lists.

⚠ Common pitfall: Mutating the Set in place (set.add(x); setSet(set)) does NOT re-render — the reference is unchanged. Always build a new Set: setSet(s => new Set(s).add(x)).

function useSet<T>(initial?: Iterable<T>) {
  const [set, setSet] = useState(() => new Set(initial));
  const actions = useMemo(() => ({
    add: (v: T) => setSet(s => new Set(s).add(v)),
    remove: (v: T) => setSet(s => { const n = new Set(s); n.delete(v); return n; }),
    toggle: (v: T) => setSet(s => { const n = new Set(s); n.has(v) ? n.delete(v) : n.add(v); return n; }),
    reset: () => setSet(new Set()),
  }), []);
  return [set, actions] as const;
}

Numeric state with stable inc/dec/set/reset actions and optional min/max clamping. All updates use the functional setState form so rapid clicks never drop increments.

⚠ Common pitfall: Clamping must happen inside the updater, not before it: inc should be setCount(c => clamp(c + 1)). Clamping the captured count drops concurrent updates.

function useCounter(initial = 0, { min = -Infinity, max = Infinity } = {}) {
  const clamp = (n: number) => Math.min(max, Math.max(min, n));
  const [count, setCount] = useState(clamp(initial));
  const actions = useMemo(() => ({
    inc: (step = 1) => setCount(c => clamp(c + step)),
    dec: (step = 1) => setCount(c => clamp(c - step)),
    set: (n: number) => setCount(clamp(n)),
    reset: () => setCount(clamp(initial)),
  }), []);
  return [count, actions] as const;
}

Copy text to the clipboard and expose a `copied` flag that flips true briefly. Wraps the async navigator.clipboard.writeText API and resets the flag with a timer.

⚠ Common pitfall: navigator.clipboard.writeText returns a Promise that REJECTS without a user gesture or on permission denial. Always .catch it, and feature-detect before calling.

function useClipboard(resetMs = 1500) {
  const [copied, setCopied] = useState(false);
  const copy = useCallback(async (text: string) => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), resetMs);
    } catch { setCopied(false); }
  }, [resetMs]);
  return { copy, copied };
}

Track whether the pointer is over an element. Returns a ref to attach and a boolean. Uses mouseenter / mouseleave so it does not fire for child bubbling like mouseover would.

⚠ Common pitfall: Re-attaching listeners when the ref node changes needs a ref callback, not a static ref object. Using mouseover instead of mouseenter makes hovered flicker as the pointer crosses children.

function useHover<T extends HTMLElement>() {
  const [hovered, setHovered] = useState(false);
  const ref = useRef<T | null>(null);
  useEffect(() => {
    const node = ref.current;
    if (!node) return;
    const on = () => setHovered(true);
    const off = () => setHovered(false);
    node.addEventListener('mouseenter', on);
    node.addEventListener('mouseleave', off);
    return () => {
      node.removeEventListener('mouseenter', on);
      node.removeEventListener('mouseleave', off);
    };
  }, []);
  return [ref, hovered] as const;
}

Observe when an element enters or leaves the viewport using IntersectionObserver. Returns a ref and the latest IntersectionObserverEntry (entry.isIntersecting tells you visibility).

⚠ Common pitfall: Re-creating the observer on every render thrashes performance — depend only on the serialized options, and disconnect in cleanup. The observer is async: the first entry may arrive a frame after mount.

function useIntersectionObserver(options?: IntersectionObserverInit) {
  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
  const ref = useRef<HTMLElement | null>(null);
  useEffect(() => {
    const node = ref.current;
    if (!node) return;
    const io = new IntersectionObserver(([e]) => setEntry(e), options);
    io.observe(node);
    return () => io.disconnect();
  }, [options?.root, options?.rootMargin, options?.threshold]);
  return [ref, entry] as const;
}

Set document.title to the given string and keep it in sync. Optionally restore the previous title on unmount. A tiny effect-driven sync to a non-React global.

⚠ Common pitfall: Setting document.title in render (not an effect) is a side effect during render and breaks concurrent rendering. Always do it in useEffect.

function useDocumentTitle(title: string, restore = false) {
  const prev = useRef(typeof document !== 'undefined' ? document.title : '');
  useEffect(() => {
    document.title = title;
  }, [title]);
  useEffect(() => {
    const previous = prev.current;
    return () => { if (restore) document.title = previous; };
  }, [restore]);
}

Return a function with a STABLE identity that always calls the latest version of fn. A userland version of the proposed useEffectEvent — lets you read fresh props/state inside a callback without adding deps.

⚠ Common pitfall: Calling it during render returns last-commit values and can tear under concurrent rendering. React ships useEffectEvent for exactly this; the userland version is a stopgap.

function useEventCallback<A extends any[], R>(fn: (...a: A) => R) {
  const ref = useRef(fn);
  useLayoutEffect(() => { ref.current = fn; });
  return useCallback((...args: A) => ref.current(...args), []);
}
const onScroll = useEventCallback(() => log(pageName, window.scrollY));

Return a value that updates at most once per intervalMs, even if the input changes faster. Unlike debounce (which waits for quiet), throttle guarantees a steady update cadence.

⚠ Common pitfall: A leading-only throttle drops the FINAL value if it arrives within the window — schedule a trailing update so the last value is not lost. Clear the timer in cleanup.

function useThrottle<T>(value: T, interval = 200): T {
  const [throttled, setThrottled] = useState(value);
  const last = useRef(Date.now());
  useEffect(() => {
    const now = Date.now();
    const remaining = interval - (now - last.current);
    if (remaining <= 0) { last.current = now; setThrottled(value); return; }
    const id = setTimeout(() => { last.current = Date.now(); setThrottled(value); }, remaining);
    return () => clearTimeout(id);
  }, [value, interval]);
  return throttled;
}

Lock or unlock body scrolling. When locked, sets overflow:hidden on documentElement and restores the previous value on unlock / unmount. Standard for modals and drawers.

⚠ Common pitfall: On iOS Safari, overflow:hidden alone does not always stop the rubber-band scroll — you may also need to fix the body position and restore scrollTop. Always save and restore the original overflow value, not assume "auto".

function useScrollLock(locked: boolean) {
  useLayoutEffect(() => {
    if (!locked) return;
    const root = document.documentElement;
    const prev = root.style.overflow;
    root.style.overflow = 'hidden';
    return () => { root.style.overflow = prev; };
  }, [locked]);
}

Support BOTH controlled and uncontrolled usage in one component. Uses props.value when provided (controlled), otherwise internal state (uncontrolled), and calls onChange either way.

⚠ Common pitfall: Switching a component between controlled and uncontrolled across renders (value going from undefined to a value) warns and resets — decide the mode once at mount via whether value is initially defined.

function useControllableState<T>({ value, defaultValue, onChange }: {
  value?: T; defaultValue?: T; onChange?: (v: T) => void;
}) {
  const isControlled = value !== undefined;
  const [uncontrolled, setUncontrolled] = useState(defaultValue);
  const state = isControlled ? value : uncontrolled;
  const setState = useCallback((next: T) => {
    if (!isControlled) setUncontrolled(next);
    onChange?.(next);
  }, [isControlled, onChange]);
  return [state, setState] as const;
}

Return how many times the component has rendered. A debugging hook that increments a ref every render. Helps spot unexpected re-renders during optimization work.

⚠ Common pitfall: In React 18 StrictMode dev, components render twice on mount, so the count is inflated. Reading it during render and mutating a ref is fine here, but do not depend on its exact value.

function useRenderCount() {
  const count = useRef(0);
  count.current += 1;
  return count.current;
}
const renders = useRenderCount();
console.log('Table rendered', renders, 'times');

State plus an undo/redo history stack. Each set pushes onto the history; undo / redo move a pointer through it. The pointer model keeps redo available until a new value branches the timeline.

⚠ Common pitfall: Setting a new value while the pointer is in the middle of history must TRUNCATE the redo tail — otherwise redo replays a branch the user already abandoned. Cap the stack length to avoid memory growth.

function useStateWithHistory<T>(initial: T) {
  const [history, setHistory] = useState<T[]>([initial]);
  const [ptr, setPtr] = useState(0);
  const set = useCallback((value: T) => {
    setHistory(h => [...h.slice(0, ptr + 1), value]);
    setPtr(p => p + 1);
  }, [ptr]);
  const undo = useCallback(() => setPtr(p => Math.max(0, p - 1)), []);
  const redo = useCallback(() => setPtr(p => Math.min(history.length - 1, p + 1)), [history.length]);
  return [history[ptr], set, {
    undo, redo, canUndo: ptr > 0, canRedo: ptr < history.length - 1,
  }] as const;
}

Run a handler when a specific key is pressed on the window. Matches against KeyboardEvent.key (e.g. "Escape", "Enter", "k"). Refs the handler so it always sees fresh state.

⚠ Common pitfall: Match on event.key, not event.keyCode (deprecated). "Escape" is the key value, not "Esc". Without a handler ref, every render re-subscribes the listener.

function useKeyPress(targetKey: string, handler: (e: KeyboardEvent) => void) {
  const ref = useRef(handler);
  useEffect(() => { ref.current = handler; }, [handler]);
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if (e.key === targetKey) ref.current(e);
    };
    window.addEventListener('keydown', onKey);
    return () => window.removeEventListener('keydown', onKey);
  }, [targetKey]);
}
useKeyPress('Escape', () => setOpen(false));

Debounce a CALLBACK (not a value): returns a stable function that delays invoking fn until delayMs of quiet. Each call resets the timer; the latest arguments win. Cancels on unmount.

⚠ Common pitfall: Returning a new function each render breaks debouncing — the timer lives in a ref and the returned function must be stable. Always clear the pending timer in cleanup or rapid unmounts leak timers.

function useDebouncedCallback<A extends any[]>(fn: (...a: A) => void, delay = 300) {
  const fnRef = useRef(fn);
  useEffect(() => { fnRef.current = fn; }, [fn]);
  const timer = useRef<ReturnType<typeof setTimeout>>();
  useEffect(() => () => clearTimeout(timer.current), []);
  return useCallback((...args: A) => {
    clearTimeout(timer.current);
    timer.current = setTimeout(() => fnRef.current(...args), delay);
  }, [delay]);
}
const save = useDebouncedCallback((draft: Draft) => api.save(draft), 800);

Swap the page favicon at runtime by updating (or creating) the <link rel="icon"> element. A small effect-driven sync to the document head, like useDocumentTitle but for the icon.

⚠ Common pitfall: Creating a new <link> each call piles up duplicate icon links. Query for the existing rel="icon" link first and reuse it; only create one if none exists.

function useFavicon(href: string) {
  useEffect(() => {
    let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
    if (!link) {
      link = document.createElement('link');
      link.rel = 'icon';
      document.head.appendChild(link);
    }
    link.href = href;
  }, [href]);
}
useFavicon(unread > 0 ? '/favicon-alert.ico' : '/favicon.ico');