React Reference ยท Props and Attributes
React children prop
Reference for the React children prop: what it contains, how to build wrapper components, slots via extra props, function children, and the Children helpers.
children is the prop that holds whatever you put between a component's opening and closing tags. If you write <Card>Hello</Card>, the Card function receives { children: 'Hello' }. It is how React components wrap other content: layouts, cards, modals, tooltips, providers. Passing JSX as children is called composition, and it is the main alternative to inheritance and to piling up configuration props.
Children can be almost anything React can render: a string, a number, an element, an array of them, null or undefined (renders nothing), or even a function that your component decides how to call. You can also pass children explicitly as a normal prop, but nesting is the idiom.
function Card({ children }) { return <div className="card">{children}</div>; } <Card> <h3>Title</h3> <p>Any content here.</p> </Card>
Try it
Syntax
function Wrapper({ children }) { return <div>{children}</div>; }
| Name | Description |
|---|---|
children |
The content between the tags. A single child is passed as is; several children arrive as an array. No children means undefined. |
Children.map(children, fn) |
Calls fn(child, index) for each child, flattening arrays, and returns an array. Empty nodes (null, undefined, booleans) are passed to fn as well. |
Children.count(children) |
Number of nodes after flattening arrays. Empty nodes (null, undefined, booleans) and empty strings count too; count(null) is 0. |
Children.toArray(children) |
A flat array with keys added to each child; empty nodes are removed. |
Children.only(children) |
Returns the single child element or throws. |
Children.forEach(children, fn) |
Like map, without a result. |
Returns: children itself is whatever the parent passed. Rendering it returns that content.
Errors: Children.only throws when given zero or several elements. Rendering a plain object as a child throws Objects are not valid as a React child. A function child is only valid if your component calls it.
Usage notes
- Text and whitespace in JSX. JSX removes whitespace-only lines and trims the start and end of each text line, then joins the lines with a single space. Spaces inside one line are kept as written (the browser collapses them when displaying). Use
{' '}for an explicit space at a line edge. - Single child versus array.
childrenis one element for one child and an array for several. Code that doeschildren.map(...)breaks for one child. UseChildren.maporChildren.toArray, or avoid inspecting children at all. - Prefer slot props to inspecting children. For layouts with named regions (
header,sidebar), accept elements as props:<Layout sidebar={<Nav />}>...</Layout>. This is more explicit and survives refactors. - The Children helpers are in maintenance mode. They can only see what the parent passed, not what a child component renders, and they break when someone wraps a child in a fragment or another component. Use context or explicit props when you need more control.
- Children can skip re-renders. When a wrapper re-renders because of its own state, the
childrenit received are the same element objects as before, so React can reuse them without calling the child components again. This is why the wrapper-with-state pattern is cheap. - Cloning children with
cloneElementto inject props is fragile. Use context or a render prop instead. See cloneElement. - Server Components can pass Client Components as
children, so a client wrapper can contain server-rendered content. - Do not mutate
children; elements are immutable descriptions. - TypeScript. Type it as
ReactNodefor anything renderable.