React Hooks Best Practices

This skill provides guidance for writing clean, efficient React hooks code with emphasis on eliminating unnecessary hooks and following established best practices.

Core Philosophy: Less Is More

The primary principle is to use hooks only when necessary. Many React applications suffer from hook overuse, particularly:

• useEffect for logic that should be in event handlers
• useMemo/useCallback for cheap computations
• useState for derived state

Before adding any hook, ask: "Can this be done without a hook?"

Mandatory Rules

1. Linter Compliance is Non-Negotiable

Never suppress react-hooks/exhaustive-deps warnings. The ESLint plugin understands React's rules better than manual reasoning. If a warning appears:

• Add missing dependencies
• Use functional updates to remove dependencies
• Restructure code to eliminate the need
• Never use // eslint-disable-next-line

2. Constants at Module Level, Not in Hooks

Never use useMemo for constant values. Define unchanging values at module scope:

// ❌ WRONG: useMemo for constants
function Component() {
  const options = useMemo(
    () => [
      { value: "a", label: "Option A" },
      { value: "b", label: "Option B" },
    ],
    [],
  );
}

// ✅ CORRECT: Module-level constants
const OPTIONS = [
  { value: "a", label: "Option A" },
  { value: "b", label: "Option B" },
] as const;

function Component() {
  // Just use OPTIONS directly
}

3. Custom Hook Returns Must Be Stable

All values returned from custom hooks must have stable references:

// ❌ WRONG: Unstable return values
function useData(id: string) {
  const [data, setData] = useState(null);
  return {
    data,
    refresh: () => fetch(id), // New function every render
    meta: { id }, // New object every render
  };
}

// ✅ CORRECT: All returns memoized or stable
function useData(id: string) {
  const [data, setData] = useState(null);

  const refresh = useCallback(() => fetch(id), [id]);
  const meta = useMemo(() => ({ id }), [id]);

  return { data, refresh, meta };
}

4. Prefer Modern Hooks When Available

Use experimental/newer hooks when React version permits:

5. Prefer Suspense for Async Operations

Prefer React Suspense boundaries over manual loading state management:

// ❌ AVOID: Manual loading state in component
function UserProfile({ userId }: Props) {
  const { data, isLoading, error } = useUser(userId);

  if (isLoading) return <Spinner />;
  if (error) return <ErrorDisplay error={error} />;
  return <Profile user={data} />;
}

// ✅ PREFER: Suspense boundary with data hook
function UserProfile({ userId }: Props) {
  const user = useUser(userId); // Suspends until ready
  return <Profile user={user} />;
}

// Parent handles loading/error
<ErrorBoundary fallback={<ErrorDisplay />}>
  <Suspense fallback={<Spinner />}>
    <UserProfile userId={id} />
  </Suspense>
</ErrorBoundary>;

Note: Internal hook implementations may still use { data, error, loading } structures. The preference for Suspense applies to component-level API design.

Quick Decision Framework

When NOT to Use useEffect

When NOT to Use useMemo/useCallback

Essential Patterns

1. Derived State: Calculate, Don't Store

// ❌ Anti-pattern: Storing derived state
const [items, setItems] = useState<Item[]>([]);
const [filteredItems, setFilteredItems] = useState<Item[]>([]);

useEffect(() => {
  setFilteredItems(items.filter((item) => item.active));
}, [items]);

// ✅ Correct: Calculate during render
const [items, setItems] = useState<Item[]>([]);
const filteredItems = items.filter((item) => item.active);

2. Event Responses: Use Handlers, Not Effects

// ❌ Anti-pattern: Effect watching state
const [query, setQuery] = useState("");

useEffect(() => {
  if (query) {
    analytics.track("search", { query });
  }
}, [query]);

// ✅ Correct: Track in event handler
const handleSearch = (newQuery: string) => {
  setQuery(newQuery);
  if (newQuery) {
    analytics.track("search", { query: newQuery });
  }
};

3. Parent-Child Communication

