import { useMemo, useCallback, useState } from 'react';

interface DataProcessorProps {
  items: Item[];
  onProcess: (id: string) => void;
}

const DataProcessor = React.memo(({ items, onProcess }: DataProcessorProps) => {
  // Component logic
});

export const ParentComponent = () => {
  const [filter, setFilter] = useState('');
  
  // Memoize derived state to prevent recalculation on unrelated renders
  const filteredItems = useMemo(() => {
    return items.filter(item => item.name.includes(filter));
  }, [items, filter]);

  // Stabilize callback reference
  const handleProcess = useCallback((id: string) => {
    console.log('Processing:', id);
    // Logic
  }, []);

  return <DataProcessor items={filteredItems} onProcess={handleProcess} />;
};

// TypeScript generic support for React.memo
const HeavyChart = React.memo<{ data: Dataset; config: ChartConfig }>(
  ({ data, config }) => {
    // Expensive SVG/Canvas rendering
    return <svg>{/* ... */}</svg>;
  },
  // Custom comparator for non-primitive props
  (prev, next) => {
    // Shallow check first
    if (prev.data === next.data && prev.config === next.config) return true;
    // Fallback to structural equality only if necessa

ry return isEqual(prev.config, next.config); } );

### 3. State Colocation and Splitting

Memoization fails when parent state changes force child re-renders despite stable props. Split state to minimize the scope of updates.

