When designing what a custom React hook returns, when should you return an array (a tuple, the way useState does) and when should you return an object?

## The two shapes and what they optimise for A custom hook's return value is its public API, and there are really only three shapes: a single value, a positional tuple, or a named object. Each optimises for something different. **Tuple — optimises for renaming.** `const [count, setCount] = useState(0)` works because array destructuring binds by position, so every call site chooses its own names for free. That matters enormously for a hook you call several times in one component: `[name, setName]` and `[email, setEmail]` coexist with no ceremony. The price is that position is the contract. Add a third element in the middle and every caller silently reads the wrong thing; skip an element and you write the awkward `const [, setValue] = …`. **Object — optimises for names and growth.** `const { data, error, refetch } = useOrders()` documents itself, lets each caller destructure only what it uses, and can gain a fourth field tomorrow without touching a single call site, because destructuring ignores properties it does not name. The price is renaming friction (`const { data: orders } = …`) and, when two instances are used in one component, the need to rename at every call site. **Single value.** If a hook has exactly one thing to give — a context value, a media-query boolean — return it bare. Wrapping one value in an object or a one-element array is pure noise. ## A practical rule Use a tuple when *all* of these hold: there are at most two or three values; their order is obvious and canonical (state first, updater second); callers will routinely rename them; and the set will not grow. Otherwise use an object. "Will not grow" is the clause people underestimate — most hooks that start as `[data, refetch]` end up wanting `isLoading` and `error`, and by then the tuple is a liability. React's own surface follows exactly this split: `useState` and `useActionState` return tuples; `useFormStatus` returns an object. ```typescript export function useCounter(initial = 0) { const [count, setCount] = useState(initial); const increment = useCallback(() => setCount((c) => c + 1), []); return [count, increment] as const; // renamable pair } ``` The `as const` is not cosmetic. Without it TypeScript infers `(number | (() => void))[]` — an array of a union — and destructuring gives you useless types. With it you get a fixed two-element tuple with the right type per position. The alternative is an explicit return type annotation such as `[number, () => void]`. ## Design decisions that outrank the shape The shape question is easy; these matter more: **Return values, not instructions.** A hook should hand back what the component renders and the functions it calls, not internal machinery. Exposing raw setters plus derived flags plus refs invites callers to depend on details you wanted to keep changeable. **Do not return what the caller can compute.** `items` and `itemCount` and `isEmpty` triple the surface for no gain; the caller writes `items.length === 0`. Return derived fields only where the derivation is non-obvious or genuinely expensive. **Be deliberate about function identity.** Callbacks in the return value end up in dependency arrays and memo comparisons downstream, so decide which of them are stable across renders and say so in the hook's documentation. **Object identity churns by default.** Returning a fresh object literal every render is normally fine, because callers destructure it immediately and never compare it. It only matters if a caller passes the whole returned object down as a prop to a memoized child — then wrap the return value in `useMemo`, or better, tell callers to pass the individual fields. **Arguments deserve the same care.** A hook taking four positional parameters is as fragile as a four-element tuple return; take one options object instead, and treat a growing pile of boolean flags as evidence that two different hooks are hiding inside one. ## The answer to give Say that the shape follows the call-site ergonomics: tuple for a small renamable pair whose order is canonical, object for anything named, optional or growable, bare value when there is only one. Then show the judgement — name React's own examples, mention `as const` for TypeScript tuples, and note that the harder API questions are which values to expose at all and which callbacks are identity-stable.