Your age is {ageAsNumber}.<\/p> } <\/> ); } Show more PitfallIf you pass value without onChange, it will be impossible to type into the input. When you control an input by passing some value to it, you force it to always have the value you passed. So if you pass a state variable as a value but forget to update that state variable synchronously during the onChange event handler, React will revert the input after every keystroke back to the value that you specified. Optimizing re-rendering on every keystroke When you use a controlled input, you set the state on every keystroke. If the component containing your state re-renders a large tree, this can get slow. There’s a few ways you can optimize re-rendering performance. For example, suppose you start with a form that re-renders all page content on every keystroke: function App() { const [firstName, setFirstName] = useState(''); return ( <> setFirstName(e.target.value)} \/> <\/form> <\/> );} Since doesn’t rely on the input state, you can move the input state into its own component: function App() { return ( <> <\/> );}function SignupForm() { const [firstName, setFirstName] = useState(''); return ( setFirstName(e.target.value)} \/> <\/form> );} This significantly improves performance because now only SignupForm re-renders on every keystroke. If there is no way to avoid re-rendering (for example, if PageContent depends on the search input’s value), useDeferredValue lets you keep the controlled input responsive even in the middle of a large re-render. Troubleshooting My text input doesn’t update when I type into it If you render an input with value but no onChange, you will see an error in the console: \/\/ 🔴 Bug: controlled text input with no onChange handler ConsoleYou provided a value prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultValue. Otherwise, set either onChange or readOnly. As the error message suggests, if you only wanted to specify the initial value, pass defaultValue instead: \/\/ ✅ Good: uncontrolled input with an initial value If you want to control this input with a state variable, specify an onChange handler: \/\/ ✅ Good: controlled input with onChange setSomething(e.target.value)} \/> If the value is intentionally read-only, add a readOnly prop to suppress the error: \/\/ ✅ Good: readonly controlled input without on change My checkbox doesn’t update when I click on it If you render a checkbox with checked but no onChange, you will see an error in the console: \/\/ 🔴 Bug: controlled checkbox with no onChange handler ConsoleYou provided a checked prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultChecked. Otherwise, set either onChange or readOnly. As the error message suggests, if you only wanted to specify the initial value, pass defaultChecked instead: \/\/ ✅ Good: uncontrolled checkbox with an initial value If you want to control this checkbox with a state variable, specify an onChange handler: \/\/ ✅ Good: controlled checkbox with onChange setSomething(e.target.checked)} \/> PitfallYou need to read e.target.checked rather than e.target.value for checkboxes. If the checkbox is intentionally read-only, add a readOnly prop to suppress the error: \/\/ ✅ Good: readonly controlled input without on change My input caret jumps to the beginning on every keystroke If you control an input, you must update its state variable to the input’s value from the DOM during onChange. You can’t update it to something other than e.target.value (or e.target.checked for checkboxes): function handleChange(e) { \/\/ 🔴 Bug: updating an input to something other than e.target.value setFirstName(e.target.value.toUpperCase());} You also can’t update it asynchronously: function handleChange(e) { \/\/ 🔴 Bug: updating an input asynchronously setTimeout(() => { setFirstName(e.target.value); }, 100);} To fix your code, update it synchronously to e.target.value: function handleChange(e) { \/\/ ✅ Updating a controlled input to e.target.value synchronously setFirstName(e.target.value);} If this doesn’t fix the problem, it’s possible that the input gets removed and re-added from the DOM on every keystroke. This can happen if you’re accidentally resetting state on every re-render, for example if the input or one of its parents always receives a different key attribute, or if you nest component function definitions (which is not supported and causes the “inner” component to always be considered a different tree). I’m getting an error: “A component is changing an uncontrolled input to be controlled” If you provide a value to the component, it must remain a string throughout its lifetime. You cannot pass value={undefined} first and later pass value="some string" because React won’t know whether you want the component to be uncontrolled or controlled. A controlled component should always receive a string value, not null or undefined. If your value is coming from an API or a state variable, it might be initialized to null or undefined. In that case, either set it to an empty string ('') initially, or pass value={someValue ?? ''} to ensure value is a string. Similarly, if you pass checked to a checkbox, ensure it’s always a boolean.PreviousNext

