Compound Components

What this pattern is

Compound components are components that work together as a group, usually like:

You’ve probably already worked with them in component libraries like Chakra UI.

The idea:

• Root manages state + context
• Child components read that context
• Users compose structure freely.

Why it’s powerful

1. Friendly API

   • You write UI the way it looks in HTML.
   • Less prop noise.

2. No prop drilling

   • Root provides shared state via context.
   • Children consume it directly.

3. Modular by default

   • Want no close button? Don’t render it.
   • No style props.

4. Scales better than “god props”

   • Alternative is a single component with 20 props and flags.
   • That becomes a massive component quickly.

5. Encourages consistent behavior

   • All items share the same rules from Root.
   • Easier to keep UX aligned.

Mental model

Think of compound components like a mini-app / subsystem:

• Root = controller / state owner
• Children = specialized views
• Context = internal wiring

The user (caller) defines layout, but your component defines rules.

When to use it

Use compound components when:

• You have a family of UI parts that must cooperate.
• Layout should be flexible for the caller.
• Passing state as props would get ugly.
• You want a scalable design-system-style API.

Don’t use it if:

• there’s only one simple UI element
• or the component doesn’t need internal coordination
• there’s not a need for the flexibilite this pattern offers

Accordion example

vs

Resources

• Chakra UI Accordion
• Compound Pattern - patterns.dev