Composition patterns: compound components over boolean props

The configuration–composition spectrum

Every component API sits on a spectrum. At one end, configuration: the caller passes props, the component owns all structure. At the other, composition: the caller passes JSX, the component owns only the frame around it. Configuration is closed and enumerable — variant="primary" | "ghost" | "danger" is a typed, finite contract you can exhaustively test and document. Composition is open — children admits anything, which is exactly the point.

The failure mode of configuration is the boolean-prop explosion. Each is*/has* boolean doubles the component’s state space: 9 booleans means 2⁹ = 512 combinations, and the interactions between them (loading × iconOnly, quiet × destructive) are real render states your tests almost certainly skip. Worse, boolean props are a one-way street: removing one is a breaking change across every consumer, so the matrix only grows. The reliable smell is a prop that describes contents rather than behavior — leftIcon, subtitle, footerActions, loadingText. Contents belong to the caller; the moment you find yourself adding a prop to inject markup, the API wants children or a slot:

// Year three of the Button. Every prop was someone's deadline.
<Button
  variant="primary" size="md" loading loadingText="Saving…"
  leftIcon={<SaveIcon />} fullWidth uppercase tooltip="Save the draft"
/>

// Composition: the same needs, zero new Button props.
<Button variant="primary" size="md" disabled={saving}>
  {saving ? <Spinner label="Saving…" /> : <SaveIcon />}
  Save draft
</Button>

The rule senior reviewers apply: enumerable, constrained variation stays a prop (it is a design decision the system owns — variant, size, tone); arbitrary structure becomes children or slots (it is the caller’s content, and the system should not enumerate it).

Compound components: a context-wired family

When several parts must share state — Tabs and its triggers and panels, Select and its options, Accordion and its items — the composition answer is a compound component: a family of components that communicate through an implicit React context, so the caller composes the parts freely while the family coordinates behind the scenes. The shape every serious system converges on:

const TabsCtx = createContext<TabsContextValue | null>(null);

function useTabs(part: string) {
  const ctx = useContext(TabsCtx);
  if (ctx === null) {
    // Fail loudly at development time, at the exact misuse site.
    throw new Error(part + " must be rendered inside <Tabs>");
  }
  return ctx;
}

export function Tabs({ value, defaultValue, onValueChange, children }: TabsProps) {
  const [internal, setInternal] = useState(defaultValue ?? null);
  const isControlled = value !== undefined;
  const active = isControlled ? value : internal;

  const select = useCallback((next: string) => {
    if (!isControlled) setInternal(next); // uncontrolled: own the state
    onValueChange?.(next);                // controlled: the parent decides
  }, [isControlled, onValueChange]);

  const ctx = useMemo(() => ({ active, select }), [active, select]);
  return <TabsCtx.Provider value={ctx}>{children}</TabsCtx.Provider>;
}

Tabs.Trigger = function Trigger({ value, children }: TriggerProps) {
  const { active, select } = useTabs("<Tabs.Trigger>");
  return (
    <button role="tab" aria-selected={active === value} onClick={() => select(value)}>
      {children}
    </button>
  );
};

Three load-bearing details. First, the context default is null and useTabs throws on it — a Tabs.Panel pasted outside Tabs fails at the misuse site with a named error, instead of rendering broken UI or crashing on an undefined read three layers deeper. Second, the controlled/uncontrolled duality: the component supports both value (parent owns state, component merely reports intent through onValueChange) and defaultValue (component owns state internally). isControlled is decided by value !== undefined and must stay fixed for the life of the instance — a half-controlled component that updates internal state and reads value will visually desync the moment the parent skips an update. Third, the context value is memoized: every consumer of TabsCtx re-renders when the value changes identity, so an inline object here would re-render every trigger and panel on each Tabs render.

Slots versus children inspection

There is an older way to wire a family: iterate children, find your parts by element type, and inject props with cloneElement. It reads cleverly and it is a trap:

// Children inspection couples the parent to the exact element tree.
function Tabs({ children }) {
  return Children.map(children, (child, i) =>
    isValidElement(child) && child.type === Tab
      ? cloneElement(child, { index: i })
      : child // a Fragment, a FeatureFlag wrapper, a custom Tab — silently skipped
  );
}

Children.map sees the immediate element layer, nothing deeper. Wrap a Tab in a fragment and the fragment is one opaque child; the tabs inside it are invisible. Wrap it in a FeatureFlag component and child.type is FeatureFlag, not Tab — the match fails, the index never arrives. Extract two tabs into a local BillingTabs component — same silent breakage, because what a component will render does not exist until render. Every one of these is a normal, encouraged refactor, and children inspection punishes all of them. That is why react.dev files the Children API under legacy and why context-wired compounds won: context reaches any descendant at any depth, through any wrapper, with no assumptions about tree shape. For fixed regions where you want explicit structure — an icon, a set of actions — a named slot is the honest tool: a plain prop typed ReactNode (icon={<Save />}, actions={...}), enumerable like configuration but open like composition.

Where render props still win

Hooks replaced render props for logic sharing, but one niche is structurally theirs: the component owns a loop over data and the app owns the markup per item. A virtualized list decides which rows exist, measures them, and positions them — only it knows the row data and the absolute-positioning style for each visible index. It must hand both back to the caller, per row, and a function child is the only channel with that shape:

<VirtualList items={rows} rowHeight={32}>
  {(row, style) => (
    <div style={style} className="row">
      {row.symbol} · {row.qty}
    </div>
  )}
</VirtualList>

Plain children cannot do this — children are created by the caller before the list knows anything. The test is direction of data flow: when the parent produces per-invocation data the caller needs, a render prop; when the caller produces the content, children; when parts share state, a compound family. TanStack Virtual and Table, downshift, and every serious data-grid live in this niche on purpose.