React Hooks in 2026: Not Just What They Do — When to Reach for Each One

// useState is correct here:
// The count changes. Nothing else in the component needs to respond to that change.
// It's truly independent.

function LikeButton({ postId }: { postId: string }) {
  const [isLiked, setIsLiked] = useState(false);
  const [likeCount, setLikeCount] = useState(0);

  const handleLike = async () => {
    // Functional update form — non-negotiable when new state depends on previous
    // Without this, rapid clicks create stale closure bugs:
    // you click twice fast, both callbacks read isLiked = false,
    // both set it to true — the second click doesn't unlike
    setIsLiked(prev => !prev);
    setLikeCount(prev => prev + (isLiked ? -1 : 1));
    await toggleLike(postId);
  };

  return (
    <button onClick={handleLike}>
      {isLiked ? '❤️' : '🤍'} {likeCount}
    </button>
  );
}

// 🚩 The smell: multiple useState calls that always change together
// If you find yourself writing this, you're managing a state machine manually

function MultiStepForm() {
  const [step, setStep] = useState(1);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [formData, setFormData] = useState<FormData>({});
  const [isValid, setIsValid] = useState(false);

  // Now every handler needs to coordinate all five of these.
  // Welcome to the coordination tax.
  const handleNext = () => {
    // Validate current step
    const newErrors = validateStep(step, formData);
    setErrors(newErrors);
    setIsValid(Object.keys(newErrors).length === 0);
    if (Object.keys(newErrors).length === 0) {
      setStep(prev => prev + 1);
    }
  };
  // This is already fragile and we haven't written the submit handler yet.
}

// Six steps of state. Now it's one reducer.
// Every possible state transition is named and explicit.

type FormStep = 1 | 2 | 3 | 4 | 5 | 6;

interface FormState {
  currentStep: FormStep;
  data: Partial<FormData>;
  errors: Record<string, string>;
  isSubmitting: boolean;
  isComplete: boolean;
}

type FormAction =
  | { type: 'NEXT_STEP'; payload: { stepData: Partial<FormData>; errors: Record<string, string> } }
  | { type: 'PREV_STEP' }
  | { type: 'UPDATE_FIELD'; payload: { field: string; value: unknown } }
  | { type: 'SUBMIT_START' }
  | { type: 'SUBMIT_SUCCESS' }
  | { type: 'SUBMIT_ERROR'; payload: string };

const initialFormState: FormState = {
  currentStep: 1,
  data: {},
  errors: {},
  isSubmitting: false,
  isComplete: false,
};

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case 'NEXT_STEP': {
      // State transition is explicit: you can only go to next step if no errors
      const hasErrors = Object.keys(action.payload.errors).length > 0;
      if (hasErrors) {
        return { ...state, errors: action.payload.errors };
      }
      return {
        ...state,
        currentStep: Math.min(6, state.currentStep + 1) as FormStep,
        data: { ...state.data, ...action.payload.stepData },
        errors: {},
      };
    }

    case 'PREV_STEP':
      return {
        ...state,
        currentStep: Math.max(1, state.currentStep - 1) as FormStep,
        errors: {}, // Clear errors when going back — intentional UX decision
      };

    case 'UPDATE_FIELD':
      return {
        ...state,
        data: { ...state.data, [action.payload.field]: action.payload.value },
        // Clear the error for this field as the user types — live validation
        errors: { ...state.errors, [action.payload.field]: '' },
      };

    case 'SUBMIT_START':
      return { ...state, isSubmitting: true, errors: {} };

    case 'SUBMIT_SUCCESS':
      return { ...state, isSubmitting: false, isComplete: true };

    case 'SUBMIT_ERROR':
      return {
        ...state,
        isSubmitting: false,
        // Show a general error at the current step
        errors: { form: action.payload },
      };

    default:
      return state;
  }
}

