Skip to content
Tutorials Center
My learning

Topics

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.

JSX
import { Children } from 'react';

const total = Children.count(children);

Try it

Counting, mapping and flattening

The false child still counts as a step (step 2 is empty): count and map see empty nodes, while toArray removes them.

toArray and only

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

TypeScript
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 map as null. false, true and undefined are passed to your callback as null, so handle null.
  • Keys are generated. map and toArray give 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 its props.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 toArray output as state or reuse indexes as keys. The result changes whenever the children change.
  • count does not match array length for empty values or nested arrays, so Children.count(children) can differ from Children.toArray(children).length, as the second example shows.
  • only is for components that must wrap exactly one element (for example a tooltip trigger). It throws React.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.