Compound Components in React: Flexible Sub-Component APIs

A component like Select that needs custom option rendering, icons, and trigger labels quickly accumulates an unwieldy list of configuration props. The Compound Components pattern addresses this by letting consumers compose the internal structure directly as JSX, rather than configuring every variation through props on one monolithic component.

Instead of one component, several small, related components are exposed together — like Select, Select.Option, and Select.Trigger — meant to be composed as JSX by the consumer. This gives the consumer full control over structure and content, while shared state is coordinated behind the scenes.

Sub-components need to coordinate — an Option needs to know the currently selected value and how to change it — without the consumer manually threading that data through props. The parent component creates a Context and provides shared state and setters, which each sub-component reads internally.

Each sub-component calls useContext to read the shared state and update functions provided by the parent. This coordination is invisible to the consumer, who only writes plain JSX, while internally it's exactly what lets the separate sub-components cooperate correctly.

Assigning Select.Option = Option attaches the Option component as a property of the Select function, making <Select.Option> valid JSX. This groups related components under a single, discoverable namespace and lets consumers import just the parent component to access everything.

The Prop Explosion Problem. A <Select> component that needs custom option icons, custom styling per option, and a custom trigger label quickly grows an unwieldy prop list: optionIcon, optionRenderer, triggerLabel, optionClassName... Compound Components solve this by letting consumers compose the internal pieces directly, instead of configuring them all through props on one giant component.

What Compound Components Look Like. Instead of one monolithic component, you expose several small components meant to be used together, like <Select>, <Select.Option>, and <Select.Trigger>. The consumer composes them as JSX, giving them full control over structure and content, while the parent silently coordinates shared state behind the scenes.

What's the main advantage of <Select><Select.Option /></Select> over <Select options={[...]} /> for highly customizable UI?

• →Each option can be arbitrary, fully customized JSX instead of a rigid config object
• →It's always fewer total characters to type

Sharing State with Context. The sub-components need to coordinate — Select.Option needs to know the currently selected value and how to change it, without the consumer having to pass that down manually. The parent Select component creates a Context, and each child sub-component reads from it internally.

Consuming Context Inside a Sub-Component. Each sub-component, like Select.Option, calls useContext(SelectContext) to read the shared state and update function. From the consumer's perspective, this is invisible — they just write JSX. From the implementation's perspective, it's what makes the pieces actually cooperate.

How does Select.Option know which value is currently selected, without the consumer passing it a selectedValue prop directly?

• →It reads shared state from Context provided by the parent Select
• →It reads a global window variable

Attaching Sub-Components with Dot Notation. Select.Option = Option is what makes <Select.Option> valid JSX — you're attaching the Option component as a property on the Select function itself. This groups related components under a single, discoverable namespace, making the relationship between them explicit at the import site.

Mastery Achieved. You now understand the Compound Components pattern: exposing several cooperating sub-components instead of one prop-heavy monolith, sharing state invisibly through Context, and attaching sub-components via dot notation for a single clean import. Next, you'll compare controlled and uncontrolled component design more broadly.