// The component is now clean.
// All the coordination logic is in the reducer — testable in isolation.
function MultiStepForm() {
  const [state, dispatch] = useReducer(formReducer, initialFormState);

  const handleNext = () => {
    const stepData = getCurrentStepData(state.currentStep, state.data);
    const errors = validateStep(state.currentStep, stepData);
    dispatch({ type: 'NEXT_STEP', payload: { stepData, errors } });
  };

  return (
    <div>
      <StepIndicator current={state.currentStep} total={6} />
      <StepContent
        step={state.currentStep}
        data={state.data}
        errors={state.errors}
        onFieldChange={(field, value) =>
          dispatch({ type: 'UPDATE_FIELD', payload: { field, value } })
        }
      />
      <FormNavigation
        onNext={handleNext}
        onBack={() => dispatch({ type: 'PREV_STEP' })}
        isSubmitting={state.isSubmitting}
        currentStep={state.currentStep}
        totalSteps={6}
      />
    </div>
  );
}

// Test the reducer in isolation — no React, no render, no DOM
describe('formReducer', () => {
  it('does not advance to next step when errors exist', () => {
    const state = formReducer(initialFormState, {
      type: 'NEXT_STEP',
      payload: {
        stepData: {},
        errors: { name: 'Name is required' },
      },
    });

    expect(state.currentStep).toBe(1); // Stayed on step 1
    expect(state.errors.name).toBe('Name is required');
  });

  it('clears errors when going back', () => {
    const stateWithErrors: FormState = {
      ...initialFormState,
      currentStep: 2,
      errors: { email: 'Invalid email' },
    };

    const state = formReducer(stateWithErrors, { type: 'PREV_STEP' });
    expect(state.errors).toEqual({});
    expect(state.currentStep).toBe(1);
  });
});

// 🚩 The most common useEffect mistake: using it for derived state
function UserGreeting({ user }: { user: User }) {
  const [greeting, setGreeting] = useState('');

  // Wrong: This is not synchronization. It's computation.
  // Every render: compute greeting → trigger re-render → compute greeting again
  // That's a render cycle for zero reason.
  useEffect(() => {
    setGreeting(`Hello, ${user.name.split(' ')[0]}!`);
  }, [user.name]);

  return <h1>{greeting}</h1>;
}

// ✅ Correct: Compute inline. No useEffect needed.
function UserGreeting({ user }: { user: User }) {
  const greeting = `Hello, ${user.name.split(' ')[0]}!`;
  return <h1>{greeting}</h1>;
}

// ✅ useEffect is correct here: synchronizing with an external system (browser API)
function useDocumentTitle(title: string) {
  useEffect(() => {
    const previousTitle = document.title;
    document.title = title;

    // Cleanup: restore the previous title when component unmounts
    // or when title changes. This is the cleanup function doing real work.
    return () => {
      document.title = previousTitle;
    };
  }, [title]);
}

// ✅ useEffect is correct here: subscribing to an external event
function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    // Cleanup: remove listeners when component unmounts.
    // Without this, the handlers remain attached to the window
    // even after the component is gone — a memory leak.
    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []); // Empty array: subscribe once on mount, unsubscribe on unmount

  return isOnline;
}

// Data fetching in useEffect — the complete, production-safe version
function useUserData(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    // AbortController lets us cancel the request if:
    // 1. The component unmounts before the request completes
    // 2. userId changes before the first request completes
    // Without this, a fast userId change causes a race condition:
    // request for user A resolves AFTER request for user B,
    // and you render user A's data for user B's profile.
    const controller = new AbortController();

    const fetchUser = async () => {
      setIsLoading(true);
      setError(null);

      try {
        const response = await fetch(`/api/users/${userId}`, {
          signal: controller.signal, // Link this request to the AbortController
        });

        if (!response.ok) throw new Error('Failed to fetch');

        const data: User = await response.json();
        setUser(data);
      } catch (err) {
        // AbortError is expected and not a real error — the component
        // unmounted or userId changed. Don't show an error for this.
        if (err instanceof Error && err.name === 'AbortError') return;
        setError(err instanceof Error ? err.message : 'Unknown error');
      } finally {
        setIsLoading(false);
      }
    };

    fetchUser();

    // Cleanup: abort the in-flight request
    return () => controller.abort();
  }, [userId]);

  return { user, isLoading, error };
}

// ✅ Good useContext usage: theme changes rarely, needed everywhere
// ThemeContext.tsx

