How to Implement the Compound Component Pattern in React

When building complex components like tabs, accordions, or dropdowns, you often need multiple sub-components to share state without the parent of those components needing to manage that state themselves. The Compound Component pattern lets these sub-components communicate implicitly through shared context rather than through explicit props passed by the user.

Create the main parent component, for example a Tabs component. Inside it, create a Context using createContext. The parent manages all shared state using useState, such as the currently active tab index. Provide this state and any updater functions through the Context's Provider, wrapping the children prop.

Create separate components for each part of the compound, such as Tabs.List, Tabs.Tab, and Tabs.Panel. These sub-components are the building blocks the user assembles. Each one reads from the Context created by the parent to access the shared state without receiving it as explicit props.

After defining the sub-components, attach them as properties on the parent component. Write Tabs.List = TabList, Tabs.Tab = Tab, and Tabs.Panel = TabPanel. This allows users to import only the parent Tabs component and access all sub-components through dot notation, keeping the API clean and discoverable.

Inside each sub-component, call useContext with the parent's context object. This gives the sub-component access to the shared state. For example, a Tab sub-component reads the active index from context and applies an active class to itself if its own index matches. A Panel reads the active index to decide whether to show or hide its content.

The power of this pattern is that the user controls the structure and composition. They can place sub-components in any order, add their own elements between them, or conditionally render sub-components. The parent does not dictate structure through props. It only manages the shared state that sub-components need to function correctly together.

Inside each sub-component's useContext call, check if the returned context value is undefined. If it is, it means the sub-component was used outside of the parent component's Provider. Throw an informative error explaining that the sub-component must be used inside the parent. This prevents confusing bugs and helps other developers use the API correctly.

Use Compound Components when building UI components that have multiple related parts working together, when you want to give users flexibility in composing the structure, and when you want to avoid the prop-explosion problem where a single component accepts dozens of props to control every aspect of its sub-parts. Common examples are Select, Modal, Menu, Accordion, and Tabs components.