When to Use This Pattern
You'll learn: How to recognize when Compound Components are the right design choice for your React architecture.
The Signal: Multiple Related Pieces Sharing State
Compound Components shine when you're building UI elements that have multiple moving parts that need to coordinate. If you find yourself passing the same state down through many levels of props, or trying to control multiple related elements from a single parent, you've likely found a good candidate.
Classic Examples
Tabs: A <TabList> needs to know which tab is active. Each <Tab> needs that same information. The <TabPanel> components also need to know. Rather than passing activeTab and setActiveTab to each piece separately, Compound Components let them share this state implicitly.
Accordions: The accordion container manages which sections are open. Each <AccordionItem> needs access to that state to render correctly. Each <AccordionTrigger> needs to update that state. All these pieces are tightly related.
Dropdowns: A <Dropdown> manages open/closed state. The <DropdownTrigger> needs to toggle it. The <DropdownMenu> needs to read it. The <DropdownItem> components might need to close the dropdown when clicked.
The Key Questions
Ask yourself:
- Do these components only make sense together? (A tab panel without tabs is meaningless)
- Are they sharing the same state? (All pieces need to know what's selected/open)
- Would the API be cluttered with props if you kept them separate?
- Does the user need flexibility in arrangement? (Tabs on top vs. bottom)
If you answered "yes" to most of these, Compound Components will make your API cleaner and more intuitive.
Key Takeaway: Use Compound Components when you have multiple related UI pieces that share state and only make sense as a coordinated group—like tabs, accordions, or dropdowns.