# Children in React: Complete Guide to Composition and the React.Children API
> Master React children and composition with our complete guide. Learn to use props.children for dynamic content and reusable UI elements effectively.
- Repository: [Meta/react](https://github.com/facebook/react)
- Tags: deep-dive
- Published: 2026-02-16
---
**Children in React are elements passed between a component's opening and closing JSX tags, accessible via `props.children`, and should be used for component composition and dynamic content wrapping.**
In the `facebook/react` repository, children represent an **opaque data structure** that can contain a single React element, an array of elements, strings, numbers, fragments, or `null` values. Understanding how to work with children in React enables you to build flexible, reusable wrapper components without hardcoding their contents.
## What Are Children in React?
When you nest content inside a JSX tag, React passes that content to the component function as a special property called `props.children`:
```jsx
Title
Content here
```
Inside `Card`, the nested `` and `
` elements arrive as `props.children`. According to the React source code in [`packages/react/src/ReactChildren.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactChildren.js), React treats this property as an opaque data structure that requires specialized utilities to traverse safely. Directly manipulating `props.children` with array methods can fail when children contain fragments, lazy components, or nested arrays.
## When to Use Children in React
Use children in React when building **composable wrapper components** that need to render arbitrary content without knowing its structure ahead of time. This pattern appears in layout components, modal dialogs, context providers, and styling containers.
The primary use cases include:
- **Component composition** – Creating reusable containers like cards, modals, or page layouts that accept any valid React element as content.
- **Dynamic content injection** – Wrapping children with additional styling, event handlers, or context providers before rendering.
- **List processing** – Transforming or validating collections of elements using the `React.Children` API.
- **Layout control** – Flattening nested structures or enforcing single-child constraints for specialized components.
## The React.Children API for Safe Manipulation
The `React.Children` API provides five utility functions implemented in [`packages/react/src/ReactChildren.js`](https://github.com/facebook/react/blob/main/packages/react/src/ReactChildren.js) to traverse and manipulate the opaque children data structure safely. These utilities handle edge cases like `null` values, fragments, and lazy components automatically.
### Mapping and Transforming with React.Children.map
Use `React.Children.map` to iterate over children and return a new array of transformed elements. Unlike `Array.prototype.map`, this utility handles nested arrays and fragments correctly:
```jsx
import React from 'react';
export default function List({ children }) {
const items = React.Children.map(children, child =>
React.isValidElement(child)
? React.cloneElement(child, {
className: `${child.props.className ?? ''} list-item`,
})
: child
);
return
;
}
```
This pattern relies on `isValidElement` and `cloneAndReplaceKey` from [`packages/react/src/jsx/ReactJSXElement.js`](https://github.com/facebook/react/blob/main/packages/react/src/jsx/ReactJSXElement.js) to safely augment each child.
### Iteration with React.Children.forEach
`React.Children.forEach` executes a function for each child without returning a new array. Use this for side effects like logging or validation:
```jsx
React.Children.forEach(children, (child, index) => {
console.log(`Child ${index}:`, child);
});
```
### Counting with React.Children.count
`React.Children.count` returns the total number of leaf nodes in the children structure, including nested arrays and fragments:
```jsx
import React from 'react';
export default function MaxTwo({ children }) {
const count = React.Children.count(children);
if (count > 2) {
console.warn('MaxTwo expects at most 2 children');
}
return {children}
;
}
```
### Enforcing Single Child with React.Children.only
`React.Children.only` validates that children contains exactly one React element, throwing an error otherwise. Use this for components that require a single content node:
```jsx
import React from 'react';
export default function Modal({ children }) {
const content = React.Children.only(children);
return (
);
}
```
### Flattening with React.Children.toArray
`React.Children.toArray` converts any children structure into a flat array with assigned keys, handling fragments and nested arrays automatically:
```jsx
import React from 'react';
export default function Grid({ children }) {
const flat = React.Children.toArray(children);
return (
{flat.map((child, i) => (
{child}
))}