type Theme = 'light' | 'dark';

interface ThemeContextValue {
  theme: Theme;
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    // Initialize from localStorage — the inline script handles first paint
    try {
      return (localStorage.getItem('theme') as Theme) ?? 'light';
    } catch {
      return 'light';
    }
  });

  const toggleTheme = useCallback(() => {
    setTheme(prev => {
      const next = prev === 'light' ? 'dark' : 'light';
      try { localStorage.setItem('theme', next); } catch {}
      document.documentElement.setAttribute('data-theme', next);
      return next;
    });
  }, []);

  // Memoize the context value to prevent unnecessary re-renders of all consumers
  // when the ThemeProvider's parent re-renders but theme hasn't changed
  const value = useMemo(() => ({ theme, toggleTheme }), [theme, toggleTheme]);

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

// Always wrap useContext in a custom hook — two reasons:
// 1. Throws a clear error if used outside the provider (beats a cryptic undefined error)
// 2. Hides the Context implementation — consumers don't need to import ThemeContext
export function useTheme() {
  const context = useContext(ThemeContext);
  if (!context) throw new Error('useTheme must be used within ThemeProvider');
  return context;
}

// 🚩 useContext performance trap: high-frequency updates in context
// This causes EVERY consumer to re-render on every keystroke

const SearchContext = createContext<{ query: string; setQuery: (q: string) => void } | null>(null);

function SearchProvider({ children }: { children: ReactNode }) {
  const [query, setQuery] = useState('');
  // Every time query changes (every keystroke), ALL consumers re-render.
  // If there are 20 components consuming SearchContext, that's 20 re-renders per keystroke.
  return (
    <SearchContext.Provider value={{ query, setQuery }}>
      {children}
    </SearchContext.Provider>
  );
}

// ✅ Better: keep high-frequency state local, pass callbacks up deliberately
// Or use a state management library (Zustand) that supports selective subscriptions

// 🚩 useCallback that helps nothing
function ParentComponent() {
  const [count, setCount] = useState(0);

  // This function is memoized — but Child is not wrapped in React.memo.
  // React.memo is what makes stable references matter.
  // Without it, Child re-renders whenever Parent re-renders regardless.
  // You're paying the memoization cost for zero benefit.
  const handleClick = useCallback(() => {
    console.log('clicked', count);
  }, [count]);

  return <Child onClick={handleClick} />; // Child is NOT React.memo
}

// ✅ useCallback that earns its place
const Child = React.memo(({ onClick }: { onClick: () => void }) => {
  // React.memo: only re-render if props change reference.
  // Now the stable reference from useCallback actually prevents re-renders.
  console.log('Child rendered');
  return <button onClick={onClick}>Click</button>;
});

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [unrelated, setUnrelated] = useState(0);

  // useCallback is justified here:
  // - Child is wrapped in React.memo
  // - stable reference → Child doesn't re-render when `unrelated` changes
  const handleClick = useCallback(() => {
    console.log('clicked', count);
  }, [count]);

  return (
    <div>
      <button onClick={() => setUnrelated(u => u + 1)}>
        Change unrelated ({unrelated})
      </button>
      <Child onClick={handleClick} />
      {/* Child does NOT re-render when unrelated changes */}
    </div>
  );
}

