**If your app is fully built with React, you shouldn't need to create any more roots, or to call [`root.render`](#root-render) again.**
From this point on, React will manage the DOM of your entire app. To add more components, [nest them inside the `App` component.](/learn/importing-and-exporting-components) When you need to update the UI, each of your components can do this by [using state](/apis/react/useState). When you need to display extra content like a modal or a tooltip outside the DOM node, [render it with a portal.](/apis/react-dom/createPortal)
From this point on, React will manage the DOM of your entire app. To add more components, [nest them inside the `App` component.](/learn/importing-and-exporting-components) When you need to update the UI, each of your components can do this by [using state.](/apis/react/useState) When you need to display extra content like a modal or a tooltip outside the DOM node, [render it with a portal.](/apis/react-dom/createPortal)
<Note>
@ -106,7 +106,7 @@ This can feel very slow! To solve this, you can generate the initial HTML from y
### Rendering a page partially built with React {/*rendering-a-page-partially-built-with-react*/}
If your page [isn't fully built with React](/learn/add-react-to-a-website), you can call `createRoot` multiple times to create a root for each top-level piece of UI managed by React. You can display different content in each root by calling [`root.render`](#root-render).
If your page [isn't fully built with React](/learn/add-react-to-a-website), you can call `createRoot` multiple times to create a root for each top-level piece of UI managed by React. You can display different content in each root by calling [`root.render`.](#root-render)
Here, two different React components are rendered into two DOM nodes defined in the `index.html` file:
@ -185,7 +185,7 @@ root.render(<Comment />);
document.body.appendChild(domNode); // You can add it anywhere in the document
```
To remove the React tree from the DOM node and clean up all the resources used by it, call [`root.unmount`](#root-unmount).
To remove the React tree from the DOM node and clean up all the resources used by it, call [`root.unmount`.](#root-unmount)
```js
root.unmount();
@ -197,7 +197,7 @@ This is mostly useful if your React components are inside an app written in a di
### Updating a root component {/*updating-a-root-component*/}
You can call `render` more than once on the same root. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state](/learn/preserving-and-resetting-state). Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
You can call `render` more than once on the same root. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state.](/learn/preserving-and-resetting-state) Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
<Sandpack>
@ -255,15 +255,15 @@ An app fully built with React will usually only have one `createRoot` call for i
#### Parameters {/*parameters*/}
* `domNode`: A [DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element). React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* **optional**`options`: A object contain options for this React root.
* `onRecoverableError`: optional callback called when React automatically recovers from errors.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`](/apis/react/useId). Useful to avoid conflicts when using multiple roots on the same page.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page.
#### Returns {/*returns*/}
`createRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`](#root-unmount).
`createRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`.](#root-unmount)
#### Caveats {/*caveats*/}
* If your app is server-rendered, using `createRoot()` is not supported. Use [`hydrateRoot()`](/apis/react-dom/client/hydrateRoot) instead.
`hydrateRoot` lets you display React components inside a browser DOM node whose HTML content was previously generated by [`react-dom/server`](/apis/react-dom/server).
`hydrateRoot` lets you display React components inside a browser DOM node whose HTML content was previously generated by [`react-dom/server`.](/apis/react-dom/server)
You shouldn't need to call `hydrateRoot` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state](/apis/react/useState).
You shouldn't need to call `hydrateRoot` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state.](/apis/react/useState)
<Gotcha>
@ -100,7 +100,7 @@ React can recover from some hydration errors, but **you must fix them like other
After the root has finished hydrating, you can call [`root.render`](#root-render) to update the root React component. **Unlike with [`createRoot`](/apis/react-dom/client/createRoot), you don't usually need to do this because the initial content was already rendered as HTML.**
If you call `root.render` at some point after hydration, and the component tree structure matches up with what was previously rendered, React will [preserve the state](/learn/preserving-and-resetting-state). Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
If you call `root.render` at some point after hydration, and the component tree structure matches up with what was previously rendered, React will [preserve the state.](/learn/preserving-and-resetting-state) Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
<Sandpack>
@ -170,11 +170,11 @@ React will attach to the HTML that exists inside the `domNode`, and take over ma
* **optional**`options`: A object contain options for this React root.
* `onRecoverableError`: optional callback called when React automatically recovers from errors.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`](/apis/react/useId). Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as used on the server.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as used on the server.
#### Returns {/*returns*/}
`hydrateRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`](#root-unmount).
`hydrateRoot` returns an object with two methods: [`render`](#root-render) and [`unmount`.](#root-unmount)
#### Caveats {/*caveats*/}
* `hydrateRoot()` expects the rendered content to be identical with the server-rendered content. You should treat mismatches as bugs and fix them.
This section is incomplete, please see the old docs for [findDOMNode](https://reactjs.org/docs/react-dom.html#finddomnode).
This section is incomplete, please see the old docs for [findDOMNode.](https://reactjs.org/docs/react-dom.html#finddomnode)
</Wip>
@ -23,6 +23,6 @@ findDOMNode(component)
<Gotcha>
`findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in StrictMode](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage).
`findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in StrictMode.](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
In React 18, `hydrate` was replaced by [`hydrateRoot`](/apis/react-dom/client/hydrateRoot). Using `hydrate` in React 18 will warn that your app will behave as if it’s running React 17. Learn more [here](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis).
In React 18, `hydrate` was replaced by [`hydrateRoot`.](/apis/react-dom/client/hydrateRoot) Using `hydrate` in React 18 will warn that your app will behave as if it’s running React 17. Learn more [here.](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis)
</Gotcha>
@ -65,9 +65,9 @@ export default function App() {
</Sandpack>
Usually you shouldn't need to call `hydrate` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state](/apis/react/useState).
Usually you shouldn't need to call `hydrate` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state.](/apis/react/useState)
For more information on hydration, see the docs for [`hydrateRoot`](/apis/react-dom/client/hydrateRoot).
For more information on hydration, see the docs for [`hydrateRoot`.](/apis/react-dom/client/hydrateRoot)
In React 18, `render` was replaced by [`createRoot`](/apis/react-dom/client/createRoot). Using `render` in React 18 will warn that your app will behave as if it’s running React 17. Learn more [here](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis).
In React 18, `render` was replaced by [`createRoot`.](/apis/react-dom/client/createRoot) Using `render` in React 18 will warn that your app will behave as if it’s running React 17. Learn more [here.](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis)
</Gotcha>
@ -56,7 +56,7 @@ export default function App() {
</Sandpack>
Usually you shouldn't need to call `render` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state](/apis/react/useState).
Usually you shouldn't need to call `render` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state.](/apis/react/useState)
---
@ -132,13 +132,13 @@ nav ul li { display: inline-block; margin-right: 20px; }
</Sandpack>
You can destroy the rendered trees with [`unmountComponentAtNode()`](/apis/react-dom/unmountComponentAtNode).
You can destroy the rendered trees with [`unmountComponentAtNode()`.](/apis/react-dom/unmountComponentAtNode)
---
### Updating the rendered tree {/*updating-the-rendered-tree*/}
You can call `render` more than once on the same DOM node. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state](/learn/preserving-and-resetting-state). Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
You can call `render` more than once on the same DOM node. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state.](/learn/preserving-and-resetting-state) Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
<Sandpack>
@ -195,7 +195,7 @@ An app fully built with React will usually only have one `render` call with its
* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like `<App />`, but you can also pass a React element constructed with [`createElement()`](/TODO), a string, a number, `null`, or `undefined`.
* `domNode`: A [DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element). React will display the `reactNode` you pass inside this DOM element. From this moment, React will manage the DOM inside the `domNode` and update it when your React tree changes.
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will display the `reactNode` you pass inside this DOM element. From this moment, React will manage the DOM inside the `domNode` and update it when your React tree changes.
* **optional**`callback`: A function. If passed, React will call it after your component is placed into the DOM.
@ -206,7 +206,7 @@ An app fully built with React will usually only have one `render` call with its
#### Caveats {/*caveats*/}
* In React 18, `render` was replaced by [`createRoot`](/apis/react-dom/client/createRoot). Please use for React 18 and beyond.
* In React 18, `render` was replaced by [`createRoot`.](/apis/react-dom/client/createRoot) Please use for React 18 and beyond.
* The first time you call `render`, React will clear all the existing HTML content inside the `domNode` before rendering the React component into it. If your `domNode` contains HTML generated by React on the server or during the build, use [`hydrate()`](/TODO) instead, which attaches the event handlers to the existing HTML.
This section is incomplete, please see the old docs for [renderToPipeableStream](https://reactjs.org/docs/react-dom-server.html#rendertopipeablestream).
This section is incomplete, please see the old docs for [renderToPipeableStream.](https://reactjs.org/docs/react-dom-server.html#rendertopipeablestream)
This section is incomplete, please see the old docs for [renderToReadableStream](https://reactjs.org/docs/react-dom-server.html#rendertoreadablestream).
This section is incomplete, please see the old docs for [renderToReadableStream.](https://reactjs.org/docs/react-dom-server.html#rendertoreadablestream)
</Wip>
<Intro>
Streams a React element to its initial HTML. Returns a Promise that resolves to a [Readable Stream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream). Fully supports Suspense and streaming of HTML. [Read more](https://github.com/reactwg/react-18/discussions/127)
Streams a React element to its initial HTML. Returns a Promise that resolves to a [Readable Stream.](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) Fully supports Suspense and streaming of HTML. [Read more](https://github.com/reactwg/react-18/discussions/127)
This section is incomplete, please see the old docs for [renderToStaticNodeStream](https://reactjs.org/docs/react-dom-server.html#rendertostaticnodestream).
This section is incomplete, please see the old docs for [renderToStaticNodeStream.](https://reactjs.org/docs/react-dom-server.html#rendertostaticnodestream)
@ -104,4 +104,4 @@ Wrap elements in `<React.Fragment>` to group them together in situations where y
#### Props {/*reference-props*/}
- **optional**`key`: Fragments declared with the explicit `<React.Fragment>` syntax may have [keys](https://beta.reactjs.org/learn/rendering-lists#keeping-list-items-in-order-with-key).
- **optional**`key`: Fragments declared with the explicit `<React.Fragment>` syntax may have [keys.](https://beta.reactjs.org/learn/rendering-lists#keeping-list-items-in-order-with-key)
This section is incomplete, please see the old docs for [React](https://reactjs.org/docs/react-api.html).
This section is incomplete, please see the old docs for [React.](https://reactjs.org/docs/react-api.html)
</Wip>
<Intro>
The React package contains all the APIs necessary to define and use [components](/learn/your-first-component).
The React package contains all the APIs necessary to define and use [components.](/learn/your-first-component)
</Intro>
## Installation {/*installation*/}
It is available as [`react`](https://www.npmjs.com/package/react) on npm. You can also [add React to the page as a `<script>` tag](/learn/add-react-to-a-website).
It is available as [`react`](https://www.npmjs.com/package/react) on npm. You can also [add React to the page as a `<script>` tag.](/learn/add-react-to-a-website)
<PackageImport>
@ -36,7 +36,7 @@ import * as React from 'react';
</PackageImport>
If you use React on the web, you'll also need the same version of [ReactDOM](/apis/react-dom).
If you use React on the web, you'll also need the same version of [ReactDOM.](/apis/react-dom)
@ -21,7 +21,7 @@ const value = useContext(SomeContext)
### Passing data deeply into the tree {/*passing-data-deeply-into-the-tree*/}
Call `useContext` at the top level of your component to read and subscribe to [context](/learn/passing-data-deeply-with-context).
Call `useContext` at the top level of your component to read and subscribe to [context.](/learn/passing-data-deeply-with-context)
```js [[2, 4, "theme"], [1, 4, "ThemeContext"]]
import { useContext } from 'react';
@ -145,7 +145,7 @@ function Button({ children }) {
### Updating data passed via context {/*updating-data-passed-via-context*/}
Often, you'll want the context to change over time. To update context, you need to combine it with [state](/apis/react/useState). Declare a state variable in the parent component, and pass the current state down as the <CodeStepstep={2}>context value</CodeStep> to the provider.
Often, you'll want the context to change over time. To update context, you need to combine it with [state.](/apis/react/useState) Declare a state variable in the parent component, and pass the current state down as the <CodeStepstep={2}>context value</CodeStep> to the provider.
@ -267,7 +267,7 @@ function Button({ children }) {
</Sandpack>
Note that `value="dark"` passes the `"dark"` string, but `value={theme}` passes the value of the JavaScript `theme` variable with [JSX curly braces](/learn/javascript-in-jsx-with-curly-braces). Curly braces also let you pass context values that aren't strings.
Note that `value="dark"` passes the `"dark"` string, but `value={theme}` passes the value of the JavaScript `theme` variable with [JSX curly braces.](/learn/javascript-in-jsx-with-curly-braces) Curly braces also let you pass context values that aren't strings.
<Solution/>
@ -923,7 +923,7 @@ If React can't find any providers of that particular <CodeStep step={1}>context<
const ThemeContext = createContext(null);
```
The default value **never changes**. If you want to update context, use it with state as [described above](#updating-data-passed-via-context).
The default value **never changes**. If you want to update context, use it with state as [described above.](#updating-data-passed-via-context)
Often, instead of `null`, there is some more meaningful value you can use as a default, for example:
@ -1279,7 +1279,7 @@ function MyApp() {
Here, the <CodeStepstep={2}>context value</CodeStep> is a JavaScript object with two properties, one of which is a function. Whenever `MyApp` re-renders (for example, on a route update), this will be a *different* object pointing at a *different* function, so React will also have to re-render all components deep in the tree that call `useContext(AuthContext)`.
In smaller apps, this is not a problem. However, there is no need to re-render them if the underlying data, like `currentUser`, has not changed. To help React take advantage of that fact, you may wrap the `login` function with [`useCallback`](/apis/react/usecallback) and wrap the object creation into [`useMemo`](/apis/usememo). This is a performance optimization:
In smaller apps, this is not a problem. However, there is no need to re-render them if the underlying data, like `currentUser`, has not changed. To help React take advantage of that fact, you may wrap the `login` function with [`useCallback`](/apis/react/usecallback) and wrap the object creation into [`useMemo`.](/apis/usememo) This is a performance optimization:
```js {1,6-9,11-14}
import { useCallback, useMemo } from 'react';
@ -1305,7 +1305,7 @@ function MyApp() {
}
```
The `login` function does not use any information from the render scope, so you can specify an empty array of dependencies. The `contextValue` object consists of `currentUser` and `login`, so it needs to list both as dependencies. As a result of this change, the components calling `useContext(AuthProvider)` won't need to re-render unless `currentUser` changes. Read more about [skipping re-renders with memoization](TODO:/learn/skipping-unchanged-trees).
The `login` function does not use any information from the render scope, so you can specify an empty array of dependencies. The `contextValue` object consists of `currentUser` and `login`, so it needs to list both as dependencies. As a result of this change, the components calling `useContext(AuthProvider)` won't need to re-render unless `currentUser` changes. Read more about [skipping re-renders with memoization.](TODO:/learn/skipping-unchanged-trees)
---
@ -1313,7 +1313,7 @@ The `login` function does not use any information from the render scope, so you
### `useContext(SomeContext)` {/*usecontext*/}
Call `useContext` at the top level of your component to read and subscribe to [context](/learn/passing-data-deeply-with-context).
Call `useContext` at the top level of your component to read and subscribe to [context.](/learn/passing-data-deeply-with-context)
```js
import { useContext } from 'react';
@ -1327,7 +1327,7 @@ function MyComponent() {
#### Parameters {/*parameters*/}
* `SomeContext`: The context that you've previously created with [`createContext`](/apis/react/useContext). The context itself does not hold the information, it only represents the kind of information you can provide or read from components.
* `SomeContext`: The context that you've previously created with [`createContext`.](/apis/react/useContext) The context itself does not hold the information, it only represents the kind of information you can provide or read from components.
#### Returns {/*returns*/}
@ -1348,7 +1348,7 @@ function MyComponent() {
There are a few common ways that this can happen:
1. You're rendering `<SomeContext.Provider>` in the same component (or below) as where you're calling `useContext()`. Move `<SomeContext.Provider>`*above and outside* the component calling `useContext()`.
2. You may have forgotten to wrap your component with `<SomeContext.Provider>`, or you might have put it in a different part of the tree than you thought. Check whether the hierarchy is right using [React DevTools](/learn/react-developer-tools).
2. You may have forgotten to wrap your component with `<SomeContext.Provider>`, or you might have put it in a different part of the tree than you thought. Check whether the hierarchy is right using [React DevTools.](/learn/react-developer-tools)
3. You might be running into some build issue with your tooling that causes `SomeContext` as seen from the providing component and `SomeContext` as seen by the reading component to be two different objects. This can happen if you use symlinks, for example. You can verify this by assigning them to globals like `window.SomeContext1` and `window.SomeContext2` and then checking whether `window.SomeContext1 === window.SomeContext2` in the console. If they're not the same, you need to fix that issue on the build tool level.
### I am always getting `undefined` from my context although the default value is different {/*i-am-always-getting-undefined-from-my-context-although-the-default-value-is-different*/}
@ -1035,7 +1035,7 @@ You can use a similar approach to prevent [`useEffect`](/api/react/useEffect) fr
### Memoizing a function {/*memoizing-a-function*/}
Suppose the `Form` component is wrapped in [`memo`](/api/react/memo). You want to pass a function to it as a prop:
Suppose the `Form` component is wrapped in [`memo`.](/api/react/memo) You want to pass a function to it as a prop:
```js {2-4}
export default function Page({ productId }) {
@ -1081,7 +1081,7 @@ The two examples above are completely equivalent. The only benefit to `useCallba
Wrapping an object in `useMemo` or a function in `useCallback` is only strictly necessary in two cases:
- You pass it as a prop to a component wrapped in [`memo`](/apis/react/memo). You want to skip re-rendering if the value hasn't changed. Memoization lets your component re-render only when dependencies are the same.
- You pass it as a prop to a component wrapped in [`memo`.](/apis/react/memo) You want to skip re-rendering if the value hasn't changed. Memoization lets your component re-render only when dependencies are the same.
- The value you're passing is later used as a dependency of some Hook. For example, maybe another `useMemo` calculation value depends on it. Or maybe you are depending on this value from [`useEffect.`](/apis/react/useEffect)
There is no benefit to wrapping in `useMemo` and `useCallback` in other cases. There is no significant harm to doing that either, so some teams choose to not think about individual cases, and memoize as much as possible. The downside of this approach is that code becomes less readable. Also, not all memoization is effective: a single value that's "always new" is enough to break memoization for an entire component. This approach is mostly useful for apps that update state many times per second or show a lot of data.
@ -1135,7 +1135,7 @@ During subsequent renders, it will either return an already stored value from th
#### Caveats {/*caveats*/}
* `useMemo` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it.
* In Strict Mode, React will **call your calculation function twice** in order to [help you find accidental impurities](#my-calculation-runs-twice-on-every-re-render). This is development-only behavior and does not affect production. If your calculation function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
* In Strict Mode, React will **call your calculation function twice** in order to [help you find accidental impurities.](#my-calculation-runs-twice-on-every-re-render) This is development-only behavior and does not affect production. If your calculation function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
* React **will not throw away the cached value unless there is a specific reason to do that.** For example, in development, React throws away the cache when you edit the file of your component. Both in development and in production, React will throw away the cache if your component suspends during the initial mount. In the future, React may add more features that take advantage of throwing away the cache--for example, if React adds built-in support for virtualized lists in the future, it would make sense to throw away the cache for items that scroll out of the virtualized table viewport. This should match your expectations if you rely on `useMemo` solely as a performance optimization. Otherwise, a [state variable](apis/react/useState#avoiding-recreating-the-initial-state) or a [ref](/apis/react/useRef#avoiding-recreating-the-ref-contents) may be more appropriate.
---
@ -1160,7 +1160,7 @@ function TodoList({ todos, tab }) {
This is expected and shouldn't break your code.
This **development-only** behavior helps you [keep components pure](/learn/keeping-components-pure). React uses the result of one of the calls, and ignores the result of the other call. As long as your component and calculation functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
This **development-only** behavior helps you [keep components pure.](/learn/keeping-components-pure) React uses the result of one of the calls, and ignores the result of the other call. As long as your component and calculation functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
For example, this impure calculation function mutates an array you received as a prop:
`useReducer` is very similar to [`useState`](/apis/react/useState), but it lets you move the state update logic from event handlers into a single function outside of your component. Read more about [choosing between `useState` and `useReducer`](/learn/extracting-state-logic-into-a-reducer#comparing-usestate-and-usereducer).
`useReducer` is very similar to [`useState`](/apis/react/useState), but it lets you move the state update logic from event handlers into a single function outside of your component. Read more about [choosing between `useState` and `useReducer`.](/learn/extracting-state-logic-into-a-reducer#comparing-usestate-and-usereducer)
---
@ -99,7 +99,7 @@ function reducer(state, action) {
}
```
Then you need to fill in the code that will calculate and return the next state. By convention, it is common to write it as a [`switch` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch). For each `case` in the `switch`, you need to calculate and return some next state.
Then you need to fill in the code that will calculate and return the next state. By convention, it is common to write it as a [`switch` statement.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch) For each `case` in the `switch`, you need to calculate and return some next state.
```js {4-7,10-13}
function reducer(state, action) {
@ -140,7 +140,7 @@ function Form() {
// ...
```
The action type names are local to your component. [Each action describes a single interaction, even if that leads to multiple changes in data](/learn/extracting-state-logic-into-a-reducer#writing-reducers-well). The shape of the state is arbitrary, but usually it'll be an object or an array.
The action type names are local to your component. [Each action describes a single interaction, even if that leads to multiple changes in data.](/learn/extracting-state-logic-into-a-reducer#writing-reducers-well) The shape of the state is arbitrary, but usually it'll be an object or an array.
Read [extracting state logic into a reducer](/learn/extracting-state-logic-into-a-reducer) to learn more.
Call `useReducer` at the top level of your component to manage its state with a [reducer](/learn/extracting-state-logic-into-a-reducer).
Call `useReducer` at the top level of your component to manage its state with a [reducer.](/learn/extracting-state-logic-into-a-reducer)
```js
import { useReducer } from 'react';
@ -900,7 +900,7 @@ function MyComponent() {
#### Caveats {/*caveats*/}
* `useReducer` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it.
* In Strict Mode, React will **call your reducer and initializer twice** in order to [help you find accidental impurities](#my-initializer-or-updater-function-runs-twice). This is development-only behavior and does not affect production. If your reducer and initializer are pure (as they should be), this should not affect the logic of your component. The result from one of the calls is ignored.
* In Strict Mode, React will **call your reducer and initializer twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. If your reducer and initializer are pure (as they should be), this should not affect the logic of your component. The result from one of the calls is ignored.
---
@ -932,7 +932,7 @@ React will set the next state to the result of calling the `reducer` function yo
* If the new value you provide is identical to the current `state`, as determined by an [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison, React will **skip re-rendering the component and its children.** This is an optimization. React may still need to call your component before ignoring the result, but it shouldn't affect your code.
* React [batches state updates](/learn/queueing-a-series-of-state-updates). It updates the screen **after all the event handlers have run** and have called their `set` functions. This prevents multiple re-renders during a single event. In the rare case that you need to force React to update the screen earlier, for example to access the DOM, you can use [`flushSync`](/apis/react-dom/flushsync).
* React [batches state updates.](/learn/queueing-a-series-of-state-updates) It updates the screen **after all the event handlers have run** and have called their `set` functions. This prevents multiple re-renders during a single event. In the rare case that you need to force React to update the screen earlier, for example to access the DOM, you can use [`flushSync`.](/apis/react-dom/flushsync)
---
@ -955,7 +955,7 @@ function handleClick() {
}
```
This is because [states behaves like a snapshot](/learn/state-as-a-snapshot). Updating state requests another render with the new state value, but does not affect the `state` JavaScript variable in your already-running event handler.
This is because [states behaves like a snapshot.](/learn/state-as-a-snapshot) Updating state requests another render with the new state value, but does not affect the `state` JavaScript variable in your already-running event handler.
If you need to guess the next state value, you can calculate it manually by calling the reducer yourself:
@ -1083,7 +1083,7 @@ If you can't find the cause of this error, click on the arrow next to the error
In [Strict Mode](/apis/react/strictmode), React will call your reducer and initializer functions twice. This shouldn't break your code.
This **development-only** behavior helps you [keep components pure](/learn/keeping-components-pure). React uses the result of one of the calls, and ignores the result of the other call. As long as your component, initializer, and reducer functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
This **development-only** behavior helps you [keep components pure.](/learn/keeping-components-pure) React uses the result of one of the calls, and ignores the result of the other call. As long as your component, initializer, and reducer functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
For example, this impure reducer function mutates an array in state:
### Referencing a value with a ref {/*referencing-a-value-with-a-ref*/}
Call `useRef` at the top level of your component to declare one or more [refs](/learn/referencing-values-with-refs).
Call `useRef` at the top level of your component to declare one or more [refs.](/learn/referencing-values-with-refs)
```js [[1, 4, "intervalRef"], [3, 4, "0"]]
import { useRef } from 'react';
@ -60,7 +60,7 @@ By using a ref, you ensure that:
- Changing it **does not trigger a re-render** (unlike state variables, which trigger a re-render).
- The **information is local** to each copy of your component (unlike the variables outside, which are shared).
Changing a ref does not trigger a re-render, so refs are not appropriate for storing information that you want to display on the screen. Use state for that instead. Read more about [choosing between `useRef` and `useState`](/learn/referencing-values-with-refs#differences-between-refs-and-state).
Changing a ref does not trigger a re-render, so refs are not appropriate for storing information that you want to display on the screen. Use state for that instead. Read more about [choosing between `useRef` and `useState`.](/learn/referencing-values-with-refs#differences-between-refs-and-state)
<RecipestitleText="Examples of referencing a value with useRef"titleId="examples-value">
@ -190,7 +190,7 @@ function MyComponent() {
If you *have to* read [or write](/apis/react/useState#storing-information-from-previous-renders) something during rendering, [use state](/apis/react/useState) instead.
When you break these rules, your component might still work, but most of the newer features we're adding to React will rely on these expectations. Read more about [keeping your components pure](/learn/keeping-components-pure#where-you-can-cause-side-effects).
When you break these rules, your component might still work, but most of the newer features we're adding to React will rely on these expectations. Read more about [keeping your components pure.](/learn/keeping-components-pure#where-you-can-cause-side-effects)
</Gotcha>
@ -198,7 +198,7 @@ When you break these rules, your component might still work, but most of the new
### Manipulating the DOM with a ref {/*manipulating-the-dom-with-a-ref*/}
It's particularly common to use a ref to manipulate the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API). React has built-in support for this.
It's particularly common to use a ref to manipulate the [DOM.](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API) React has built-in support for this.
First, declare a <CodeStepstep={1}>ref object</CodeStep> with an <CodeStepstep={3}>initial value</CodeStep> of `null`:
@ -227,7 +227,7 @@ After React creates the DOM node and puts it on the screen, React will set the <
React will set the `current` property back to `null` when the node is removed from the screen.
Read more about [manipulating the DOM with refs](/learn/manipulating-the-dom-with-refs).
Read more about [manipulating the DOM with refs.](/learn/manipulating-the-dom-with-refs)
<RecipestitleText="Examples of manipulating the DOM with useRef"titleId="examples-dom">
@ -502,7 +502,7 @@ Here, the `playerRef` itself is nullable. However, you should be able to convinc
### `useRef(initialValue)` {/*useref*/}
Call `useRef` at the top level of your component to declare a [ref](/learn/referencing-values-with-refs).
Call `useRef` at the top level of your component to declare a [ref.](/learn/referencing-values-with-refs)
```js
import { useRef } from 'react';
@ -513,7 +513,7 @@ function MyComponent() {
// ...
```
See examples of [referencing values](#examples-value) and [DOM manipulation](#examples-dom).
See examples of [referencing values](#examples-value) and [DOM manipulation.](#examples-dom)
#### Parameters {/*parameters*/}
@ -531,8 +531,8 @@ On the next renders, `useRef` will return the same object.
* You can mutate the `ref.current` property. Unlike state, it is mutable. However, if it holds an object that is used for rendering (for example, a piece of your state), then you shouldn't mutate that object.
* When you change the `ref.current` property, React does not re-render your component. React is not aware of when you change it because a ref is a plain JavaScript object.
* Do not write _or read_`ref.current` during rendering, except for [initialization](#avoiding-recreating-the-ref-contents). This makes your component's behavior unpredictable.
* In Strict Mode, React will **call your component function twice** in order to [help you find accidental impurities](#my-initializer-or-updater-function-runs-twice). This is development-only behavior and does not affect production. This means that each ref object will be created twice, and one of the versions will be discarded. If your component function is pure (as it should be), this should not affect the logic of your component.
* Do not write _or read_`ref.current` during rendering, except for [initialization.](#avoiding-recreating-the-ref-contents) This makes your component's behavior unpredictable.
* In Strict Mode, React will **call your component function twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. This means that each ref object will be created twice, and one of the versions will be discarded. If your component function is pure (as it should be), this should not affect the logic of your component.
---
@ -591,4 +591,4 @@ export default MyInput;
Then the parent component can get a ref to it.
Read more about [accessing another component's DOM nodes](/learn/manipulating-the-dom-with-refs#accessing-another-components-dom-nodes).
Read more about [accessing another component's DOM nodes.](/learn/manipulating-the-dom-with-refs#accessing-another-components-dom-nodes)
The convention is to name state variables like `[something, setSomething]` using [array destructuring](TODO:/learn/a-javascript-refresher#array-destructuring).
The convention is to name state variables like `[something, setSomething]` using [array destructuring.](TODO:/learn/a-javascript-refresher#array-destructuring)
`useState` returns an array with exactly two items:
@ -227,7 +227,7 @@ function handleClick() {
Here, `a => a + 1` is your updater function. It takes the <CodeStepstep={1}>pending state</CodeStep> and calculates the <CodeStepstep={2}>next state</CodeStep> from it.
React puts your updater functions in a [queue](/learn/queueing-a-series-of-state-updates). Then, during the next render, it will call them in the same order:
React puts your updater functions in a [queue.](/learn/queueing-a-series-of-state-updates) Then, during the next render, it will call them in the same order:
1. `a => a + 1` will receive `42` as the pending state and return `43` as the next state.
1. `a => a + 1` will receive `43` as the pending state and return `44` as the next state.
@ -237,7 +237,7 @@ There are no other queued updates, so React will store `45` as the current state
By convention, it's common to name the pending state argument for the first letter of the state variable name, like `a` for `age`. However, you may also call it like `prevAge` or something else that you find clearer.
React may [call your updaters twice](#my-initializer-or-updater-function-runs-twice) in development to verify that they are [pure](/learn/keeping-components-pure).
React may [call your updaters twice](#my-initializer-or-updater-function-runs-twice) in development to verify that they are [pure.](/learn/keeping-components-pure)
<DeepDivetitle="Is using an updater always preferred?">
@ -247,7 +247,7 @@ In most cases, there is no difference between these two approaches. React always
However, if you do multiple updates within the same event, updaters can be helpful. They're also helpful if accessing the state variable itself is inconvenient (you might run into this when optimizing re-renders).
If you prefer consistency over slightly more verbose syntax, it's reasonable to always write an updater if the state you're setting is calculated from the previous state. If it's calculated from the previous state of some *other* state variable, you might want to combine them into one object and [use a reducer](/learn/extracting-state-logic-into-a-reducer).
If you prefer consistency over slightly more verbose syntax, it's reasonable to always write an updater if the state you're setting is calculated from the previous state. If it's calculated from the previous state of some *other* state variable, you might want to combine them into one object and [use a reducer.](/learn/extracting-state-logic-into-a-reducer)
</DeepDive>
@ -827,7 +827,7 @@ function TodoList() {
Notice that you’re passing `createInitialTodos`, which is the *function itself*, and not `createInitialTodos()`, which is the result of calling it. If you pass a function to `useState`, React will only call it during initialization.
React may [call your initializers twice](#my-initializer-or-updater-function-runs-twice) in development to verify that they are [pure](/learn/keeping-components-pure).
React may [call your initializers twice](#my-initializer-or-updater-function-runs-twice) in development to verify that they are [pure.](/learn/keeping-components-pure)
<RecipestitleText="The difference between passing an initializer and passing the initial state directly"titleId="examples-initializer">
@ -943,7 +943,7 @@ export default function TodoList() {
### Resetting state with a key {/*resetting-state-with-a-key*/}
Typically, you might encounter the `key` attribute when [rendering lists](/learn/rendering-lists). However, it also serves another purpose.
Typically, you might encounter the `key` attribute when [rendering lists.](/learn/rendering-lists) However, it also serves another purpose.
You can **reset a component's state by passing a different `key` to a component.** In this example, the Reset button changes the `version` state variable, which we pass as a `key` to the `Form`. When the `key` changes, React re-creates the `Form` component (and all of its children) from scratch, so its state gets reset.
@ -998,7 +998,7 @@ Usually, you will update state in event handlers. However, in rare cases you mig
In most cases, you don't need this:
* **If the value you need can be computed entirely from the current props or other state, [remove that redundant state altogether](/learn/choosing-the-state-structure#avoid-redundant-state).** If you're worried about recomputing too often, the [`useMemo` Hook](/apis/react/usememo) can help.
* **If the value you need can be computed entirely from the current props or other state, [remove that redundant state altogether.](/learn/choosing-the-state-structure#avoid-redundant-state)** If you're worried about recomputing too often, the [`useMemo` Hook](/apis/react/usememo) can help.
* If you want to reset the entire component tree's state, [pass a different `key` to your component.](#resetting-state-with-a-key)
* If you can, update all the relevant state in the event handlers.
Note that if you call a `set` function while rendering, it must be inside a condition like `prevCount !== count`, and there must be a call like `setPrevCount(count)` inside of the condition. Otherwise, your component would re-render in a loop until it crashes. Also, you can only update the state of the *currently rendering* component like this. Calling the `set` function of *another* component during rendering is an error. Finally, your `set` call should still [update state without mutation](#updating-objects-and-arrays-in-state) -- this special case doesn't mean you can break other rules of [pure functions](/learn/keeping-components-pure).
Note that if you call a `set` function while rendering, it must be inside a condition like `prevCount !== count`, and there must be a call like `setPrevCount(count)` inside of the condition. Otherwise, your component would re-render in a loop until it crashes. Also, you can only update the state of the *currently rendering* component like this. Calling the `set` function of *another* component during rendering is an error. Finally, your `set` call should still [update state without mutation](#updating-objects-and-arrays-in-state) -- this special case doesn't mean you can break other rules of [pure functions.](/learn/keeping-components-pure)
This pattern can be hard to understand and is usually best avoided. However, it's better than updating state in an effect. When you call the `set` function during render, React will re-render that component immediately after your component exits with a `return` statement, and before rendering the children. This way, children don't need to render twice. The rest of your component function will still execute (and the result will be thrown away), but if your condition is below all the calls to Hooks, you may add an early `return;` inside it to restart rendering earlier.
@ -1071,7 +1071,7 @@ This pattern can be hard to understand and is usually best avoided. However, it'
### `useState(initialState)` {/*usestate*/}
Call `useState` at the top level of your component to declare a [state variable](/learn/state-a-components-memory).
Call `useState` at the top level of your component to declare a [state variable.](/learn/state-a-components-memory)
```js
import { useState } from 'react';
@ -1083,7 +1083,7 @@ function MyComponent() {
// ...
```
The convention is to name state variables like `[something, setSomething]` using [array destructuring](TODO:/learn/a-javascript-refresher#array-destructuring).
The convention is to name state variables like `[something, setSomething]` using [array destructuring.](TODO:/learn/a-javascript-refresher#array-destructuring)
[See more examples above.](#examples-basic)
@ -1102,7 +1102,7 @@ The convention is to name state variables like `[something, setSomething]` using
#### Caveats {/*caveats*/}
* `useState` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it.
* In Strict Mode, React will **call your initializer function twice** in order to [help you find accidental impurities](#my-initializer-or-updater-function-runs-twice). This is development-only behavior and does not affect production. If your initializer function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
* In Strict Mode, React will **call your initializer function twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. If your initializer function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
---
@ -1134,11 +1134,11 @@ function handleClick() {
* If the new value you provide is identical to the current `state`, as determined by an [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison, React will **skip re-rendering the component and its children.** This is an optimization. Although in some cases React may still need to call your component before skipping the children, it shouldn't affect your code.
* React [batches state updates](/learn/queueing-a-series-of-state-updates). It updates the screen **after all the event handlers have run** and have called their `set` functions. This prevents multiple re-renders during a single event. In the rare case that you need to force React to update the screen earlier, for example to access the DOM, you can use [`flushSync`](/apis/react-dom/flushsync).
* React [batches state updates.](/learn/queueing-a-series-of-state-updates) It updates the screen **after all the event handlers have run** and have called their `set` functions. This prevents multiple re-renders during a single event. In the rare case that you need to force React to update the screen earlier, for example to access the DOM, you can use [`flushSync`.](/apis/react-dom/flushsync)
* Calling the `set` function *during rendering* is only allowed from within the currently rendering component. React will discard its output and immediately attempt to render it again with the new state. This pattern is rarely needed, but you can use it to **store information from the previous renders**. [See an example above.](#storing-information-from-previous-renders)
* In Strict Mode, React will **call your updater function twice** in order to [help you find accidental impurities](#my-initializer-or-updater-function-runs-twice). This is development-only behavior and does not affect production. If your updater function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
* In Strict Mode, React will **call your updater function twice** in order to [help you find accidental impurities.](#my-initializer-or-updater-function-runs-twice) This is development-only behavior and does not affect production. If your updater function is pure (as it should be), this should not affect the logic of your component. The result from one of the calls will be ignored.
---
@ -1161,7 +1161,7 @@ function handleClick() {
}
```
This is because [states behaves like a snapshot](/learn/state-as-a-snapshot). Updating state requests another render with the new state value, but does not affect the `count` JavaScript variable in your already-running event handler.
This is because [states behaves like a snapshot.](/learn/state-as-a-snapshot) Updating state requests another render with the new state value, but does not affect the `count` JavaScript variable in your already-running event handler.
If you need to use the next state, you can save it in a variable before passing it to the `set` function:
@ -1239,7 +1239,7 @@ function TodoList() {
This is expected and shouldn't break your code.
This **development-only** behavior helps you [keep components pure](/learn/keeping-components-pure). React uses the result of one of the calls, and ignores the result of the other call. As long as your component, initializer, and updater functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
This **development-only** behavior helps you [keep components pure.](/learn/keeping-components-pure) React uses the result of one of the calls, and ignores the result of the other call. As long as your component, initializer, and updater functions are pure, this shouldn't affect your logic. However, if they are accidentally impure, this helps you notice the mistakes and fix it.
For example, this impure updater function mutates an array in state:
zqran
2 years ago
GitHub