React Reference ยท Top-Level React APIs
React Children utilities
Reference for React.Children: count, map, forEach, toArray and only for working with the children prop, with edge cases for empty values, arrays and fragments.
Children is a set of helper functions for the children prop. Children can be a single element, a string, a number, null, or a nested array of all of those, so looping over them with plain array methods is unsafe: children.map fails when there is only one child. The helpers accept any shape and treat it uniformly.
The five helpers are Children.count, Children.map, Children.forEach, Children.toArray and Children.only. The React team calls the API legacy because it makes components fragile, and recommends passing data through props or context instead, but it remains supported and widely used.
import { Children } from 'react'; const total = Children.count(children);
Try it
The false child still counts as a step (step 2 is empty): count and map see empty nodes, while toArray removes them.
The second Inspect logs count: 4 toArray length: 3: count counts the null as a node, while toArray drops empty values and gives the rest keys such as .0 and .2.
Syntax
Children.count(children: ReactNode): number; Children.map<T>(children: ReactNode, fn: (child: ReactNode, index: number) => T): T[] | null | undefined; Children.forEach(children: ReactNode, fn: (child: ReactNode, index: number) => void): void; Children.toArray(children: ReactNode): Array<Exclude<ReactNode, boolean | null | undefined>>; Children.only(children: ReactNode): ReactElement;
| Function | Description |
|---|---|
count(children) |
Number of nodes. Strings, numbers, elements, null, undefined and booleans each count as one; arrays count their contents; fragments count as one element. |
map(children, fn) |
Calls fn(child, index) for each node and returns a flat array of the results. Returns null or undefined unchanged if children is one of those. |
forEach(children, fn) |
Like map but returns nothing. |
toArray(children) |
A flat array of children without empty nodes, with keys added to elements. |
only(children) |
Returns the child if it is exactly one element; otherwise throws. |
Usage notes
- Empty nodes reach
mapasnull.false,trueandundefinedare passed to your callback asnull, so handlenull. - Keys are generated.
mapandtoArraygive returned elements keys derived from their position, so you rarely need to add your own. A key you set on a returned element is prefixed rather than lost. - Fragments are not flattened.
<><A /><B /></>is one child. To work on the fragment's contents you must read itsprops.children. - Only what is written in the JSX is seen. The helpers inspect elements passed as
children, not what a child component renders. Wrapping a child in another component hides it from the parent. - Do not store
toArrayoutput as state or reuse indexes as keys. The result changes whenever the children change. countdoes not match array length for empty values or nested arrays, soChildren.count(children)can differ fromChildren.toArray(children).length, as the second example shows.onlyis for components that must wrap exactly one element (for example a tooltip trigger). It throwsReact.Children.only expected to receive a single React element child.otherwise; a string child also fails.- Alternatives: accept data as a prop (
items), use named slots (header,footer), or context. They survive refactors that wrap children.