Typed custom hooks are a powerful pattern in React, allowing you to encapsulate logic and reuse it across your application. When you create hooks that return complex values—such as objects, arrays, or tuples—typing these return values correctly is crucial for both safety and developer experience. You want consumers of your hook to immediately know what to expect, making your hooks both robust and easy to use.

Consider a hook that returns an object. You might create a hook for toggling boolean state:

function useToggle(initial: boolean) {
  const [value, setValue] = React.useState(initial);
  const toggle = () => setValue(v => !v);
  return { value, toggle };
}

// Typed return value:
type UseToggleReturn = {
  value: boolean;
  toggle: () => void;
};

function useToggleTyped(initial: boolean): UseToggleReturn {
  const [value, setValue] = React.useState(initial);
  const toggle = () => setValue(v => !v);
  return { value, toggle };
}

When your hook returns an array, you can specify the type as an array or a tuple. Arrays are useful for lists of items of the same type, while tuples are ideal when the array has a fixed length and each position has a specific meaning. For example, a hook that returns a value and a setter is best typed as a tuple:

function useCounter(initial: number): [number, () => void] {
  const [count, setCount] = React.useState(initial);
  const increment = () => setCount(c => c + 1);
  return [count, increment];
}

type FetchResult<T> = [T | null, boolean, Error | null];

function useFetch<T>(url: string): FetchResult<T> {
  const [data, setData] = React.useState<T | null>(null);
  const [loading, setLoading] = React.useState(true);
  const [error, setError] = React.useState<Error | null>(null);

  React.useEffect(() => {
    setLoading(true);
    fetch(url)
      .then(res => res.json())
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [url]);

  return [data, loading, error];
}

When documenting your custom hooks, always specify the return type in your TypeScript signature. This makes it clear to consumers what the hook provides. If your hook is generic, define a generic return type. For objects, use interfaces or type aliases for clarity. For tuples, type each position explicitly. Good documentation and explicit return types help TypeScript infer types for consumers, leading to better autocomplete, fewer errors, and a smoother development experience.