Why React.Children.only?

Question

Quick question for react gurus ;)

React.Children.only is one of its top-level apis, and is very commonly used by react-redux (<Provider />) and React Router (<Router />) to inject store/router as context, what's the reason behind this, why not simply return props.children? Seems something to do with JSX?

EDIT: Please don't explain what is React.Children.only, i am asking for why using it instead of props.children, which seems more powerful/flexible.

Answer 1

As pointed out in the docs

Verifies that children has only one child (a React element) and returns it. Otherwise this method throws an error.

So now why is it helpful over just using props.children?

The main reason is it's throwing an error, thus halting the whole dev flow, so you cannot skip it.

This is a handy util that enforces a rule of having specifically and only one child.

Of course, you could use propTypes, but that will only put a warning in the console, that you might as well miss.

One use case of React.Children.only can be to enforce specific declarative interface that should consist of one logical Child component:

class GraphEditorEditor extends React.Component {
  componentDidMount() {
    this.props.editor.makeEditable();
    // and all other editor specific logic
  }

  render() {
    return null;
  }
}

class GraphEditorPreview extends React.Component {
  componentDidMount() {
    this.props.editor.makePreviewable();
    // and all other preview specific logic
  }

  render() {
    return null;
  }
}

class GraphEditor extends React.Component {
  static Editor = GraphEditorEditor;
  static Preview = GraphEditorPreview;
  wrapperRef = React.createRef();

  state = {
    editorInitialized: false
  }

  componentDidMount() {
    // instantiate base graph to work with in logical children components
    this.editor = SomeService.createEditorInstance(this.props.config);
    this.editor.insertSelfInto(this.wrapperRef.current);

    this.setState({ editorInitialized: true });
  }

  render() {
    return (
      <div ref={this.wrapperRef}>
        {this.editorInitialized ?
          React.Children.only(
            React.cloneElement(
              this.props.children, 
              { editor: this.editor }
            )
          ) : null
        }
      </div>
    );
  }
}

which can be used like this:

class ParentContainer extends React.Component {
  render() {
    return (
      <GraphEditor config={{some: "config"}}>
        <GraphEditor.Editor> //<-- EDITOR mode
      </GraphEditor>
    )
  }
}

// OR

class ParentContainer extends React.Component {
  render() {
    return (
      <GraphEditor config={{some: "config"}}>
        <GraphEditor.Preview> //<-- Preview mode
      </GraphEditor>
    )
  }
}

Hope this is helpful.

Answer 2

Before React 16, a Component's render method could not return an array of elements. When implementing a component that didn't introduce any of its own markup, you had no choice but to only accept a single child:

// We have to ensure that there's only one child, because returning an array
// from a component is prohibited.
const DisplayIf = ({children, condition}, {uniforms}) =>
    condition(uniforms) ? Children.only(children) : nothing;
DisplayIf.contextTypes = BaseField.contextTypes;

Now you can simply return props.children, requiring the caller to include keys on array elements, or return <>{props.children}</>, using a Fragment to avoid returning an array:

const DisplayIf = ({children, condition}, {uniforms}) =>
    condition(uniforms) ? <>{children}</> : nothing;
DisplayIf.contextTypes = BaseField.contextTypes;

Answer 3

I have just found out a case of using Children.only while implementing Tooltip component: https://github.com/chakra-ui/chakra-ui/blob/2456a7090439ebd1a1d1cdee36daa472d12ce6f7/packages/components/tooltip/src/tooltip.tsx#L113.

When there is an unknown number of children, it will be tricky for Tooltip component itself to set the ref. As a result, it will be really handy to have Children.only here.