README.md

React Composer

Compose render prop components.

Motivation

Render props are great. Using a component with a render prop looks like the following:

<RenderPropComponent {...config}>
  {(result) => (<MyComponent result={result} />)}
</RenderPropComponent>

Sometimes you need the result of multiple render prop components inside of MyComponent. This can get messy.

<RenderPropComponent {...config}>
  {resultOne => (
    <RenderPropComponent {...configTwo}>
      {resultTwo => (
        <RenderPropComponent {...configThree}>
          {resultThree => (
            <MyComponent results={{resultOne, resultTwo, resultThree}} />
          )}
        </RenderPropComponent>
      )}
    </RenderPropComponent>
  )}
</RenderPropComponent>

Nesting render prop components leads to rightward drift of your code. Use React Composer to prevent that drift.

import Composer from 'react-composer';

<Composer components={[
    <RenderPropComponent {...configOne} />,
    <RenderPropComponent {...configTwo} />,
    <RenderPropComponent {...configThree} />
  ]}>
  {([resultOne, resultTwo, resultThree]) => (
    <MyComponent results={{resultOne, resultTwo, resultThree}} />
  )}
</Composer>

Installation

Install using npm:

npm install react-composer

or yarn:

yarn add react-composer

API

This library has one export: Composer.

<Composer />

Compose multiple render prop components together. The props are as follows:

components

The render prop components to compose.

Note: You do not need to specify the render prop on the components. If you do specify the render prop, it will be ignored.

children

A function that is called with an array of results from the render prop components.

renderPropName

The name of the component's render prop. Defaults to "children".

Note: Components typically use children or render as the render prop. Some even accept both.

mapResult

A function that is called with the same arguments that each component's render prop is called with. This can be used to change the result that each component passes down.

Typically, this is useful for a component that passes multiple arguments to its render prop. You could, for instance, map the arguments to an array:

<Composer
  components={[<RenderPropComponent />]}
  mapResult={function() {
    return Array.from(arguments);
  }}>
  {() => { ... }}
</Composer>

Note: This is an advanced feature that you won't often need to use, but it's here should you need it.

Guides

Limitations

This library only works for render prop components that have a single render prop. So, for instance, this library will not work if your component has an API like the following:

<RenderPropComponent onSuccess={onSuccess} onError={onError} />

Render Order

The components render last-to-first. So, for instance, if you pass

<Composer components={[<A/>, <B/>, <C/>]}>

then your tree will render like so:

- C
  - B
    - A

Note: Do you think the render order should be reversed? I'm open to that change. Leave your comments over in Issue #7.

Example Usage

Here are some examples of render prop components that benefit from React Composer:

• React's new Context API. See this example by Kent Dodds.
• React Request

Do you know of a component that you think benefits from React Composer? Open a Pull Request and add it to the list!