Compound Components: What, Why and When.

What are Compound Components? #

It’s a base component that expects to be combined with other component parts. Below the <Multiselect /> is the base component and the <Option /> and <Group /> components are the composable parts.

<Multiselect
  selectedValues={[1, 2]}
  onSelectedValuesChange={newValues => /* ... */}/>
  <Option optionValue={1}>One</Option>
  <Group header="The best numbers">
    <Option optionValue={2}>Two</Option>
    <Option optionValue={3}>Three</Option>
  </Group>
</Multiselect>

It differs from the use of { children } props where you are not expecting any components in particular.

<Box>
  <Header title="My Work" />
  <Content>Lots of good stuff</Context>
</Box>

While the <Multiselect /> children will accept any components, having a combination of a base and a part component like <Option /> that is intended to be used with it passes our Compound Component definition.

Why would you opt for this pattern? #

The main advantage that the Compound Component pattern version offers is its flexibility. Want to make a <Multiselect /> of people that includes their avatar? Easy.

<Multiselect
  selectedValues={[1, 2]}
  onSelectedValuesChange={newValues => /* ... */}/>
  <PersonOption personId={1}>Jane</Option>
  <PersonOption personId={2}>John</Option>
</Multiselect>

We can support many variations without having to change the base components code.

To mirror the same behaviour using strict props we need to start adding flags like isPersonOptions:

<Multiselect
  selectedValues={[1, 2]}
  onSelectedValuesChange={newValues => /* ... */}
  isPersonOptions={true}
  options={[
    {name: 'Jane', id: 1},
    {name: 'John', id: 2},
  ]}/>
</Multiselect>

More flags will build up over time and the complexity will grow.

When should you use it? #

It’s when you need flexibility. Are you building something that will be widely used?

See React Component API Design for API design alternatives.