sastan/react-render-callback

render-prop helper to render anything (Functions, Components, Elements, ...)

react-render-callback

render-prop helper to render anything (Functions, Components, Elements, ...)

The problem

You want your component to support the render prop pattern with different types of values like Function as children, a React.Component (Component Injection) or just plain react elements.

This solution

react-render-callback frees you from detecting what kind fo render prop your component is dealing with:

import React from 'react'
import renderCallback from 'react-render-callback'

class Component from React.Component {
  state = {}

  render() {
    // can be any prop like render, component, renderHeader, ...
    // children may be a function, a component, an element, ...
    return renderCallback(this.props.children, this.state)
  }
}

View an example in codesandbox.io.

Highlights

• 📦 Super tiny (~650 bytes)
• 👌 Dependency free (except for Object.assign polyfill)
• 🔌 Just Works ^TM
• 🔮 Tree shaking friendly (ESM, no side effects)
• 📚 Well documented
• 💯 test coverage
• ☀️ supports React v0.14, v15 and v16
• 👪 supports rendering of
  • Stateless Function Components (SFC) with one argument (the common props case) aka Render Props aka Function as Child or optional with several arguments
  • Class Components aka Component Injection
  • Context Provider and Consumer
  • Forward Refs
  • Factories
  • Elements with optional support for cloning to merge props
  • primitives like strings, numbers, arrays, ...
  • false, null, undefined and true are returned as null just like in JSX

Table of Contents

• Installation
• Usage
  • API
  • Examples
• Other Solutions
• Credits
• Contributors
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save react-render-callback

This package also depends on react. Please make sure you have it installed as well.

The Universal Module Definition (UMD) is available via unpkg.com and exposed as ReactRenderCallback.

<script src="https://unpkg.com/react-render-callback/dist/react-render-callback.umd.min.js"></script>

Usage

API

renderCallback([ renderable [, props [, options ] ] ])

renders the given renderable with props

// esm
import renderCallback from 'react-render-callback'
// commonjs
const renderCallback = require('react-render-callback')

renderable (optional): anything that can be rendered like a function, a component, or elements

• uses React.createElement for react types like class components, context provider or consumer, forward refs, factories, ...
• invokes stateless function components (SFC) respecting their defaultProps
  • not using React.createElement for improved performance
  • except the SFC has propTypes and process.env.NODE_ENV is not production, in that case React.createElement is used to enable typechecking with PropTypes
• gracefully handles other types like string, array, react elements, ...

props (optional): to pass to renderable

options (optional):

• cloneElement (default: false, since: v1.1.0): allows to pass props to the element using React.cloneElement

renderCallback(<a href="#bar">bar</a>, {title: 'foo'})
// --> <a href="#bar">bar</a>

renderCallback(<a href="#bar">bar</a>, {title: 'foo'}, {cloneElement: true})
// --> <a href="#bar" title="foo">bar</a>

returns

• the created react element
• false, null, undefined and true are returned as null just like in JSX
• the value as is for all other values

createRender([ renderable [, options ] ])

since: v1.1.0

Returns a function ((...args) => ...) to render renderable with.

// esm
import {createRender} from 'react-render-callback'
// commonjs
const {createRender} = require('react-render-callback')

Accepts the same arguments (except props) as renderCallback(). It exists mainly to pre-determine (read cache) what type renderable is, to prevent these checks on every invocation.

Additionally the returned method accepts more than one argument (since: v1.2.0). This allows to provide several parameters to the renderable.

const renderCallback = createRender((a, b, c) => ({a, b, c}))
renderCallback(1, 2, 3)
// -> { a: 1, b: 2, c: 3 }

If the renderable has a defaultProps property only the first parameter is used and merged with the defaultProps.

returns

a function ((...args) => ...) to render the args

Examples

A basic example showing the most common use cases can be viewed/edited at codesandbox.io.

Use options.cloneElement

This option allows to pass down props without to need to create a function within render which merges the defined and provided props.

class CountSeconds extends React.Component {
  state = {
    value: 0,
  }

  componentDidMount() {
    this.timer = setInterval(() => {
      this.setState(({value}) => ({value: value + 1}))
    }, 1000)
  }

  componentWillUnmount() {
    clearInterval(this.timer)
  }

  render() {
    const {children, render = children} = this.props
    return renderCallback(render, this.state, {cloneElement: true})
  }
}

const DisplayValue = ({prefix = '', value}) => `${prefix}${value}`

const App = ({prefix}) => (
  <CountSeconds>
    <DisplayValue prefix={prefix} />
  </CountSeconds>
)

Use createRender to pass down several arguments

class CountSeconds extends React.Component {
  state = {
    value: 0,
  }

  reset = () => {
    this.setState({value: 0})
  }

  componentDidMount() {
    this.timer = setInterval(() => {
      this.setState(({value}) => ({value: value + 1}))
    }, 1000)
  }

  componentWillUnmount() {
    clearInterval(this.timer)
  }

  render() {
    const {children, render = children} = this.props
    return createRender(render)(this.state.value, this.reset)
  }
}

const DisplayValue = ({prefix = '', value}) => `${prefix}${value}`

const App = () => (
  <CountSeconds>
    {(value, reset) => (
      <React.Fragment>
        <DisplayValue prefix="Seconds: " value={value} />
        <button onClick={reset} type="button">
          reset
        </button>
      </React.Fragment>
    )}
  </CountSeconds>
)

Use createRender to interop with a library which only supports functions as render-prop

import Toggle from 'react-toggled'

class Toggler extends React.Component {
  static defaultProps = {
    onLabel: 'Toggled On',
    offLabel: 'Toggled Off',
  }

  render() {
    const {on, getTogglerProps, onLabel, offLabel} = this.props

    return (
      <div>
        <button {...getTogglerProps()}>Toggle me</button>
        <div>{on ? onLabel : offLabel}</div>
      </div>
    )
  }
}

const ToggleView = createRender(Toggler)

const App = () => <Toggle>{ToggleView}</Toggle>

Other Solutions

• render-props
• react-render-function
• @macklinu/render-props

Credits

A special thanks needs to go to Kent C. Dodds for his great video series ( egghead.io, frontendmasters.com and youtube.com). His projects are either used in this project (kcd-scripts) or are a template for the structure of this project (downshift). Make sure to subscribe to his newsletter.

Contributors

Thanks goes to these people (emoji key):

Sascha Tandel 💻 📖 🚇 ⚠️ 👀 📝 🐛 💡 🤔 📢

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT