React: what are use cases when we need React.Children api

Question

Just trying to find any use case for React.Children api. Reading docs is confusing. (React v. 15.2.0)

https://facebook.github.io/react/docs/top-level-api.html#react.children

Here they say, that this.props.children is 'opaque data structure'. But when debugging in chrome dev tools, it looks like children is an array. So functions like React.Children.map or React.Children.toArray don't make so much sense, as Array.prototype.map can be used instead of the first one, and the last produces the same result as original children property.

For me it looks like docs are outdated (I didn't use react 0.14.*, so I don't know what situation was there), or I am missing something. Will be glad if somebody can explain.

Thanks.

Answer 1

Nothing in JavaScript is really opaque. The deal here is that the React team considers the current implementation of children to be exactly that: implementation details.

They tell you to treat the data as opaque and only access it through their React.Children API so that they have the freedom to change the underlying data structure in the future without worrying about breaking existing apps.

If you do not use React.Children API and instead use the underlying Array prototype methods, then you are using unsupported implementation details and you risk having your code stop working with some new version of React.

Answer 2

React.Children is, as the documentation explains, a set of utilities for a components children. In this case (jsx):

<div>
  <span>Foo</span>
  <span>Bar</span>
</div>

Your div's children would be an array of the two spans. Consider a self-closing component:

<div>
   <SomeCustomElement/>
</div>

In this case, div has a single child, but this.props.children in SomeCustomElement would be null. So trying to call this.props.children.map would in some cases throw an error, since the children prop does not follow a strict typing convention.

React.Children does two things. It "fixes" (some would say circumvents) the before-mentioned by providing some common tools that allows you to not care about whether this.props.children is null, an array, a keyed fragment or whatever so you don't fill up your component with if, switch and such just to iterate over its children. Also, it ensures forward compatibility. It's arguable that a better way would just to stick to a strict type, providing an empty array instead of null, an array with a single element if the only child is a keyed fragment and so on.