{child} <\/div>); Reference Children.count(children) Children.forEach(children, fn, thisArg?) Children.map(children, fn, thisArg?) Children.only(children) Children.toArray(children) Usage Transforming children Running some code for each child Counting children Converting children to an array Alternatives Exposing multiple components Accepting an array of objects as a prop Calling a render prop to customize rendering Troubleshooting I pass a custom component, but the Children methods don’t show its render result Reference Children.count(children) Call Children.count(children) to count the number of children in the children data structure. import { Children } from 'react';function RowList({ children }) { return ( <>

Total rows: {Children.count(children)}<\/h1> ... <\/> );} See more examples below. Parameters children: The value of the children prop received by your component. Returns The number of nodes inside these children. Caveats Empty nodes (null, undefined, and Booleans), strings, numbers, and React elements 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 don’t get traversed. Children.forEach(children, fn, thisArg?) Call Children.forEach(children, fn, thisArg?) to run some code for each child in the children data structure. import { Children } from 'react';function SeparatorList({ children }) { const result = []; Children.forEach(children, (child, index) => { result.push(child); result.push(
); }); \/\/ ... See more examples below. Parameters children: The value of the children prop received by your component. fn: The function you want to run for each child, similar to the array forEach method 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 with which the fn function should be called. If omitted, it’s undefined. Returns Children.forEach returns undefined. Caveats Empty nodes (null, undefined, and Booleans), strings, numbers, and React elements 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 don’t get traversed. Children.map(children, fn, thisArg?) Call Children.map(children, fn, thisArg?) to map or transform each child in the children data structure. import { Children } from 'react';function RowList({ children }) { return (
{Children.map(children, child =>
{child} <\/div> )} <\/div> );} See more examples below. Parameters children: The value of the children prop received by your component. fn: The mapping function, similar to the array map method 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 with which the fn function should be called. If omitted, it’s undefined. 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 Empty nodes (null, undefined, and Booleans), strings, numbers, and React elements 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 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) Call Children.only(children) to assert that children represent a single React element. function Box({ children }) { const element = Children.only(children); \/\/ ... Parameters children: The value of the children prop received by your component. Returns If children is a valid element, returns that element. Otherwise, throws an error. 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) Call Children.toArray(children) to create an array out of the children data structure. import { Children } from 'react';export default function ReversedList({ children }) { const result = Children.toArray(children); result.reverse(); \/\/ ... Parameters children: The value of the children prop received by your component. Returns Returns a flat array of elements in children. 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. Usage Transforming children To transform the children JSX that your component receives as the children prop, call Children.map: import { Children } from 'react';function RowList({ children }) { return (
{Children.map(children, child =>
{child} <\/div> )} <\/div> );} In the example above, the RowList wraps every child it receives into a
container. For example, let’s say the parent component passes three
tags as the children prop to RowList:
This is the first item.<\/p>
This is the second item.<\/p>
This is the third item.<\/p><\/RowList> Then, with the RowList implementation above, the final rendered result will look like this:

This is the first item.<\/p> <\/div>

This is the second item.<\/p> <\/div>

This is the third item.<\/p> <\/div><\/div> Children.map is similar to to transforming arrays with map(). 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. App.jsRowList.jsRowList.jsReloadClearForkimport { Children } from 'react'; export default function RowList({ children }) { return (
{Children.map(children, child =>
{child} <\/div> )} <\/div> ); } Deep DiveWhy is the children prop not always an array? Show DetailsIn 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 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. PitfallThe 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:
This is the first item.<\/p> This is why only two row wrappers are generated in this example:App.jsRowList.jsApp.jsReloadClearForkimport RowList from '.\/RowList.js'; export default function App() { return (
This is the first item.<\/p> <\/RowList> ); } function MoreRows() { return ( <>
This is the second item.<\/p>
This is the third item.<\/p> <\/> ); } Show moreThere is no way to get the rendered output of an inner component like when manipulating children. This is why it’s usually better to use one of the alternative solutions. 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. You can use it to run custom logic like constructing your own array. App.jsSeparatorList.jsSeparatorList.jsReloadClearForkimport { Children } from 'react'; export default function SeparatorList({ children }) { const result = []; Children.forEach(children, (child, index) => { result.push(child); result.push(
); }); result.pop(); \/\/ Remove the last separator return result; } PitfallAs 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. Counting children Call Children.count(children) to calculate the number of children. App.jsRowList.jsRowList.jsReloadClearForkimport { Children } from 'react'; export default function RowList({ children }) { return (

Total rows: {Children.count(children)} <\/h1> {Children.map(children, child =>
{child} <\/div> )} <\/div> ); } Show more PitfallAs 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. 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, sort, or reverse. App.jsReversedList.jsReversedList.jsReloadClearForkimport { Children } from 'react'; export default function ReversedList({ children }) { const result = Children.toArray(children); result.reverse(); return result; } PitfallAs 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 NoteThis section describes alternatives to the Children API (with capital C) that’s imported like this:import { Children } from 'react';Don’t confuse it with using the children prop (lowercase c), which is good and encouraged. 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
, export a Row component, and manually wrap every row into it like this: App.jsRowList.jsApp.jsReloadClearForkimport { RowList, Row } from '.\/RowList.js'; export default function App() { return (
This is the first item.<\/p> <\/Row>
This is the second item.<\/p> <\/Row>
This is the third item.<\/p> <\/Row> <\/RowList> ); } Show more 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 because it works even if you keep extracting more components. For example, it still works if you extract your own MoreRows component: App.jsRowList.jsApp.jsReloadClearForkimport { RowList, Row } from '.\/RowList.js'; export default function App() { return (
This is the first item.<\/p> <\/Row> <\/RowList> ); } function MoreRows() { return ( <>
This is the second item.<\/p> <\/Row>
This is the third item.<\/p> <\/Row> <\/> ); } Show more This wouldn’t work with Children.map because it would “see” as a single child (and a single row). 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: App.jsRowList.jsApp.jsReloadClearForkimport { RowList, Row } from '.\/RowList.js'; export default function App() { return ( This is the first item.<\/p> }, { id: 'second', content:
This is the second item.<\/p> }, { id: 'third', content:
This is the third item.<\/p> } ]} \/> ); } Since rows is a regular JavaScript array, the RowList component can use built-in array methods like 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: App.jsTabSwitcher.jsApp.jsReloadClearForkimport TabSwitcher from '.\/TabSwitcher.js'; export default function App() { return ( This is the first item.<\/p> }, { id: 'second', header: 'Second', content:
This is the second item.<\/p> }, { id: 'third', header: 'Third', content:
This is the third item.<\/p> } ]} \/> ); } Show more 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 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: App.jsTabSwitcher.jsApp.jsReloadClearForkimport TabSwitcher from '.\/TabSwitcher.js'; export default function App() { return ( { return tabId[0].toUpperCase() + tabId.slice(1); }} renderContent={tabId => { return
This is the {tabId} item.<\/p>; }} \/> ); } 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: App.jsRowList.jsApp.jsReloadClearForkimport { RowList, Row } from '.\/RowList.js'; export default function App() { return ( { return (
This is the {id} item.<\/p> <\/Row> ); }} \/> ); } Show more This is another example of how parent and child components can cooperate without manipulating the children. Troubleshooting I pass a custom component, but the Children methods don’t show its render result Suppose you pass two children to RowList like this:
First item<\/p> <\/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 are preferred to using Children.PreviousLegacy React APIsNextcloneElement ``` Children ``` Pattern 3: Deep DiveWhy is the children prop not always an array? Show DetailsIn 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 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. PitfallThe 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:
This is the first item.<\/p> This is why only two row wrappers are generated in this example:App.jsRowList.jsApp.jsReloadClearForkimport RowList from '.\/RowList.js'; export default function App() { return (
This is the first item.<\/p> <\/RowList> ); } function MoreRows() { return ( <>
This is the second item.<\/p>
This is the third item.<\/p> <\/> ); } Show moreThere is no way to get the rendered output of an inner component like when manipulating children. This is why it’s usually better to use one of the alternative solutions. 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. You can use it to run custom logic like constructing your own array. ``` children ``` Pattern 4: Learn ReactEscape HatchesManipulating the DOM with RefsReact automatically updates the DOM to match your render output, so your components won’t often need to manipulate it. However, sometimes you might need access to the DOM elements managed by React—for example, to focus a node, scroll to it, or measure its size and position. There is no built-in way to do those things in React, so you will need a ref to the DOM node. You will learn How to access a DOM node managed by React with the ref attribute How the ref JSX attribute relates to the useRef Hook How to access another component’s DOM node In which cases it’s safe to modify the DOM managed by React Getting a ref to the node To access a DOM node managed by React, first, import the useRef Hook: import { useRef } from 'react'; Then, use it to declare a ref inside your component: const myRef = useRef(null); Finally, pass your ref as the ref attribute to the JSX tag for which you want to get the DOM node:
The useRef Hook returns an object with a single property called current. Initially, myRef.current will be null. When React creates a DOM node for this
, React will put a reference to this node into myRef.current. You can then access this DOM node from your event handlers and use the built-in browser APIs defined on it. \/\/ You can use any browser APIs, for example:myRef.current.scrollIntoView(); Example: Focusing a text input In this example, clicking the button will focus the input: App.jsApp.jsReloadClearForkimport { useRef } from 'react'; export default function Form() { const inputRef = useRef(null); function handleClick() { inputRef.current.focus(); } return ( <>

react-19