// ❌ Anti-pattern: Effect to notify parent
useEffect(() => {
  onChange(internalValue);
}, [internalValue, onChange]);

// ✅ Correct: Call during event
const handleChange = (value: string) => {
  setInternalValue(value);
  onChange(value);
};

4. Initialization from Props

// ❌ Anti-pattern: Sync props to state
const [value, setValue] = useState(initialValue);

useEffect(() => {
  setValue(initialValue);
}, [initialValue]);

// ✅ Correct: Use key to reset
<Editor key={documentId} initialValue={initialValue} />;

Legitimate useEffect Use Cases

Effects are appropriate for:

1. External system synchronization (DOM manipulation, third-party libraries)
2. Subscriptions (WebSocket, event listeners, observers)
3. Data fetching (when not using a data library)

// ✅ Legitimate: External system sync
useEffect(() => {
  const map = new MapLibrary(mapRef.current);
  map.setCenter(coordinates);

  return () => map.destroy();
}, [coordinates]);

// ✅ Legitimate: Subscription
useEffect(() => {
  const unsubscribe = store.subscribe(handleChange);
  return unsubscribe;
}, []);

Performance Optimization Strategy

Step 1: Measure First

Never optimize without profiling. Use React DevTools Profiler to identify actual bottlenecks.

Step 2: Structural Solutions Before Memoization

Try these before adding useMemo/useCallback:

• Lift state down: Move state closer to where it's used
• Extract components: Isolate frequently updating parts
• Use children prop: Pass static JSX as children

Step 3: Memoize Strategically

When memoization is needed:

// Memoize expensive computations
const sortedData = useMemo(
  () => data.toSorted((a, b) => complexSort(a, b)),
  [data],
);

// Memoize callbacks for optimized children
const handleClick = useCallback(
  (id: string) => dispatch({ type: "SELECT", id }),
  [dispatch],
);

// Combine with React.memo for child optimization
const MemoizedChild = memo(function Child({ onClick }: Props) {
  return <button onClick={onClick}>Click</button>;
});

Custom Hook Design Principles

Single Responsibility

Each custom hook should do one thing well:

// ✅ Focused hooks
function useLocalStorage<T>(key: string, initial: T) {
  /* ... */
}
function useDebounce<T>(value: T, delay: number) {
  /* ... */
}
function useMediaQuery(query: string) {
  /* ... */
}

Return Type Patterns

Composition Over Complexity

Build complex behavior from simple hooks:

function useSearchWithDebounce(initialQuery: string) {
  const [query, setQuery] = useState(initialQuery);
  const debouncedQuery = useDebounce(query, 300);
  const results = useSearch(debouncedQuery);

  return { query, setQuery, results };
}

Common Mistakes at a Glance

Code Review Checklist

When reviewing React hooks code, verify:

Mandatory (Zero Tolerance)

• No ESLint exhaustive-deps warnings suppressed
• No useMemo for constant values (use module-level)
• All custom hook returns are stable (memoized or primitives)

Anti-Patterns

• No useEffect for derived state calculations
• No useEffect for event response logic
• No useState for values computable from other state/props
• No useMemo/useCallback without proven performance need

Quality

• Dependencies arrays are complete and accurate
• Custom hooks follow single responsibility principle
• Cleanup functions provided where needed
• Modern hooks used where React version permits

Additional Resources

Reference Files

For detailed guidance and examples, consult:

• references/unnecessary-hooks.md - Comprehensive patterns for eliminating unnecessary hooks with before/after examples
• references/custom-hooks.md - Advanced custom hook design patterns and composition strategies
• references/dependency-array.md - Deep dive into dependency array management and common pitfalls

Example Files

Working examples in examples/:

• good-patterns.tsx - Correct hook usage examples
• anti-patterns.tsx - Common mistakes with corrections

Summary

The goal is writing React code that is:

1. Minimal: Use hooks only when necessary
2. Direct: Prefer event handlers over effects
3. Calculated: Derive values during render when possible
4. Measured: Optimize based on profiling, not assumptions

Apply the principle: "The best hook is the one you don't need to write."