**Anti-Pattern:**
```typescript
// Parent holds all state; child re-renders on any change
const [user, setUser] = useState<User>(initialUser);
const [theme, setTheme] = useState<Theme>('light');
// UserProfile re-renders when theme changes

Solution:

// Colocate state or use context with selectors
const UserProfile = () => {
  const [user, setUser] = useState<User>(initialUser);
  // Theme accessed via context; component only re-renders if user changes
  return <div>{user.name}</div>;
};

4. Architecture Decision: The Memoization Boundary Strategy

Adopt a boundary-based approach rather than granular hook usage. Identify "heavy" subtrees and wrap them at the entry point. Ensure props passed across the boundary are memoized in the parent.

• Boundary: React.memo wrapper around a list or chart component.
• Feed: useMemo for data transformation, useCallback for event handlers.
• Result: The boundary prevents re-renders of the entire subtree when parent state unrelated to the boundary changes.

Pitfall Guide

1. The Memoization Tax

Mistake: Wrapping every component in React.memo or using useMemo for trivial calculations. Explanation: Memoization adds overhead. If a component renders in 0.5ms, the cost of dependency comparison and cache management may be 0.2ms. You save 0.5ms but spend 0.2ms checking, resulting in a net loss when the component actually needs to update. Best Practice: Profile first. Only memoize components where render time > 2ms or where re-renders are frequent and unnecessary.

2. Missing Dependencies

Mistake: Omitting variables from dependency arrays to prevent re-computation. Explanation: This causes stale closures and renders. The hook returns cached values based on outdated state. Best Practice: Use ESLint react-hooks/exhaustive-deps. If dependencies change too frequently, refactor the logic or use refs for mutable values that shouldn't trigger re-renders.

3. Object Literal Prop Leakage

Mistake: Passing new objects or arrays inline to memoized children.

<Child style={{ color: 'red' }} /> // New object every render
<Child items={[1, 2, 3]} /> // New array every render

Explanation: React.memo performs a shallow comparison. New references always fail, rendering the memoization useless. Best Practice: Extract constants outside the component or use useMemo for inline objects/arrays.

4. Custom Comparator Performance

Mistake: Using deep equality checks (e.g., lodash.isEqual) in React.memo comparators. Explanation: Deep equality traverses the entire object graph. For large objects, this is O(N) and often slower than the render itself. Best Practice: Rely on reference equality. Structure data so that updates produce new references only when data changes. Use immutable update patterns or libraries like Immer to ensure reference stability.

5. useMemo for Side Effects

Mistake: Using useMemo to trigger side effects or API calls. Explanation: useMemo is for computing values. React may discard memoized values in development or under memory pressure. Side effects belong in useEffect. Best Practice: Use useEffect for side effects. Use useMemo strictly for expensive computations.

6. Ignoring State Structure

Mistake: Storing related data in separate state variables that update together. Explanation: Multiple useState calls cause multiple re-renders or require batching. Memoization cannot fix structural inefficiencies. Best Practice: Group related state into a single object or use useReducer for complex state logic to control update granularity.

7. The useCallback Trap with Inline Functions

Mistake: Wrapping a function in useCallback but passing it to a non-memoized child. Explanation: The child component re-renders anyway. The useCallback adds overhead without benefit. Best Practice: Pair useCallback with React.memo children. If the child is not memoized, stabilizing the callback provides no performance gain.

Production Bundle

Action Checklist

• Profile Baseline: Use React DevTools Profiler to record interactions. Identify components with high "wasted time" or high render counts.
• Stabilize Props: Audit components passing objects/arrays/functions inline. Wrap them in useMemo or useCallback or extract constants.
• Apply Boundaries: Wrap heavy subtrees (lists, charts, forms) in React.memo. Verify prop stability.
• Review Comparators: Remove deep equality comparators. Ensure data structures support reference equality.
• Audit Dependencies: Run ESLint checks. Fix missing dependencies in hooks. Refactor logic if dependencies cause excessive updates.
• Test Mobile Performance: Validate frame rates on low-end devices. Memoization benefits are most visible on constrained hardware.
• Measure Bundle Size: Check if memoization patterns increase bundle size. Remove unused utility imports.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Heavy computation in render	useMemo	Caches expensive result; avoids recalculation on every render.	Low CPU, Low Memory
Callback passed to React.memo child	useCallback	Stabilizes reference; prevents child re-render.	Low CPU, Low Memory
Large list rendering	Virtualization + React.memo	Reduces DOM nodes; memoization prevents item re-renders.	High Perf Gain, Med Memory
Simple UI component	No memoization	Render cost is negligible; memoization adds overhead.	None
Frequently changing complex prop	React.memo with reference check	Shallow check fails quickly; allows update when needed.	Low CPU, Low Memory
Static configuration object	Extract constant outside component	Eliminates need for useMemo; reference is stable by default.	Zero Overhead

Configuration Template

Use this pattern for a robust memoization boundary with development-time validation.

import React, { ComponentType, ComponentProps } from 'react';

// Development wrapper to log unnecessary re-renders
const withMemoizationAudit = <T extends ComponentType<any>>(
  WrappedComponent: T,
  componentName: string
) => {
  const MemoizedComponent = React.memo(WrappedComponent, (prev, next) => {
    const shouldUpdate = prev !== next;
    if (shouldUpdate && process.env.NODE_ENV === 'development') {
      // Log props that changed to identify instability
      const changedProps = Object.keys(prev).filter(
        key => prev[key as keyof typeof prev] !== next[key as keyof typeof next]
      );
      if (changedProps.length > 0) {
        console.warn(
          `[Memoization Audit] ${componentName} re-rendered due to: ${changedProps.join(', ')}`
        );
      }
    }
    return !shouldUpdate;
  });

  return MemoizedComponent as T;
};

// Usage
const HeavyTable = ({ data, columns }: TableProps) => {
  return <table>{/* ... */}</table>;
};

export const MemoizedHeavyTable = withMemoizationAudit(HeavyTable, 'HeavyTable');

Quick Start Guide

1. Install React DevTools: Ensure the browser extension is active and the "Highlight updates when components render" feature is enabled.
2. Record Interaction: Open the Profiler tab. Click "Record". Perform the slow interaction (e.g., typing in a search box, scrolling a list). Stop recording.
3. Analyze Flamegraph: Look for bars with high duration. Identify the component causing the bottleneck. Check "Why did this render?" to see if props/state changed.
4. Apply Fix: If the component re-renders due to unstable props, stabilize them in the parent using useMemo or useCallback. If the component itself is heavy, wrap it in React.memo.
5. Verify: Re-record the interaction. Confirm the render count decreased and the duration bar shortened. Repeat for remaining bottlenecks.