lukechilds
/
react.dev
mirror of https://github.com/lukechilds/react.dev.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

[Beta] Children API (#5163) 

* [Beta] Children API

* tweak

* wip
main
dan 2 years ago
committed by GitHub
parent
3ac36ffd9c
commit
06ab241633
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 927 additions and 9 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 933
      beta/src/content/apis/react/Children.md
  2. 3
      beta/src/sidebarReference.json

933
beta/src/content/apis/react/Children.md
View File

@ -1,20 +1,939 @@
--- ---
title: React.Children title: Children
--- ---
<Wip> <Gotcha>
This section is incomplete, please see the old docs for [React.Children.](https://reactjs.org/docs/react-api.html#reactchildren) Using `Children` is uncommon and can lead to fragile code. [See common alternatives.](#alternatives)
</Wip>
</Gotcha>
<Intro> <Intro>
`React.Children` provides utilities for dealing with the this.props.children opaque data structure. `Children` lets you manipulate and transform the JSX you received as the [`children` prop.](/learn/passing-props-to-a-component#passing-jsx-as-children)
```js
const mappedChildren = Children.map(children, child =>
<div className="Row">
{child}
</div>
);
See the [React.Children](https://reactjs.org/docs/react-api.html#reactchildren) docs for more info. ```
</Intro> </Intro>
<InlineToc /> <InlineToc />
---
## Usage {/*usage*/}
### Transforming children {/*transforming-children*/}
To transform the children JSX that your component [receives as the `children` prop,](/learn/passing-props-to-a-component#passing-jsx-as-children) call `Children.map`:
```js {6,10}
import { Children } from 'react';
function RowList({ children }) {
return (
<div className="RowList">
{Children.map(children, child =>
<div className="Row">
{child}
</div>
)}
</div>
);
}
```
In the example above, the `RowList` wraps every child it receives into a `<div className="Row>` container. For example, let's say the parent component passes three `<p>` tags as the `children` prop to `RowList`:
```js
<RowList>
<p>This is the first item.</p>
<p>This is the second item.</p>
<p>This is the third item.</p>
</RowList>
```
Then, with the `RowList` implementation above, the final rendered result will look like this:
```js
<div className="RowList">
<div className="Row">
<p>This is the first item.</p>
</div>
<div className="Row">
<p>This is the second item.</p>
</div>
<div className="Row">
<p>This is the third item.</p>
</div>
</div>
```
`Children.map` is similar to [to transforming arrays with `map()`.](/learn/rendering-lists) The difference is that the `children` data structure is considered *opaque.* This means that even if it's sometimes an array, you should not assume it's an array or any other particular data type. This is why you should use `Children.map` if you need to transform it.
<Sandpack>
```js
import RowList from './RowList.js';
export default function App() {
return (
<RowList>
<p>This is the first item.</p>
<p>This is the second item.</p>
<p>This is the third item.</p>
</RowList>
);
}
```
```js RowList.js active
import { Children } from 'react';
export default function RowList({ children }) {
return (
<div className="RowList">
{Children.map(children, child =>
<div className="Row">
{child}
</div>
)}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
<DeepDive title="Why is the children prop not always an array?">
In React, the `children` prop is considered an *opaque* data structure. This means that you shouldn't rely on how it is structured. To transform, filter, or count children, you should use the `Children` methods.
In practice, the `children` data structure is often represented as an array internally. However, if there is only a single child, then React won't create an extra array since this would lead to unnecessary memory overhead. As long as you use the `Children` methods instead of directly introspecting the `children` prop, your code will not break even if React changes how the data structure is actually implemented.
Even when `children` is an array, `Children.map` has useful special behavior. For example, `Children.map` combines the [keys](/learn/rendering-lists#keeping-list-items-in-order-with-key) on the returned elements with the keys on the `children` you've passed to it. This ensures the original JSX children don't "lose" keys even if they get wrapped like in the example above.
</DeepDive>
<Gotcha>
The `children` data structure **does not include rendered output** of the components you pass as JSX. In the example below, the `children` received by the `RowList` only contains two items rather than three:
1. `<p>This is the first item.</p>`
2. `<MoreRows />`
This is why only two row wrappers are generated in this example:
<Sandpack>
```js
import RowList from './RowList.js';
export default function App() {
return (
<RowList>
<p>This is the first item.</p>
<MoreRows />
</RowList>
);
}
function MoreRows() {
return (
<>
<p>This is the second item.</p>
<p>This is the third item.</p>
</>
);
}
```
```js RowList.js
import { Children } from 'react';
export default function RowList({ children }) {
return (
<div className="RowList">
{Children.map(children, child =>
<div className="Row">
{child}
</div>
)}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
**There is no way to get the rendered output of an inner component** like `<MoreRows />` when manipulating `children`. This is why [it's usually better to use one of the alternative solutions.](#alternatives)
</Gotcha>
---
### Running some code for each child {/*running-some-code-for-each-child*/}
Call `Children.forEach` to iterate over each child in the `children` data structure. It does not return any value and is similar to the [array `forEach` method.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) You can use it to run custom logic like constructing your own array.
<Sandpack>
```js
import SeparatorList from './SeparatorList.js';
export default function App() {
return (
<SeparatorList>
<p>This is the first item.</p>
<p>This is the second item.</p>
<p>This is the third item.</p>
</SeparatorList>
);
}
```
```js SeparatorList.js active
import { Children } from 'react';
export default function SeparatorList({ children }) {
const result = [];
Children.forEach(children, (child, index) => {
result.push(child);
result.push(<hr key={index} />);
});
result.pop(); // Remove the last separator
return result;
}
```
</Sandpack>
<Gotcha>
As mentioned earlier, there is no way to get the rendered output of an inner component when manipulating `children`. This is why [it's usually better to use one of the alternative solutions.](#alternatives)
</Gotcha>
---
### Counting children {/*counting-children*/}
Call `Children.count(children)` to calculate the number of children.
<Sandpack>
```js
import RowList from './RowList.js';
export default function App() {
return (
<RowList>
<p>This is the first item.</p>
<p>This is the second item.</p>
<p>This is the third item.</p>
</RowList>
);
}
```
```js RowList.js active
import { Children } from 'react';
export default function RowList({ children }) {
return (
<div className="RowList">
<h1 className="RowListHeader">
Total rows: {Children.count(children)}
</h1>
{Children.map(children, child =>
<div className="Row">
{child}
</div>
)}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.RowListHeader {
padding-top: 5px;
font-size: 25px;
font-weight: bold;
text-align: center;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
<Gotcha>
As mentioned earlier, there is no way to get the rendered output of an inner component when manipulating `children`. This is why [it's usually better to use one of the alternative solutions.](#alternatives)
</Gotcha>
---
### Converting children to an array {/*converting-children-to-an-array*/}
Call `Children.toArray(children)` to turn the `children` data structure into a regular JavaScript array. This lets you manipulate the array with built-in array methods like [`filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), [`sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), or [`reverse`.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse)
<Sandpack>
```js
import ReversedList from './ReversedList.js';
export default function App() {
return (
<ReversedList>
<p>This is the first item.</p>
<p>This is the second item.</p>
<p>This is the third item.</p>
</ReversedList>
);
}
```
```js ReversedList.js active
import { Children } from 'react';
export default function ReversedList({ children }) {
const result = Children.toArray(children);
result.reverse();
return result;
}
```
</Sandpack>
<Gotcha>
As mentioned earlier, there is no way to get the rendered output of an inner component when manipulating `children`. This is why [it's usually better to use one of the alternative solutions.](#alternatives)
</Gotcha>
---
## Alternatives {/*alternatives*/}
### Exposing multiple components {/*exposing-multiple-components*/}
Manipulating children with the `Children` methods often leads to fragile code. When you pass children to a component in JSX, you don't usually expect the component to manipulate or transform the individual children.
When you can, try to avoid using the `Children` methods. For example, if you want every child of `RowList` to be wrapped in `<div className="Row">`, export a `Row` component, and manually wrap every row into it like this:
<Sandpack>
```js
import { RowList, Row } from './RowList.js';
export default function App() {
return (
<RowList>
<Row>
<p>This is the first item.</p>
</Row>
<Row>
<p>This is the second item.</p>
</Row>
<Row>
<p>This is the third item.</p>
</Row>
</RowList>
);
}
```
```js RowList.js
import { Children } from 'react';
export function RowList({ children }) {
return (
<div className="RowList">
{children}
</div>
);
}
export function Row({ children }) {
return (
<div className="Row">
{children}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
Unlike using `Children.map`, this approach does not wrap every child automatically. **However, this approach has a significant benefit compared to the [earlier example with `Children.map`](#transforming-children) because it works even if you keep extracting more components.** For example, it still works if you extract your own `MoreRows` component:
<Sandpack>
```js
import { RowList, Row } from './RowList.js';
export default function App() {
return (
<RowList>
<Row>
<p>This is the first item.</p>
</Row>
<MoreRows />
</RowList>
);
}
function MoreRows() {
return (
<>
<Row>
<p>This is the second item.</p>
</Row>
<Row>
<p>This is the third item.</p>
</Row>
</>
);
}
```
```js RowList.js
import { Children } from 'react';
export function RowList({ children }) {
return (
<div className="RowList">
{children}
</div>
);
}
export function Row({ children }) {
return (
<div className="Row">
{children}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
This wouldn't work with `Children.map` because it would "see" `<MoreRows />` as a single child (and a single row).
---
### Accepting an array of objects as a prop {/*accepting-an-array-of-objects-as-a-prop*/}
You can also explicitly pass an array as a prop. For example, this `RowList` accepts a `rows` array as a prop:
<Sandpack>
```js
import { RowList, Row } from './RowList.js';
export default function App() {
return (
<RowList rows={[
{ id: 'first', content: <p>This is the first item.</p> },
{ id: 'second', content: <p>This is the second item.</p> },
{ id: 'third', content: <p>This is the third item.</p> }
]} />
);
}
```
```js RowList.js
export function RowList({ rows }) {
return (
<div className="RowList">
{rows.map(row => (
<div className="Row" key={row.id}>
{row.content}
</div>
))}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
```
</Sandpack>
Since `rows` is a regular JavaScript array, the `RowList` component can use built-in array methods like [`map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on it.
This pattern is especially useful when you want to be able to pass more information as structured data together with children. In the below example, the `TabSwitcher` component receives an array of objects as the `tabs` prop:
<Sandpack>
```js
import TabSwitcher from './TabSwitcher.js';
export default function App() {
return (
<TabSwitcher tabs={[
{
id: 'first',
header: 'First',
content: <p>This is the first item.</p>
},
{
id: 'second',
header: 'Second',
content: <p>This is the second item.</p>
},
{
id: 'third',
header: 'Third',
content: <p>This is the third item.</p>
}
]} />
);
}
```
```js TabSwitcher.js
import { useState } from 'react';
export default function TabSwitcher({ tabs }) {
const [selectedId, setSelectedId] = useState(tabs[0].id);
const selectedTab = tabs.find(tab => tab.id === selectedId);
return (
<>
{tabs.map(tab => (
<button
key={tab.id}
onClick={() => setSelectedId(tab.id)}
>
{tab.header}
</button>
))}
<hr />
<div key={selectedId}>
<h3>{selectedTab.header}</h3>
{selectedTab.content}
</div>
</>
);
}
```
</Sandpack>
Unlike passing the children as JSX, this approach lets you associate some extra data like `header` with each item. Because you are working with the `tabs` directly, and it is an array, you do not need the `Children` methods.
---
### Calling a render prop to customize rendering {/*calling-a-render-prop-to-customize-rendering*/}
Instead of producing JSX for every single item, you can also pass a function that returns JSX, and call that function when necessary. In this example, the `App` component passes a `renderContent` function to the `TabSwitcher` component. The `TabSwitcher` component calls `renderContent` only for the selected tab:
<Sandpack>
```js
import TabSwitcher from './TabSwitcher.js';
export default function App() {
return (
<TabSwitcher
tabIds={['first', 'second', 'third']}
getHeader={tabId => {
return tabId[0].toUpperCase() + tabId.slice(1);
}}
renderContent={tabId => {
return <p>This is the {tabId} item.</p>;
}}
/>
);
}
```
```js TabSwitcher.js
import { useState } from 'react';
export default function TabSwitcher({ tabIds, getHeader, renderContent }) {
const [selectedId, setSelectedId] = useState(tabIds[0]);
return (
<>
{tabIds.map((tabId) => (
<button
key={tabId}
onClick={() => setSelectedId(tabId)}
>
{getHeader(tabId)}
</button>
))}
<hr />
<div key={selectedId}>
<h3>{getHeader(selectedId)}</h3>
{renderContent(selectedId)}
</div>
</>
);
}
```
</Sandpack>
A prop like `renderContent` is called a *render prop* because it is a prop that specifies how to render a piece of the user interface. However, there is nothing special about it: it is a regular prop which happens to be a function.
Render props are functions, so you can pass information to them. For example, this `RowList` component passes the `id` and the `index` of each row to the `renderRow` render prop, which uses `index` to highlight even rows:
<Sandpack>
```js
import { RowList, Row } from './RowList.js';
export default function App() {
return (
<RowList
rowIds={['first', 'second', 'third']}
renderRow={(id, index) => {
return (
<Row isHighlighted={index % 2 === 0}>
<p>This is the {id} item.</p>
</Row>
);
}}
/>
);
}
```
```js RowList.js
import { Fragment } from 'react';
export function RowList({ rowIds, renderRow }) {
return (
<div className="RowList">
<h1 className="RowListHeader">
Total rows: {rowIds.length}
</h1>
{rowIds.map((rowId, index) =>
<Fragment key={rowId}>
{renderRow(rowId, index)}
</Fragment>
)}
</div>
);
}
export function Row({ children, isHighlighted }) {
return (
<div className={[
'Row',
isHighlighted ? 'RowHighlighted' : ''
].join(' ')}>
{children}
</div>
);
}
```
```css
.RowList {
display: flex;
flex-direction: column;
border: 2px solid grey;
padding: 5px;
}
.RowListHeader {
padding-top: 5px;
font-size: 25px;
font-weight: bold;
text-align: center;
}
.Row {
border: 2px dashed black;
padding: 5px;
margin: 5px;
}
.RowHighlighted {
background: #ffa;
}
```
</Sandpack>
This is another example of how parent and child components can cooperate without manipulating the children.
---
## Reference {/*reference*/}
### `Children.count(children)` {/*children-count*/}
Call `Children.count(children)` to count the number of children in the `children` data structure.
```js RowList.js active
import { Children } from 'react';
function RowList({ children }) {
return (
<>
<h1>Total rows: {Children.count(children)}</h1>
...
</>
);
}
```
[See more examples above.](#counting-children)
#### Parameters {/*children-count-parameters*/}
* `children`: The value of the [`children` prop](/learn/passing-props-to-a-component#passing-jsx-as-children) received by your component.
#### Returns {/*children-count-returns*/}
The number of nodes inside these `children`.
#### Caveats {/*children-count-caveats*/}
- Empty nodes (`null`, `undefined`, and Booleans), strings, numbers, and [React elements](/apis/react/createElement) count as individual nodes. Arrays don't count as individual nodes, but their children do. **The traversal does not go deeper than React elements:** they don't get rendered, and their children aren't traversed. [Fragments](/apis/react/Fragment) don't get traversed.
---
### `Children.forEach(children, fn, thisArg?)` {/*children-foreach*/}
Call `Children.forEach(children, fn, thisArg?)` to run some code for each child in the `children` data structure.
```js RowList.js active
import { Children } from 'react';
function SeparatorList({ children }) {
const result = [];
Children.forEach(children, (child, index) => {
result.push(child);
result.push(<hr key={index} />);
});
// ...
```
[See more examples above.](#running-some-code-for-each-child)
#### Parameters {/*children-foreach-parameters*/}
* `children`: The value of the [`children` prop](/learn/passing-props-to-a-component#passing-jsx-as-children) received by your component.
* `fn`: The function you want to run for each child, similar to the [array `forEach` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) callback. It will be called with the child as the first argument and its index as the second argument. The index starts at `0` and increments on each call.
* **optional** `thisArg`: The [`this` value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this) with which the `fn` function should be called. If omitted, it's `undefined`.
#### Returns {/*children-foreach-returns*/}
`Children.forEach` returns `undefined`.
#### Caveats {/*children-foreach-caveats*/}
- Empty nodes (`null`, `undefined`, and Booleans), strings, numbers, and [React elements](/apis/react/createElement) count as individual nodes. Arrays don't count as individual nodes, but their children do. **The traversal does not go deeper than React elements:** they don't get rendered, and their children aren't traversed. [Fragments](/apis/react/Fragment) don't get traversed.
---
### `Children.map(children, fn, thisArg?)` {/*children-map*/}
Call `Children.map(children, fn, thisArg?)` to map or transform each child in the `children` data structure.
```js RowList.js active
import { Children } from 'react';
function RowList({ children }) {
return (
<div className="RowList">
{Children.map(children, child =>
<div className="Row">
{child}
</div>
)}
</div>
);
}
```
[See more examples above.](#transforming-children)
#### Parameters {/*children-map-parameters*/}
* `children`: The value of the [`children` prop](/learn/passing-props-to-a-component#passing-jsx-as-children) received by your component.
* `fn`: The mapping function, similar to the [array `map` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) callback. It will be called with the child as the first argument and its index as the second argument. The index starts at `0` and increments on each call. You need to return a React node from this function. This may be an empty node (`null`, `undefined`, or a Boolean), a string, a number, a React element, or an array of other React nodes.
* **optional** `thisArg`: The [`this` value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this) with which the `fn` function should be called. If omitted, it's `undefined`.
#### Returns {/*children-map-returns*/}
If `children` is `null` or `undefined`, returns the same value.
Otherwise, returns a flat array consisting of the nodes you've returned from the `fn` function. The returned array will contain all nodes you returned except for `null` and `undefined`.
#### Caveats {/*children-map-caveats*/}
- Empty nodes (`null`, `undefined`, and Booleans), strings, numbers, and [React elements](/apis/react/createElement) count as individual nodes. Arrays don't count as individual nodes, but their children do. **The traversal does not go deeper than React elements:** they don't get rendered, and their children aren't traversed. [Fragments](/apis/react/Fragment) don't get traversed.
- If you return an element or an array of elements with keys from `fn`, **the returned elements' keys will be automatically combined with the key of the corresponding original item from `children`.** When you return multiple elements from `fn` in an array, their keys only need to be unique locally amongst each other.
---
### `Children.only(children)` {/*children-only*/}
Call `Children.only(children)` to assert that `children` represent a single React element.
```js
function Box({ children }) {
const element = Children.only(children);
// ...
```
#### Parameters {/*children-only-parameters*/}
* `children`: The value of the [`children` prop](/learn/passing-props-to-a-component#passing-jsx-as-children) received by your component.
#### Returns {/*children-only-returns*/}
If `children` [is a valid element,](/apis/react/isValidElement) returns that element.
Otherwise, throws an error.
#### Caveats {/*children-only-caveats*/}
- This method always **throws if you pass an array (such as the return value of `Children.map`) as `children`.** In other words, it enforces that `children` is a single React element, not that it's an array with a single element.
---
### `Children.toArray(children)` {/*children-toarray*/}
Call `Children.toArray(children)` to create an array out of the `children` data structure.
```js ReversedList.js active
import { Children } from 'react';
export default function ReversedList({ children }) {
const result = Children.toArray(children);
result.reverse();
// ...
```
#### Parameters {/*children-toarray-parameters*/}
* `children`: The value of the [`children` prop](/learn/passing-props-to-a-component#passing-jsx-as-children) received by your component.
#### Returns {/*children-toarray-returns*/}
Returns a flat array of elements in `children`.
#### Caveats {/*children-toarray-caveats*/}
- Empty nodes (`null`, `undefined`, and Booleans) will be omitted in the returned array. **The returned elements' keys will be calculated from the original elements' keys and their level of nesting and position.** This ensures that flattening the array does not introduce changes in behavior.
---
## Troubleshooting {/*troubleshooting*/}
### I pass a custom component, but the `Children` methods don't show its render result {/*i-pass-a-custom-component-but-the-children-methods-dont-show-its-render-result*/}
Suppose you pass two children to `RowList` like this:
```js
<RowList>
<p>First item</p>
<MoreRows />
</RowList>
```
If you do `Children.count(children)` inside `RowList`, you will get `2`. Even if `MoreRows` renders 10 different items, or if it returns `null`, `Children.count(children)` will still be `2`. From the `RowList`'s perspective, it only "sees" the JSX it has received. It does not "see" the internals of the `MoreRows` component.
The limitation makes it hard to extract a component. This is why [alternatives](#alternatives) are preferred to using `Children`.

3
beta/src/sidebarReference.json
View File

@ -13,8 +13,7 @@
"routes": [ "routes": [
{ {
"title": "Children", "title": "Children",
"path": "/apis/react/Children", "path": "/apis/react/Children"
"wip": true
}, },
{ {
"title": "cloneElement", "title": "cloneElement",

Write Preview
Loading…
Cancel
Save