The compound component pattern

A compound component is one parent that owns state plus sub-components that read it implicitly — the consumer never wires the state by hand. Compare the two API shapes. The props-driven Tabs accepts a data array and dictates the markup; the compound Tabs accepts children and lets the caller write the markup, while the pieces silently share which tab is active.

// props-driven: the component owns the layout, you feed it config
<Tabs
  tabs={[{ id: "a", label: "Account", panel: <Account /> }]}
  renderTab={(t) => <span>{t.label}</span>}
/>

// compound: you own the layout, the pieces share state implicitly
<Tabs defaultValue="account">
  <Tabs.List>
    <Tabs.Tab value="account">Account</Tabs.Tab>
    <Tabs.Tab value="billing">Billing</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="account"><Account /></Tabs.Panel>
  <Tabs.Panel value="billing"><Billing /></Tabs.Panel>
</Tabs>

The compound version reads like markup, not configuration. That readability is the feature — and it comes from the pieces sharing state without the caller passing activeTab to each one.

The implicit channel between parent and pieces is React context — the parent provides, every sub-component consumes. The parent holds the active value in state and exposes it (plus a setter) through a context. Tabs.Tab reads the context to know whether it’s selected and to flip the value on click; Tabs.Panel reads it to decide whether to render. No prop drilling, no caller-supplied glue.

type TabsCtx = { value: string; setValue: (v: string) => void };
const TabsContext = createContext<TabsCtx | null>(null);

function useTabs() {
  const ctx = useContext(TabsContext);
  if (!ctx) throw new Error("Tabs.* must be rendered inside <Tabs>");
  return ctx;
}

function Tabs({ defaultValue, children }: { defaultValue: string; children: React.ReactNode }) {
  const [value, setValue] = useState(defaultValue);
  return <TabsContext.Provider value={{ value, setValue }}>{children}</TabsContext.Provider>;
}

The useTabs guard that throws when used outside the provider is not optional polish — it turns a confusing null crash into a clear contract violation at the call site.

The sub-components are attached as static fields on the parent — Tabs.List, Tabs.Tab, Tabs.Panel — so the API arrives as a single import. Each piece is a normal component that calls useTabs(). Hanging them off the parent groups the family namespace, signals they belong together, and means consumers import one symbol.

Tabs.List = function List({ children }: { children: React.ReactNode }) {
  return <div role="tablist">{children}</div>;
};

Tabs.Tab = function Tab({ value, children }: { value: string; children: React.ReactNode }) {
  const { value: active, setValue } = useTabs();
  const selected = active === value;
  return (
    <button role="tab" aria-selected={selected} onClick={() => setValue(value)}>
      {children}
    </button>
  );
};

Tabs.Panel = function Panel({ value, children }: { value: string; children: React.ReactNode }) {
  const { value: active } = useTabs();
  return active === value ? <div role="tabpanel">{children}</div> : null;
};

Tabs.Tab doesn’t receive isActive from the consumer — it derives it from shared state. That derivation living inside the piece is what gives the caller layout freedom: they place the tab anywhere, and it still knows whether it’s selected.

The payoff is consumer ergonomics: the caller rearranges the internals freely because the pieces find their state by position in the tree, not by prop wiring. The same Tabs renders panels-above-list on mobile, slips a badge into a tab label, or drops a divider between tabs — none of which the parent had to anticipate. A props-driven API would need a new prop for each of those; the compound API needs nothing, because layout is the consumer’s job and behavior is the parent’s.

// the consumer reshuffles internals — the parent never changed
<Tabs defaultValue="inbox">
  <Tabs.Panel value="inbox"><Inbox /></Tabs.Panel>   {/* panels first on mobile */}
  <Tabs.List>
    <Tabs.Tab value="inbox">Inbox <UnreadBadge /></Tabs.Tab>  {/* badge inline */}
    <Divider />                                              {/* arbitrary node */}
    <Tabs.Tab value="archive">Archive</Tabs.Tab>
  </Tabs.List>
</Tabs>

This is exactly why design systems (Radix, Reach, Headless UI, Ariakit) ship compound APIs: the library owns the hard, invariant behavior; the application owns the layout that differs per screen.