// useMemo: the right use case
function ProductList({ products, filters }: { products: Product[]; filters: Filters }) {
  // Filtering 10,000 products on every render is expensive.
  // useMemo ensures this only runs when products or filters actually change.
  const filteredProducts = useMemo(() => {
    return products
      .filter(p => !filters.category || p.category === filters.category)
      .filter(p => p.price >= filters.minPrice && p.price <= filters.maxPrice)
      .sort((a, b) => {
        if (filters.sortBy === 'price') return a.price - b.price;
        return a.name.localeCompare(b.name);
      });
  }, [products, filters]); // Only recalculate when these change

  return (
    <div>
      {filteredProducts.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

// Use case 1: DOM access
function VideoPlayer({ src }: { src: string }) {
  const videoRef = useRef<HTMLVideoElement>(null);

  const handlePlay = () => {
    // Direct DOM access — can't be done with state
    videoRef.current?.play();
  };

  const handlePause = () => {
    videoRef.current?.pause();
  };

  return (
    <div>
      <video ref={videoRef} src={src} />
      <button onClick={handlePlay}>Play</button>
      <button onClick={handlePause}>Pause</button>
    </div>
  );
}

// Use case 2: Storing a mutable value without re-render
function useInterval(callback: () => void, delay: number) {
  const savedCallback = useRef(callback);

  // Keep the ref up to date without causing re-renders
  useEffect(() => {
    savedCallback.current = callback;
  }, [callback]);

  useEffect(() => {
    const id = setInterval(() => savedCallback.current(), delay);
    // Cleanup: clear the interval when the component unmounts or delay changes
    return () => clearInterval(id);
  }, [delay]);
}

// Use case 3: Tracking previous values
function usePreview<T>(value: T): T | undefined {
  const ref = useRef<T>();

  useEffect(() => {
    ref.current = value; // Store current value after render
  });

  return ref.current; // Return the value from the PREVIOUS render
}

// Without useTransition: typing in the search input feels laggy
// because every keystroke triggers an expensive filter of 50,000 items
// and the browser hangs until it's done.

// With useTransition: typing is instant. The results update a moment later.
// The user sees smooth input. The results follow. That's the right UX.

function ProductSearch({ products }: { products: Product[] }) {
  const [inputValue, setInputValue] = useState('');
  const [searchQuery, setSearchQuery] = useState('');
  const [isPending, startTransition] = useTransition();

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    // This update is instant — input stays responsive
    setInputValue(e.target.value);

    // This update is a transition — React can deprioritize it
    // if there are more urgent updates (like the next keystroke)
    startTransition(() => {
      setSearchQuery(e.target.value);
    });
  };

  // This expensive computation only runs when searchQuery changes
  // (which is deferred), not when inputValue changes (which is instant)
  const results = useMemo(() => {
    if (!searchQuery) return products;
    return products.filter(p =>
      p.name.toLowerCase().includes(searchQuery.toLowerCase()) ||
      p.description.toLowerCase().includes(searchQuery.toLowerCase())
    );
  }, [products, searchQuery]);

  return (
    <div>
      <input
        value={inputValue}
        onChange={handleChange}
        placeholder="Search products..."
      />
      {/* isPending = the deferred update is still computing */}
      {/* Don't use a full loading spinner here — it's jarring for fast transitions */}
      {/* A subtle opacity change communicates "updating" without disrupting the user */}
      <div style={{ opacity: isPending ? 0.6 : 1, transition: 'opacity 0.1s' }}>
        <p>{results.length} results</p>
        {results.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </div>
  );
}

// useDeferredValue: when you receive a value from outside and can't control when it changes
function SearchResults({ query }: { query: string }) {
  // query comes from a parent — we don't control when it changes.
  // useDeferredValue gives us a version of query that React will
  // deprioritize updating, keeping the parent's UI responsive.
  const deferredQuery = useDeferredValue(query);

  const results = useMemo(() => expensiveSearch(deferredQuery), [deferredQuery]);

  // isStale = the deferred value hasn't caught up to the real value yet
  const isStale = query !== deferredQuery;

  return (
    <div style={{ opacity: isStale ? 0.7 : 1 }}>
      {results.map(r => <SearchResult key={r.id} result={r} />)}
    </div>
  );
}

// A like button that feels instant — because it is

interface Post {
  id: string;
  content: string;
  likeCount: number;
  isLikedByUser: boolean;
}

async function toggleLikeApi(postId: string, currentlyLiked: boolean): Promise<void> {
  const response = await fetch(`/api/posts/${postId}/like`, {
    method: currentlyLiked ? 'DELETE' : 'POST',
  });
  if (!response.ok) throw new Error('Failed to toggle like');
}

function LikeButton({ post }: { post: Post }) {
  const [actualPost, setActualPost] = useState(post);

  // useOptimistic takes:
  // 1. The actual state (what the server knows)
  // 2. A function to compute the optimistic state (what we show immediately)
  const [optimisticPost, setOptimisticLike] = useOptimistic(
    actualPost,
    (currentPost, isLiking: boolean) => ({
      ...currentPost,
      isLikedByUser: isLiking,
      likeCount: currentPost.likeCount + (isLiking ? 1 : -1),
    })
  );

  const handleLike = async () => {
    const isCurrentlyLiked = optimisticPost.isLikedByUser;

    // Step 1: Show the result immediately in the UI
    setOptimisticLike(!isCurrentlyLiked);

    try {
      // Step 2: Tell the server
      await toggleLikeApi(post.id, isCurrentlyLiked);

      // Step 3: Update the actual state to match
      setActualPost(prev => ({
        ...prev,
        isLikedByUser: !isCurrentlyLiked,
        likeCount: prev.likeCount + (isCurrentlyLiked ? -1 : 1),
      }));
    } catch {
      // Step 4 (on failure): useOptimistic automatically reverts to actualPost
      // The UI snaps back to the actual state. User sees a brief flash of the revert.
      // Show a toast notification explaining the failure.
      console.error('Like failed — UI reverted automatically');
    }
  };

  return (
    <button
      onClick={handleLike}
      aria-label={optimisticPost.isLikedByUser ? 'Unlike post' : 'Like post'}
    >
      {optimisticPost.isLikedByUser ? '❤️' : '🤍'} {optimisticPost.likeCount}
    </button>
  );
}

// usePostActions.ts
// Encapsulates all the logic for interacting with a post.
// The component that uses this doesn't know about API calls,
// optimistic state, error handling, or state management.
// It just calls functions and reads state.

interface UsePostActionsReturn {
  post: Post;
  handleLike: () => Promise<void>;
  handleBookmark: () => Promise<void>;
  isLiking: boolean;
  isBookmarking: boolean;
}

export function usePostActions(initialPost: Post): UsePostActionsReturn {
  const [actualPost, setActualPost] = useState(initialPost);
  const [isLiking, setIsLiking] = useState(false);
  const [isBookmarking, setIsBookmarking] = useState(false);

  const [optimisticPost, applyOptimistic] = useOptimistic(
    actualPost,
    (post, action: { type: 'like' | 'bookmark'; value: boolean }) => {
      if (action.type === 'like') {
        return {
          ...post,
          isLikedByUser: action.value,
          likeCount: post.likeCount + (action.value ? 1 : -1),
        };
      }
      return { ...post, isBookmarkedByUser: action.value };
    }
  );

  const handleLike = async () => {
    const newValue = !optimisticPost.isLikedByUser;
    setIsLiking(true);
    applyOptimistic({ type: 'like', value: newValue });
    try {
      await toggleLikeApi(initialPost.id, !newValue);
      setActualPost(prev => ({
        ...prev,
        isLikedByUser: newValue,
        likeCount: prev.likeCount + (newValue ? 1 : -1),
      }));
    } catch {
      // Optimistic state reverts automatically
    } finally {
      setIsLiking(false);
    }
  };

  const handleBookmark = async () => {
    const newValue = !optimisticPost.isBookmarkedByUser;
    setIsBookmarking(true);
    applyOptimistic({ type: 'bookmark', value: newValue });
    try {
      await toggleBookmarkApi(initialPost.id, !newValue);
      setActualPost(prev => ({ ...prev, isBookmarkedByUser: newValue }));
    } catch {
      // Optimistic state reverts automatically
    } finally {
      setIsBookmarking(false);
    }
  };

  return {
    post: optimisticPost,
    handleLike,
    handleBookmark,
    isLiking,
    isBookmarking,
  };
}

// The component is now trivially simple.
// All complexity is in the hook — testable without mounting a component.
function PostCard({ post }: { post: Post }) {
  const { post: postState, handleLike, handleBookmark } = usePostActions(post);

  return (
    <article>
      <p>{postState.content}</p>
      <button onClick={handleLike}>
        {postState.isLikedByUser ? '❤️' : '🤍'} {postState.likeCount}
      </button>
      <button onClick={handleBookmark}>
        {postState.isBookmarkedByUser ? '🔖' : '📄'}
      </button>
    </article>
  );
}