Custom Hooks Architecture: Designing Composable State Abstractions in React

Since React 16.8, Hooks have been the cornerstone of state and effect composition in frontend engineering. While React ships with essential built-in primitives like useState, useEffect, and useContext (React documentation), real-world applications quickly accumulate complex logic: browser subscriptions, debounced search filters, media query listeners, and local storage synchronization.

When this logic is inlined directly inside UI components, components quickly become bloated, brittle, and difficult to test. The solution is extracting Custom Hooks (React documentation).

However, building production-grade custom Hooks requires more than just moving code into a separate function. Developers frequently struggle with API design choices: Should a Hook return an array or an object? How do you ensure bulletproof cleanup for subscriptions? How do you compose Hooks while avoiding infinite render loops?

In this guide, we break down custom Hook architecture, design principles for type-safe APIs in TypeScript, and best practices for creating composable state abstractions.

---

1. The Core Philosophy: Sharing Logic, Not State

A foundational mental model for custom Hooks is that custom Hooks share stateful logic, not state itself (React documentation).

// Two components calling the same Hook maintain completely independent state!
function ComponentA() {
  const [value, setValue] = useCounter(); // counter = 0
}

function ComponentB() {
  const [value, setValue] = useCounter(); // counter = 0 (completely separate instance!)
}

Every time a component calls a custom Hook, React allocates a fresh, isolated set of state cells inside that component’s fiber node. Custom Hooks are not global state singletons; they are reusable blueprints for stateful behavior.

---

2. API Design: Tuples vs. Objects Return Signatures

One of the first decisions when authoring a custom Hook is choosing the return signature.

When to Return a Tuple ([state, action])

Return a tuple when the Hook acts like an atomic value primitive (mirroring useState) with 1–2 values. In TypeScript, always mark the array as as const so the tuple preserves exact types rather than a union array:

export function useToggle(initialValue = false): [boolean, () => void] {
  const [state, setState] = useState(initialValue);
  const toggle = useCallback(() => setState(prev => !prev), []);
  return [state, toggle] as const;
}

// Consumer can conveniently rename variables:
const [isModalOpen, toggleModal] = useToggle();
const [isSidebarOpen, toggleSidebar] = useToggle();

When to Return an Object ({ data, error, isLoading })

Return an object when the Hook exposes multiple values, statuses, or helper methods (3 or more items). Objects provide named clarity, allow consumers to destructure only what they need, and allow backward-compatible additions without breaking index positions:

export interface UseAsyncState<T> {
  data: T | null;
  error: Error | null;
  isLoading: boolean;
  execute: () => Promise<void>;
  reset: () => void;
}

---

3. Practical Implementation: A Type-Safe useMediaQuery Hook

Let us look at a practical, production-ready custom Hook: subscribing to CSS media queries in browser environments. This illustrates clean lifecycle management, Server-Side Rendering (SSR) safety, and event listener cleanups:

'use client';

import { useState, useEffect } from 'react';

/**
 * Subscribes to a CSS media query and returns whether it currently matches.
 * SSR-safe: Defaults to false on the server before client hydration.
 */
export function useMediaQuery(query: string): boolean {
  // 1. SSR-safe initial state (avoid window undefined during SSR)
  const [matches, setMatches] = useState<boolean>(() => {
    if (typeof window !== 'undefined') {
      return window.matchMedia(query).matches;
    }
    return false;
  });

  useEffect(() => {
    // 2. Browser guard
    if (typeof window === 'undefined') return;

    const mediaQueryList = window.matchMedia(query);
    setMatches(mediaQueryList.matches);

    // 3. Listener callback
    function handleChange(event: MediaQueryListEvent) {
      setMatches(event.matches);
    }

    // 4. Attach listener
    mediaQueryList.addEventListener('change', handleChange);

    // 5. Strict cleanup to prevent memory leaks on unmount or query change
    return () => {
      mediaQueryList.removeEventListener('change', handleChange);
    };
  }, [query]); // Re-subscribe if the query string changes

  return matches;
}

Consuming the Custom Hook:

export function ResponsiveNavigation() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const prefersDarkMode = useMediaQuery('(prefers-color-scheme: dark)');

  return isMobile ? <MobileDrawer /> : <DesktopNavbar theme={prefersDarkMode ? 'dark' : 'light'} />;
}

The consumer component contains zero browser DOM event code, zero window checks, and zero event listener cleanups. The logic is completely encapsulated behind a clean, declarative boolean.

---

4. Chaining and Composing Custom Hooks

Custom Hooks achieve their true architectural power when composed together. You can pass reactive state returned from one Hook directly into another:

export function useDebouncedSearch(initialQuery = '', delay = 300) {
  // Hook 1: Local input state
  const [query, setQuery] = useState(initialQuery);

  // Hook 2: Debounced value state
  const debouncedQuery = useDebounce(query, delay);

  // Hook 3: Data fetching using the debounced value
  const searchResults = useSearchApi(debouncedQuery);

  return {
    query,
    setQuery,
    debouncedQuery,
    ...searchResults,
  };
}

By chaining smaller, single-responsibility Hooks (useDebounce, useSearchApi), you create high-level feature hooks that remain modular, testable, and reusable across different pages.

---

5. Architectural Anti-Patterns to Avoid

1. Don’t Wrap Every Single useEffect: If an Effect is specific to a single component’s DOM node and will never be reused, inlining it with a clear comment is often clearer than creating a useOneOffFeature Hook.
2. Beware of Unstable Callbacks in Dependency Arrays: When passing callbacks into custom hooks, ensure consumers wrap them in useCallback or adopt useEffectEvent to prevent infinite re-subscription cycles.
3. Always Follow the Rules of Hooks: Custom Hooks must always start with the use prefix, and must never be called inside conditional statements or loops (React documentation).

---

Conclusion

Custom Hooks represent React’s most elegant mechanism for separating stateful business logic from visual presentation. By designing clean return contracts, guaranteeing strict lifecycle cleanups, and composing focused primitives, frontend architectures remain maintainable, testable, and resilient as codebases scale.

---

Sources

• React Learn: Reusing Logic with Custom Hooks
• React Reference: Rules of Hooks
• React Reference: Built-in React Hooks
• React Reference: useEffect