Compound Components
Components that understand each other
Compound Components is a pattern where a parent component shares state implicitly with its children through Context. The children are independent pieces that know how to talk to the parent — without manual props between them. It's the foundation of Radix UI, shadcn/ui, and most modern design systems.
The core idea
Instead of controlling everything from the parent with props (activeTab, onTabChange, tabLabels…), you create an internal context that subcomponents consume. The user composes the pieces freely: <Tabs><Tabs.List>…</Tabs.List><Tabs.Panel>…</Tabs.Panel></Tabs>. State lives in Tabs, but no child needs to receive explicit props.
How it's built
Create a private context. The root component manages state and provides the context. Subcomponents consume it. Attach subcomponents as static properties of the parent (Tabs.List, Tabs.Tab, Tabs.Panel) so the API is self-discoverable — the user types Tabs. and their editor shows the available pieces.
Common pitfalls
- 01The context is private to the pattern — don't export it globally. Each Tabs instance has its own Provider.
- 02If the user nests two Tabs, the nearest context wins. That's usually correct, but verify it's intentional.
- 03Attaching subcomponents as static properties (Tabs.List) is convention, not mandatory — you can also export them separately.