react-hooks

React Hooks Best Practices

Overview

Guidelines for writing custom hooks, choosing the right hook, and avoiding common pitfalls. Optimized for React 19 + biome useExhaustiveDependencies.

When to Use

• Creating or modifying custom hooks
• Deciding whether to use useEffect, useMemo, useCallback
• Debugging stale closures, infinite loops, or unnecessary re-renders
• Fixing biome/eslint exhaustive-deps warnings

---

Custom Hook Design

When to Extract a Custom Hook

Rule: only extract when there is actual duplication. Two or more components must share the same stateful logic before a hook is worth creating. A single consumer → keep the logic inline. Extracting a hook "for organization" with only one caller is over-engineering.

// Good: reusable across components
function useDebounce<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return debounced;
}

Naming & Return Values

• Always prefix with use
• Return object for 3+ values, tuple for 1-2 values
• Return stable references: actions via useCallback, derived data via useMemo

// Tuple for simple hooks
function useToggle(initial = false): [boolean, () => void] { ... }

// Object for complex hooks
function useChat(socket: TypedSocket) {
  return { sendMessage, abort, createSession };
}

Composition Over Complexity

Build complex hooks by composing simpler ones. Each hook should have a single responsibility.

// Good: composed
function useChatPanel(socket: TypedSocket) {
  const chat = useChat(socket);
  const store = useChannel((s) => ({ messages: s.messages, status: s.status }));
  return { ...chat, ...store };
}

---

You Might Not Need an Effect

Most useEffect calls fall into two categories — only one needs useEffect.

Don't Need useEffect

Pattern	Instead
Transform data for render	Compute during render (const x = derive(props))
Cache expensive computation	useMemo(() => compute(deps), [deps])
Reset state when prop changes	Use key prop on component
Respond to user event	Handle in event handler directly
POST on form submit	Handle in onSubmit, not in effect
Initialize app once	Module-level code or useRef guard