# Table of Contents

- [React Reference Overview – React](#react-reference-overview-react)
- [useActionState – React](#useactionstate-react)
- [Built-in React Hooks – React](#built-in-react-hooks-react)
- [useDebugValue – React](#usedebugvalue-react)
- [useCallback – React](#usecallback-react)
- [useContext – React](#usecontext-react)
- [useDeferredValue – React](#usedeferredvalue-react)
- [useEffect – React](#useeffect-react)
- [useId – React](#useid-react)
- [useImperativeHandle – React](#useimperativehandle-react)
- [useInsertionEffect – React](#useinsertioneffect-react)
- [useOptimistic – React](#useoptimistic-react)
- [useReducer – React](#usereducer-react)
- [useMemo – React](#usememo-react)
- [useRef – React](#useref-react)
- [useState – React](#usestate-react)
- [useSyncExternalStore – React](#usesyncexternalstore-react)
- [Built-in React Components – React](#built-in-react-components-react)
- [useTransition – React](#usetransition-react)
- [<Fragment> (<>...</>) – React](#-fragment-react)
- [<Profiler> – React](#-profiler-react)
- [<StrictMode> – React](#-strictmode-react)
- [createContext – React](#createcontext-react)
- [lazy – React](#lazy-react)

---

# React Reference Overview – React

[API Reference](/reference/react)

React Reference Overview[](#undefined "Link for this heading")

===============================================================

This section provides detailed reference documentation for working with React. For an introduction to React, please visit the [Learn](/learn)
 section.

The React reference documentation is broken down into functional subsections:

React[](#react "Link for React ")

----------------------------------

Programmatic React features:

*   [Hooks](/reference/react/hooks)
     - Use different React features from your components.
*   [Components](/reference/react/components)
     - Built-in components that you can use in your JSX.
*   [APIs](/reference/react/apis)
     - APIs that are useful for defining components.
*   [Directives](/reference/rsc/directives)
     - Provide instructions to bundlers compatible with React Server Components.

React DOM[](#react-dom "Link for React DOM ")

----------------------------------------------

React-dom contains features that are only supported for web applications (which run in the browser DOM environment). This section is broken into the following:

*   [Hooks](/reference/react-dom/hooks)
     - Hooks for web applications which run in the browser DOM environment.
*   [Components](/reference/react-dom/components)
     - React supports all of the browser built-in HTML and SVG components.
*   [APIs](/reference/react-dom)
     - The `react-dom` package contains methods supported only in web applications.
*   [Client APIs](/reference/react-dom/client)
     - The `react-dom/client` APIs let you render React components on the client (in the browser).
*   [Server APIs](/reference/react-dom/server)
     - The `react-dom/server` APIs let you render React components to HTML on the server.

Rules of React[](#rules-of-react "Link for Rules of React ")

-------------------------------------------------------------

React has idioms — or rules — for how to express patterns in a way that is easy to understand and yields high-quality applications:

*   [Components and Hooks must be pure](/reference/rules/components-and-hooks-must-be-pure)
     – Purity makes your code easier to understand, debug, and allows React to automatically optimize your components and hooks correctly.
*   [React calls Components and Hooks](/reference/rules/react-calls-components-and-hooks)
     – React is responsible for rendering components and hooks when necessary to optimize the user experience.
*   [Rules of Hooks](/reference/rules/rules-of-hooks)
     – Hooks are defined using JavaScript functions, but they represent a special type of reusable UI logic with restrictions on where they can be called.

Legacy APIs[](#legacy-apis "Link for Legacy APIs ")

----------------------------------------------------

*   [Legacy APIs](/reference/react/legacy)
     - Exported from the `react` package, but not recommended for use in newly written code.

[NextHooks](/reference/react/hooks)

* * *

---

# useActionState – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useActionState[](#undefined "Link for this heading")

=====================================================

`useActionState` is a Hook that allows you to update state based on the result of a form action.

    const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);

### Note

In earlier React Canary versions, this API was part of React DOM and called `useFormState`.

*   [Reference](#reference)
    *   [`useActionState(action, initialState, permalink?)`](#useactionstate)
        
*   [Usage](#usage)
    *   [Using information returned by a form action](#using-information-returned-by-a-form-action)
        
*   [Troubleshooting](#troubleshooting)
    *   [My action can no longer read the submitted form data](#my-action-can-no-longer-read-the-submitted-form-data)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useActionState(action, initialState, permalink?)`[](#useactionstate "Link for this heading")

Call `useActionState` at the top level of your component to create component state that is updated [when a form action is invoked](/reference/react-dom/components/form)
. You pass `useActionState` an existing form action function as well as an initial state, and it returns a new action that you use in your form, along with the latest form state and whether the Action is still pending. The latest form state is also passed to the function that you provided.

    import { useActionState } from "react";async function increment(previousState, formData) {  return previousState + 1;}function StatefulForm({}) {  const [state, formAction] = useActionState(increment, 0);  return (    <form>      {state}      <button formAction={formAction}>Increment</button>    </form>  )}

The form state is the value returned by the action when the form was last submitted. If the form has not yet been submitted, it is the initial state that you pass.

If used with a Server Function, `useActionState` allows the server’s response from submitting the form to be shown even before hydration has completed.

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `fn`: The function to be called when the form is submitted or button pressed. When the function is called, it will receive the previous state of the form (initially the `initialState` that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that a form action normally receives.
*   `initialState`: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the action is first invoked.
*   **optional** `permalink`: A string containing the unique page URL that this form modifies. For use on pages with dynamic content (eg: feeds) in conjunction with progressive enhancement: if `fn` is a [server function](/reference/rsc/server-functions)
     and the form is submitted before the JavaScript bundle loads, the browser will navigate to the specified permalink URL, rather than the current page’s URL. Ensure that the same form component is rendered on the destination page (including the same action `fn` and `permalink`) so that React knows how to pass the state through. Once the form has been hydrated, this parameter has no effect.

#### Returns[](#returns "Link for Returns ")

`useActionState` returns an array with the following values:

1.  The current state. During the first render, it will match the `initialState` you have passed. After the action is invoked, it will match the value returned by the action.
2.  A new action that you can pass as the `action` prop to your `form` component or `formAction` prop to any `button` component within the form. The action can also be called manually within [`startTransition`](/reference/react/startTransition)
    .
3.  The `isPending` flag that tells you whether there is a pending Transition.

#### Caveats[](#caveats "Link for Caveats ")

*   When used with a framework that supports React Server Components, `useActionState` lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, it is equivalent to component local state.
*   The function passed to `useActionState` receives an extra argument, the previous or initial state, as its first argument. This makes its signature different than if it were used directly as a form action without using `useActionState`.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Using information returned by a form action[](#using-information-returned-by-a-form-action "Link for Using information returned by a form action ")

Call `useActionState` at the top level of your component to access the return value of an action from the last time a form was submitted.

    import { useActionState } from 'react';import { action } from './actions.js';function MyComponent() {  const [state, formAction] = useActionState(action, null);  // ...  return (    <form action={formAction}>      {/* ... */}    </form>  );}

`useActionState` returns an array with the following items:

1.  The current state of the form, which is initially set to the initial state you provided, and after the form is submitted is set to the return value of the action you provided.
2.  A new action that you pass to `<form>` as its `action` prop or call manually within `startTransition`.
3.  A pending state that you can utilise while your action is processing.

When the form is submitted, the action function that you provided will be called. Its return value will become the new current state of the form.

The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if `useActionState` had not been used.

    function action(currentState, formData) {  // ...  return 'next state';}

#### Display information after submitting a form[](#display-information-after-submitting-a-form "Link for Display information after submitting a form")

1. Display form errors 2. Display structured information after submitting a form

#### 

Example 1 of 2:

Display form errors[](#display-form-errors "Link for this heading")

To display messages such as an error message or toast that’s returned by a Server Function, wrap the action in a call to `useActionState`.

App.jsactions.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useActionState, useState } from "react";
import { addToCart } from "./actions.js";

function AddToCartForm({itemID, itemTitle}) {
  const \[message, formAction, isPending\] = useActionState(addToCart, null);
  return (
    <form action\={formAction}\>
      <h2\>{itemTitle}</h2\>
      <input type\="hidden" name\="itemID" value\={itemID} />
      <button type\="submit"\>Add to Cart</button\>
      {isPending ? "Loading..." : message}
    </form\>
  );
}

export default function App() {
  return (
    <\>
      <AddToCartForm itemID\="1" itemTitle\="JavaScript: The Definitive Guide" />
      <AddToCartForm itemID\="2" itemTitle\="JavaScript: The Good Parts" />
    </\>
  )
}

Show more

Next Example

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### My action can no longer read the submitted form data[](#my-action-can-no-longer-read-the-submitted-form-data "Link for My action can no longer read the submitted form data ")

When you wrap an action with `useActionState`, it gets an extra argument _as its first argument_. The submitted form data is therefore its _second_ argument instead of its first as it would usually be. The new first argument that gets added is the current state of the form.

    function action(currentState, formData) {  // ...}

[PreviousHooks](/reference/react/hooks)
[NextuseCallback](/reference/react/useCallback)

* * *

---

# Built-in React Hooks – React

[API Reference](/reference/react)

Built-in React Hooks[](#undefined "Link for this heading")

===========================================================

_Hooks_ let you use different React features from your components. You can either use the built-in Hooks or combine them to build your own. This page lists all built-in Hooks in React.

* * *

State Hooks[](#state-hooks "Link for State Hooks ")

----------------------------------------------------

_State_ lets a component [“remember” information like user input.](/learn/state-a-components-memory)
 For example, a form component can use state to store the input value, while an image gallery component can use state to store the selected image index.

To add state to a component, use one of these Hooks:

*   [`useState`](/reference/react/useState)
     declares a state variable that you can update directly.
*   [`useReducer`](/reference/react/useReducer)
     declares a state variable with the update logic inside a [reducer function.](/learn/extracting-state-logic-into-a-reducer)
    

    function ImageGallery() {  const [index, setIndex] = useState(0);  // ...

* * *

Context Hooks[](#context-hooks "Link for Context Hooks ")

----------------------------------------------------------

_Context_ lets a component [receive information from distant parents without passing it as props.](/learn/passing-props-to-a-component)
 For example, your app’s top-level component can pass the current UI theme to all components below, no matter how deep.

*   [`useContext`](/reference/react/useContext)
     reads and subscribes to a context.

    function Button() {  const theme = useContext(ThemeContext);  // ...

* * *

Ref Hooks[](#ref-hooks "Link for Ref Hooks ")

----------------------------------------------

_Refs_ let a component [hold some information that isn’t used for rendering,](/learn/referencing-values-with-refs)
 like a DOM node or a timeout ID. Unlike with state, updating a ref does not re-render your component. Refs are an “escape hatch” from the React paradigm. They are useful when you need to work with non-React systems, such as the built-in browser APIs.

*   [`useRef`](/reference/react/useRef)
     declares a ref. You can hold any value in it, but most often it’s used to hold a DOM node.
*   [`useImperativeHandle`](/reference/react/useImperativeHandle)
     lets you customize the ref exposed by your component. This is rarely used.

    function Form() {  const inputRef = useRef(null);  // ...

* * *

Effect Hooks[](#effect-hooks "Link for Effect Hooks ")

-------------------------------------------------------

_Effects_ let a component [connect to and synchronize with external systems.](/learn/synchronizing-with-effects)
 This includes dealing with network, browser DOM, animations, widgets written using a different UI library, and other non-React code.

*   [`useEffect`](/reference/react/useEffect)
     connects a component to an external system.

    function ChatRoom({ roomId }) {  useEffect(() => {    const connection = createConnection(roomId);    connection.connect();    return () => connection.disconnect();  }, [roomId]);  // ...

Effects are an “escape hatch” from the React paradigm. Don’t use Effects to orchestrate the data flow of your application. If you’re not interacting with an external system, [you might not need an Effect.](/learn/you-might-not-need-an-effect)

There are two rarely used variations of `useEffect` with differences in timing:

*   [`useLayoutEffect`](/reference/react/useLayoutEffect)
     fires before the browser repaints the screen. You can measure layout here.
*   [`useInsertionEffect`](/reference/react/useInsertionEffect)
     fires before React makes changes to the DOM. Libraries can insert dynamic CSS here.

* * *

Performance Hooks[](#performance-hooks "Link for Performance Hooks ")

----------------------------------------------------------------------

A common way to optimize re-rendering performance is to skip unnecessary work. For example, you can tell React to reuse a cached calculation or to skip a re-render if the data has not changed since the previous render.

To skip calculations and unnecessary re-rendering, use one of these Hooks:

*   [`useMemo`](/reference/react/useMemo)
     lets you cache the result of an expensive calculation.
*   [`useCallback`](/reference/react/useCallback)
     lets you cache a function definition before passing it down to an optimized component.

    function TodoList({ todos, tab, theme }) {  const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);  // ...}

Sometimes, you can’t skip re-rendering because the screen actually needs to update. In that case, you can improve performance by separating blocking updates that must be synchronous (like typing into an input) from non-blocking updates which don’t need to block the user interface (like updating a chart).

To prioritize rendering, use one of these Hooks:

*   [`useTransition`](/reference/react/useTransition)
     lets you mark a state transition as non-blocking and allow other updates to interrupt it.
*   [`useDeferredValue`](/reference/react/useDeferredValue)
     lets you defer updating a non-critical part of the UI and let other parts update first.

* * *

Other Hooks[](#other-hooks "Link for Other Hooks ")

----------------------------------------------------

These Hooks are mostly useful to library authors and aren’t commonly used in the application code.

*   [`useDebugValue`](/reference/react/useDebugValue)
     lets you customize the label React DevTools displays for your custom Hook.
*   [`useId`](/reference/react/useId)
     lets a component associate a unique ID with itself. Typically used with accessibility APIs.
*   [`useSyncExternalStore`](/reference/react/useSyncExternalStore)
     lets a component subscribe to an external store.

*   [`useActionState`](/reference/react/useActionState)
     allows you to manage state of actions.

* * *

Your own Hooks[](#your-own-hooks "Link for Your own Hooks ")

-------------------------------------------------------------

You can also [define your own custom Hooks](/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component)
 as JavaScript functions.

[PreviousOverview](/reference/react)
[NextuseActionState](/reference/react/useActionState)

* * *

---

# useDebugValue – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useDebugValue[](#undefined "Link for this heading")

====================================================

`useDebugValue` is a React Hook that lets you add a label to a custom Hook in [React DevTools.](/learn/react-developer-tools)

    useDebugValue(value, format?)

*   [Reference](#reference)
    *   [`useDebugValue(value, format?)`](#usedebugvalue)
        
*   [Usage](#usage)
    *   [Adding a label to a custom Hook](#adding-a-label-to-a-custom-hook)
        
    *   [Deferring formatting of a debug value](#deferring-formatting-of-a-debug-value)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useDebugValue(value, format?)`[](#usedebugvalue "Link for this heading")

Call `useDebugValue` at the top level of your [custom Hook](/learn/reusing-logic-with-custom-hooks)
 to display a readable debug value:

    import { useDebugValue } from 'react';function useOnlineStatus() {  // ...  useDebugValue(isOnline ? 'Online' : 'Offline');  // ...}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `value`: The value you want to display in React DevTools. It can have any type.
*   **optional** `format`: A formatting function. When the component is inspected, React DevTools will call the formatting function with the `value` as the argument, and then display the returned formatted value (which may have any type). If you don’t specify the formatting function, the original `value` itself will be displayed.

#### Returns[](#returns "Link for Returns ")

`useDebugValue` does not return anything.

Usage[](#usage "Link for Usage ")

----------------------------------

### Adding a label to a custom Hook[](#adding-a-label-to-a-custom-hook "Link for Adding a label to a custom Hook ")

Call `useDebugValue` at the top level of your [custom Hook](/learn/reusing-logic-with-custom-hooks)
 to display a readable debug value for [React DevTools.](/learn/react-developer-tools)

    import { useDebugValue } from 'react';function useOnlineStatus() {  // ...  useDebugValue(isOnline ? 'Online' : 'Offline');  // ...}

This gives components calling `useOnlineStatus` a label like `OnlineStatus: "Online"` when you inspect them:

![A screenshot of React DevTools showing the debug value](/images/docs/react-devtools-usedebugvalue.png)

Without the `useDebugValue` call, only the underlying data (in this example, `true`) would be displayed.

App.jsuseOnlineStatus.js

useOnlineStatus.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useSyncExternalStore, useDebugValue } from 'react';

export function useOnlineStatus() {
  const isOnline = useSyncExternalStore(subscribe, () \=> navigator.onLine, () \=> true);
  useDebugValue(isOnline ? 'Online' : 'Offline');
  return isOnline;
}

function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () \=> {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

Show more

### Note

Don’t add debug values to every custom Hook. It’s most valuable for custom Hooks that are part of shared libraries and that have a complex internal data structure that’s difficult to inspect.

* * *

### Deferring formatting of a debug value[](#deferring-formatting-of-a-debug-value "Link for Deferring formatting of a debug value ")

You can also pass a formatting function as the second argument to `useDebugValue`:

    useDebugValue(date, date => date.toDateString());

Your formatting function will receive the debug value as a parameter and should return a formatted display value. When your component is inspected, React DevTools will call this function and display its result.

This lets you avoid running potentially expensive formatting logic unless the component is actually inspected. For example, if `date` is a Date value, this avoids calling `toDateString()` on it for every render.

[PrevioususeContext](/reference/react/useContext)
[NextuseDeferredValue](/reference/react/useDeferredValue)

* * *

---

# useCallback – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useCallback[](#undefined "Link for this heading")

==================================================

`useCallback` is a React Hook that lets you cache a function definition between re-renders.

    const cachedFn = useCallback(fn, dependencies)

*   [Reference](#reference)
    *   [`useCallback(fn, dependencies)`](#usecallback)
        
*   [Usage](#usage)
    *   [Skipping re-rendering of components](#skipping-re-rendering-of-components)
        
    *   [Updating state from a memoized callback](#updating-state-from-a-memoized-callback)
        
    *   [Preventing an Effect from firing too often](#preventing-an-effect-from-firing-too-often)
        
    *   [Optimizing a custom Hook](#optimizing-a-custom-hook)
        
*   [Troubleshooting](#troubleshooting)
    *   [Every time my component renders, `useCallback` returns a different function](#every-time-my-component-renders-usecallback-returns-a-different-function)
        
    *   [I need to call `useCallback` for each list item in a loop, but it’s not allowed](#i-need-to-call-usememo-for-each-list-item-in-a-loop-but-its-not-allowed)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useCallback(fn, dependencies)`[](#usecallback "Link for this heading")

Call `useCallback` at the top level of your component to cache a function definition between re-renders:

    import { useCallback } from 'react';export default function ProductPage({ productId, referrer, theme }) {  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }, [productId, referrer]);

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `fn`: The function value that you want to cache. It can take any arguments and return any values. React will return (not call!) your function back to you during the initial render. On next renders, React will give you the same function again if the `dependencies` have not changed since the last render. Otherwise, it will give you the function that you have passed during the current render, and store it in case it can be reused later. React will not call your function. The function is returned to you so you can decide when and whether to call it.
    
*   `dependencies`: The list of all reactive values referenced inside of the `fn` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting)
    , it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison algorithm.
    

#### Returns[](#returns "Link for Returns ")

On the initial render, `useCallback` returns the `fn` function you have passed.

During subsequent renders, it will either return an already stored `fn` function from the last render (if the dependencies haven’t changed), or return the `fn` function you have passed during this render.

#### Caveats[](#caveats "Link for Caveats ")

*   `useCallback` 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.
*   React **will not throw away the cached function 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 `useCallback` as a performance optimization. Otherwise, a [state variable](/reference/react/useState#im-trying-to-set-state-to-a-function-but-it-gets-called-instead)
     or a [ref](/reference/react/useRef#avoiding-recreating-the-ref-contents)
     may be more appropriate.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Skipping re-rendering of components[](#skipping-re-rendering-of-components "Link for Skipping re-rendering of components ")

When you optimize rendering performance, you will sometimes need to cache the functions that you pass to child components. Let’s first look at the syntax for how to do this, and then see in which cases it’s useful.

To cache a function between re-renders of your component, wrap its definition into the `useCallback` Hook:

    import { useCallback } from 'react';function ProductPage({ productId, referrer, theme }) {  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }, [productId, referrer]);  // ...

You need to pass two things to `useCallback`:

1.  A function definition that you want to cache between re-renders.
2.  A list of dependencies including every value within your component that’s used inside your function.

On the initial render, the returned function you’ll get from `useCallback` will be the function you passed.

On the following renders, React will compare the dependencies with the dependencies you passed during the previous render. If none of the dependencies have changed (compared with [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
), `useCallback` will return the same function as before. Otherwise, `useCallback` will return the function you passed on _this_ render.

In other words, `useCallback` caches a function between re-renders until its dependencies change.

**Let’s walk through an example to see when this is useful.**

Say you’re passing a `handleSubmit` function down from the `ProductPage` to the `ShippingForm` component:

    function ProductPage({ productId, referrer, theme }) {  // ...  return (    <div className={theme}>      <ShippingForm onSubmit={handleSubmit} />    </div>  );

You’ve noticed that toggling the `theme` prop freezes the app for a moment, but if you remove `<ShippingForm />` from your JSX, it feels fast. This tells you that it’s worth trying to optimize the `ShippingForm` component.

**By default, when a component re-renders, React re-renders all of its children recursively.** This is why, when `ProductPage` re-renders with a different `theme`, the `ShippingForm` component _also_ re-renders. This is fine for components that don’t require much calculation to re-render. But if you verified a re-render is slow, you can tell `ShippingForm` to skip re-rendering when its props are the same as on last render by wrapping it in [`memo`:](/reference/react/memo)

    import { memo } from 'react';const ShippingForm = memo(function ShippingForm({ onSubmit }) {  // ...});

**With this change, `ShippingForm` will skip re-rendering if all of its props are the _same_ as on the last render.** This is when caching a function becomes important! Let’s say you defined `handleSubmit` without `useCallback`:

    function ProductPage({ productId, referrer, theme }) {  // Every time the theme changes, this will be a different function...  function handleSubmit(orderDetails) {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }    return (    <div className={theme}>      {/* ... so ShippingForm's props will never be the same, and it will re-render every time */}      <ShippingForm onSubmit={handleSubmit} />    </div>  );}

**In JavaScript, a `function () {}` or `() => {}` always creates a _different_ function,** similar to how the `{}` object literal always creates a new object. Normally, this wouldn’t be a problem, but it means that `ShippingForm` props will never be the same, and your [`memo`](/reference/react/memo)
 optimization won’t work. This is where `useCallback` comes in handy:

    function ProductPage({ productId, referrer, theme }) {  // Tell React to cache your function between re-renders...  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }, [productId, referrer]); // ...so as long as these dependencies don't change...  return (    <div className={theme}>      {/* ...ShippingForm will receive the same props and can skip re-rendering */}      <ShippingForm onSubmit={handleSubmit} />    </div>  );}

**By wrapping `handleSubmit` in `useCallback`, you ensure that it’s the _same_ function between the re-renders** (until dependencies change). You don’t _have to_ wrap a function in `useCallback` unless you do it for some specific reason. In this example, the reason is that you pass it to a component wrapped in [`memo`,](/reference/react/memo)
 and this lets it skip re-rendering. There are other reasons you might need `useCallback` which are described further on this page.

### Note

**You should only rely on `useCallback` as a performance optimization.** If your code doesn’t work without it, find the underlying problem and fix it first. Then you may add `useCallback` back.

##### Deep Dive

#### How is useCallback related to useMemo?[](#how-is-usecallback-related-to-usememo "Link for How is useCallback related to useMemo? ")

Show Details

You will often see [`useMemo`](/reference/react/useMemo)
 alongside `useCallback`. They are both useful when you’re trying to optimize a child component. They let you [memoize](https://en.wikipedia.org/wiki/Memoization)
 (or, in other words, cache) something you’re passing down:

    import { useMemo, useCallback } from 'react';function ProductPage({ productId, referrer }) {  const product = useData('/product/' + productId);  const requirements = useMemo(() => { // Calls your function and caches its result    return computeRequirements(product);  }, [product]);  const handleSubmit = useCallback((orderDetails) => { // Caches your function itself    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }, [productId, referrer]);  return (    <div className={theme}>      <ShippingForm requirements={requirements} onSubmit={handleSubmit} />    </div>  );}

The difference is in _what_ they’re letting you cache:

*   **[`useMemo`](/reference/react/useMemo)
     caches the _result_ of calling your function.** In this example, it caches the result of calling `computeRequirements(product)` so that it doesn’t change unless `product` has changed. This lets you pass the `requirements` object down without unnecessarily re-rendering `ShippingForm`. When necessary, React will call the function you’ve passed during rendering to calculate the result.
*   **`useCallback` caches _the function itself._** Unlike `useMemo`, it does not call the function you provide. Instead, it caches the function you provided so that `handleSubmit` _itself_ doesn’t change unless `productId` or `referrer` has changed. This lets you pass the `handleSubmit` function down without unnecessarily re-rendering `ShippingForm`. Your code won’t run until the user submits the form.

If you’re already familiar with [`useMemo`,](/reference/react/useMemo)
 you might find it helpful to think of `useCallback` as this:

    // Simplified implementation (inside React)function useCallback(fn, dependencies) {  return useMemo(() => fn, dependencies);}

[Read more about the difference between `useMemo` and `useCallback`.](/reference/react/useMemo#memoizing-a-function)

##### Deep Dive

#### Should you add useCallback everywhere?[](#should-you-add-usecallback-everywhere "Link for Should you add useCallback everywhere? ")

Show Details

If your app is like this site, and most interactions are coarse (like replacing a page or an entire section), memoization is usually unnecessary. On the other hand, if your app is more like a drawing editor, and most interactions are granular (like moving shapes), then you might find memoization very helpful.

Caching a function with `useCallback` is only valuable in a few cases:

*   You pass it as a prop to a component wrapped in [`memo`.](/reference/react/memo)
     You want to skip re-rendering if the value hasn’t changed. Memoization lets your component re-render only if dependencies changed.
*   The function you’re passing is later used as a dependency of some Hook. For example, another function wrapped in `useCallback` depends on it, or you depend on this function from [`useEffect.`](/reference/react/useEffect)
    

There is no benefit to wrapping a function in `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 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.

Note that `useCallback` does not prevent _creating_ the function. You’re always creating a function (and that’s fine!), but React ignores it and gives you back a cached function if nothing changed.

**In practice, you can make a lot of memoization unnecessary by following a few principles:**

1.  When a component visually wraps other components, let it [accept JSX as children.](/learn/passing-props-to-a-component#passing-jsx-as-children)
     Then, if the wrapper component updates its own state, React knows that its children don’t need to re-render.
2.  Prefer local state and don’t [lift state up](/learn/sharing-state-between-components)
     any further than necessary. Don’t keep transient state like forms and whether an item is hovered at the top of your tree or in a global state library.
3.  Keep your [rendering logic pure.](/learn/keeping-components-pure)
     If re-rendering a component causes a problem or produces some noticeable visual artifact, it’s a bug in your component! Fix the bug instead of adding memoization.
4.  Avoid [unnecessary Effects that update state.](/learn/you-might-not-need-an-effect)
     Most performance problems in React apps are caused by chains of updates originating from Effects that cause your components to render over and over.
5.  Try to [remove unnecessary dependencies from your Effects.](/learn/removing-effect-dependencies)
     For example, instead of memoization, it’s often simpler to move some object or a function inside an Effect or outside the component.

If a specific interaction still feels laggy, [use the React Developer Tools profiler](https://legacy.reactjs.org/blog/2018/09/10/introducing-the-react-profiler.html)
 to see which components benefit the most from memoization, and add memoization where needed. These principles make your components easier to debug and understand, so it’s good to follow them in any case. In long term, we’re researching [doing memoization automatically](https://www.youtube.com/watch?v=lGEMwh32soc)
 to solve this once and for all.

#### The difference between useCallback and declaring a function directly[](#examples-rerendering "Link for The difference between useCallback and declaring a function directly")

1. Skipping re-rendering with `useCallback` and `memo` 2. Always re-rendering a component

#### 

Example 1 of 2:

Skipping re-rendering with `useCallback` and `memo`[](#skipping-re-rendering-with-usecallback-and-memo "Link for this heading")

In this example, the `ShippingForm` component is **artificially slowed down** so that you can see what happens when a React component you’re rendering is genuinely slow. Try incrementing the counter and toggling the theme.

Incrementing the counter feels slow because it forces the slowed down `ShippingForm` to re-render. That’s expected because the counter has changed, and so you need to reflect the user’s new choice on the screen.

Next, try toggling the theme. **Thanks to `useCallback` together with [`memo`](/reference/react/memo)
, it’s fast despite the artificial slowdown!** `ShippingForm` skipped re-rendering because the `handleSubmit` function has not changed. The `handleSubmit` function has not changed because both `productId` and `referrer` (your `useCallback` dependencies) haven’t changed since last render.

App.jsProductPage.jsShippingForm.js

ProductPage.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useCallback } from 'react';
import ShippingForm from './ShippingForm.js';

export default function ProductPage({ productId, referrer, theme }) {
  const handleSubmit = useCallback((orderDetails) \=> {
    post('/product/' + productId + '/buy', {
      referrer,
      orderDetails,
    });
  }, \[productId, referrer\]);

  return (
    <div className\={theme}\>
      <ShippingForm onSubmit\={handleSubmit} />
    </div\>
  );
}

function post(url, data) {
  // Imagine this sends a request...
  console.log('POST /' + url);
  console.log(data);
}

Show more

Next Example

* * *

### Updating state from a memoized callback[](#updating-state-from-a-memoized-callback "Link for Updating state from a memoized callback ")

Sometimes, you might need to update state based on previous state from a memoized callback.

This `handleAddTodo` function specifies `todos` as a dependency because it computes the next todos from it:

    function TodoList() {  const [todos, setTodos] = useState([]);  const handleAddTodo = useCallback((text) => {    const newTodo = { id: nextId++, text };    setTodos([...todos, newTodo]);  }, [todos]);  // ...

You’ll usually want memoized functions to have as few dependencies as possible. When you read some state only to calculate the next state, you can remove that dependency by passing an [updater function](/reference/react/useState#updating-state-based-on-the-previous-state)
 instead:

    function TodoList() {  const [todos, setTodos] = useState([]);  const handleAddTodo = useCallback((text) => {    const newTodo = { id: nextId++, text };    setTodos(todos => [...todos, newTodo]);  }, []); // ✅ No need for the todos dependency  // ...

Here, instead of making `todos` a dependency and reading it inside, you pass an instruction about _how_ to update the state (`todos => [...todos, newTodo]`) to React. [Read more about updater functions.](/reference/react/useState#updating-state-based-on-the-previous-state)

* * *

### Preventing an Effect from firing too often[](#preventing-an-effect-from-firing-too-often "Link for Preventing an Effect from firing too often ")

Sometimes, you might want to call a function from inside an [Effect:](/learn/synchronizing-with-effects)

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  function createOptions() {    return {      serverUrl: 'https://localhost:1234',      roomId: roomId    };  }  useEffect(() => {    const options = createOptions();    const connection = createConnection(options);    connection.connect();    // ...

This creates a problem. [Every reactive value must be declared as a dependency of your Effect.](/learn/lifecycle-of-reactive-effects#react-verifies-that-you-specified-every-reactive-value-as-a-dependency)
 However, if you declare `createOptions` as a dependency, it will cause your Effect to constantly reconnect to the chat room:

      useEffect(() => {    const options = createOptions();    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [createOptions]); // 🔴 Problem: This dependency changes on every render  // ...

To solve this, you can wrap the function you need to call from an Effect into `useCallback`:

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  const createOptions = useCallback(() => {    return {      serverUrl: 'https://localhost:1234',      roomId: roomId    };  }, [roomId]); // ✅ Only changes when roomId changes  useEffect(() => {    const options = createOptions();    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [createOptions]); // ✅ Only changes when createOptions changes  // ...

This ensures that the `createOptions` function is the same between re-renders if the `roomId` is the same. **However, it’s even better to remove the need for a function dependency.** Move your function _inside_ the Effect:

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  useEffect(() => {    function createOptions() { // ✅ No need for useCallback or function dependencies!      return {        serverUrl: 'https://localhost:1234',        roomId: roomId      };    }    const options = createOptions();    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [roomId]); // ✅ Only changes when roomId changes  // ...

Now your code is simpler and doesn’t need `useCallback`. [Learn more about removing Effect dependencies.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)

* * *

### Optimizing a custom Hook[](#optimizing-a-custom-hook "Link for Optimizing a custom Hook ")

If you’re writing a [custom Hook,](/learn/reusing-logic-with-custom-hooks)
 it’s recommended to wrap any functions that it returns into `useCallback`:

    function useRouter() {  const { dispatch } = useContext(RouterStateContext);  const navigate = useCallback((url) => {    dispatch({ type: 'navigate', url });  }, [dispatch]);  const goBack = useCallback(() => {    dispatch({ type: 'back' });  }, [dispatch]);  return {    navigate,    goBack,  };}

This ensures that the consumers of your Hook can optimize their own code when needed.

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### Every time my component renders, `useCallback` returns a different function[](#every-time-my-component-renders-usecallback-returns-a-different-function "Link for this heading")

Make sure you’ve specified the dependency array as a second argument!

If you forget the dependency array, `useCallback` will return a new function every time:

    function ProductPage({ productId, referrer }) {  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }); // 🔴 Returns a new function every time: no dependency array  // ...

This is the corrected version passing the dependency array as a second argument:

    function ProductPage({ productId, referrer }) {  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails,    });  }, [productId, referrer]); // ✅ Does not return a new function unnecessarily  // ...

If this doesn’t help, then the problem is that at least one of your dependencies is different from the previous render. You can debug this problem by manually logging your dependencies to the console:

      const handleSubmit = useCallback((orderDetails) => {    // ..  }, [productId, referrer]);  console.log([productId, referrer]);

You can then right-click on the arrays from different re-renders in the console and select “Store as a global variable” for both of them. Assuming the first one got saved as `temp1` and the second one got saved as `temp2`, you can then use the browser console to check whether each dependency in both arrays is the same:

    Object.is(temp1[0], temp2[0]); // Is the first dependency the same between the arrays?Object.is(temp1[1], temp2[1]); // Is the second dependency the same between the arrays?Object.is(temp1[2], temp2[2]); // ... and so on for every dependency ...

When you find which dependency is breaking memoization, either find a way to remove it, or [memoize it as well.](/reference/react/useMemo#memoizing-a-dependency-of-another-hook)

* * *

### I need to call `useCallback` for each list item in a loop, but it’s not allowed[](#i-need-to-call-usememo-for-each-list-item-in-a-loop-but-its-not-allowed "Link for this heading")

Suppose the `Chart` component is wrapped in [`memo`](/reference/react/memo)
. You want to skip re-rendering every `Chart` in the list when the `ReportList` component re-renders. However, you can’t call `useCallback` in a loop:

    function ReportList({ items }) {  return (    <article>      {items.map(item => {        // 🔴 You can't call useCallback in a loop like this:        const handleClick = useCallback(() => {          sendReport(item)        }, [item]);        return (          <figure key={item.id}>            <Chart onClick={handleClick} />          </figure>        );      })}    </article>  );}

Instead, extract a component for an individual item, and put `useCallback` there:

    function ReportList({ items }) {  return (    <article>      {items.map(item =>        <Report key={item.id} item={item} />      )}    </article>  );}function Report({ item }) {  // ✅ Call useCallback at the top level:  const handleClick = useCallback(() => {    sendReport(item)  }, [item]);  return (    <figure>      <Chart onClick={handleClick} />    </figure>  );}

Alternatively, you could remove `useCallback` in the last snippet and instead wrap `Report` itself in [`memo`.](/reference/react/memo)
 If the `item` prop does not change, `Report` will skip re-rendering, so `Chart` will skip re-rendering too:

    function ReportList({ items }) {  // ...}const Report = memo(function Report({ item }) {  function handleClick() {    sendReport(item);  }  return (    <figure>      <Chart onClick={handleClick} />    </figure>  );});

[PrevioususeActionState](/reference/react/useActionState)
[NextuseContext](/reference/react/useContext)

* * *

---

# useContext – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useContext[](#undefined "Link for this heading")

=================================================

`useContext` is a React Hook that lets you read and subscribe to [context](/learn/passing-data-deeply-with-context)
 from your component.

    const value = useContext(SomeContext)

*   [Reference](#reference)
    *   [`useContext(SomeContext)`](#usecontext)
        
*   [Usage](#usage)
    *   [Passing data deeply into the tree](#passing-data-deeply-into-the-tree)
        
    *   [Updating data passed via context](#updating-data-passed-via-context)
        
    *   [Specifying a fallback default value](#specifying-a-fallback-default-value)
        
    *   [Overriding context for a part of the tree](#overriding-context-for-a-part-of-the-tree)
        
    *   [Optimizing re-renders when passing objects and functions](#optimizing-re-renders-when-passing-objects-and-functions)
        
*   [Troubleshooting](#troubleshooting)
    *   [My component doesn’t see the value from my provider](#my-component-doesnt-see-the-value-from-my-provider)
        
    *   [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)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useContext(SomeContext)`[](#usecontext "Link for this heading")

Call `useContext` at the top level of your component to read and subscribe to [context.](/learn/passing-data-deeply-with-context)

    import { useContext } from 'react';function MyComponent() {  const theme = useContext(ThemeContext);  // ...

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `SomeContext`: The context that you’ve previously created with [`createContext`](/reference/react/createContext)
    . The context itself does not hold the information, it only represents the kind of information you can provide or read from components.

#### Returns[](#returns "Link for Returns ")

`useContext` returns the context value for the calling component. It is determined as the `value` passed to the closest `SomeContext.Provider` above the calling component in the tree. If there is no such provider, then the returned value will be the `defaultValue` you have passed to [`createContext`](/reference/react/createContext)
 for that context. The returned value is always up-to-date. React automatically re-renders components that read some context if it changes.

#### Caveats[](#caveats "Link for Caveats ")

*   `useContext()` call in a component is not affected by providers returned from the _same_ component. The corresponding `<Context.Provider>` **needs to be _above_** the component doing the `useContext()` call.
*   React **automatically re-renders** all the children that use a particular context starting from the provider that receives a different `value`. The previous and the next values are compared with the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison. Skipping re-renders with [`memo`](/reference/react/memo)
     does not prevent the children receiving fresh context values.
*   If your build system produces duplicates modules in the output (which can happen with symlinks), this can break context. Passing something via context only works if `SomeContext` that you use to provide context and `SomeContext` that you use to read it are **_exactly_ the same object**, as determined by a `===` comparison.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Passing data deeply into the tree[](#passing-data-deeply-into-the-tree "Link for 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)

    import { useContext } from 'react';function Button() {  const theme = useContext(ThemeContext);  // ...

`useContext` returns the context value for the context you passed. To determine the context value, React searches the component tree and finds **the closest context provider above** for that particular context.

To pass context to a `Button`, wrap it or one of its parent components into the corresponding context provider:

    function MyPage() {  return (    <ThemeContext.Provider value="dark">      <Form />    </ThemeContext.Provider>  );}function Form() {  // ... renders buttons inside ...}

It doesn’t matter how many layers of components there are between the provider and the `Button`. When a `Button` _anywhere_ inside of `Form` calls `useContext(ThemeContext)`, it will receive `"dark"` as the value.

### Pitfall

`useContext()` always looks for the closest provider _above_ the component that calls it. It searches upwards and **does not** consider providers in the component from which you’re calling `useContext()`.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createContext, useContext } from 'react';

const ThemeContext = createContext(null);

export default function MyApp() {
  return (
    <ThemeContext.Provider value\="dark"\>
      <Form />
    </ThemeContext.Provider\>
  )
}

function Form() {
  return (
    <Panel title\="Welcome"\>
      <Button\>Sign up</Button\>
      <Button\>Log in</Button\>
    </Panel\>
  );
}

function Panel({ title, children }) {
  const theme = useContext(ThemeContext);
  const className = 'panel-' + theme;
  return (
    <section className\={className}\>
      <h1\>{title}</h1\>
      {children}
    </section\>
  )
}

function Button({ children }) {
  const theme = useContext(ThemeContext);
  const className = 'button-' + theme;
  return (
    <button className\={className}\>
      {children}
    </button\>
  );
}

Show more

* * *

### Updating data passed via context[](#updating-data-passed-via-context "Link for Updating data passed via context ")

Often, you’ll want the context to change over time. To update context, combine it with [state.](/reference/react/useState)
 Declare a state variable in the parent component, and pass the current state down as the context value to the provider.

    function MyPage() {  const [theme, setTheme] = useState('dark');  return (    <ThemeContext.Provider value={theme}>      <Form />      <Button onClick={() => {        setTheme('light');      }}>        Switch to light theme      </Button>    </ThemeContext.Provider>  );}

Now any `Button` inside of the provider will receive the current `theme` value. If you call `setTheme` to update the `theme` value that you pass to the provider, all `Button` components will re-render with the new `'light'` value.

#### Examples of updating context[](#examples-basic "Link for Examples of updating context")

1. Updating a value via context 2. Updating an object via context 3. Multiple contexts 4. Extracting providers to a component 5. Scaling up with context and a reducer

#### 

Example 1 of 5:

Updating a value via context[](#updating-a-value-via-context "Link for this heading")

In this example, the `MyApp` component holds a state variable which is then passed to the `ThemeContext` provider. Checking the “Dark mode” checkbox updates the state. Changing the provided value re-renders all the components using that context.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext(null);

export default function MyApp() {
  const \[theme, setTheme\] = useState('light');
  return (
    <ThemeContext.Provider value\={theme}\>
      <Form />
      <label\>
        <input
          type\="checkbox"
          checked\={theme === 'dark'}
          onChange\={(e) \=> {
            setTheme(e.target.checked ? 'dark' : 'light')
          }}
        />
        Use dark mode
      </label\>
    </ThemeContext.Provider\>
  )
}

function Form({ children }) {
  return (
    <Panel title\="Welcome"\>
      <Button\>Sign up</Button\>
      <Button\>Log in</Button\>
    </Panel\>
  );
}

function Panel({ title, children }) {
  const theme = useContext(ThemeContext);
  const className = 'panel-' + theme;
  return (
    <section className\={className}\>
      <h1\>{title}</h1\>
      {children}
    </section\>
  )
}

function Button({ children }) {
  const theme = useContext(ThemeContext);
  const className = 'button-' + theme;
  return (
    <button className\={className}\>
      {children}
    </button\>
  );
}

Show more

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.

Next Example

* * *

### Specifying a fallback default value[](#specifying-a-fallback-default-value "Link for Specifying a fallback default value ")

If React can’t find any providers of that particular context in the parent tree, the context value returned by `useContext()` will be equal to the default value that you specified when you [created that context](/reference/react/createContext)
:

    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)

Often, instead of `null`, there is some more meaningful value you can use as a default, for example:

    const ThemeContext = createContext('light');

This way, if you accidentally render some component without a corresponding provider, it won’t break. This also helps your components work well in a test environment without setting up a lot of providers in the tests.

In the example below, the “Toggle theme” button is always light because it’s **outside any theme context provider** and the default context theme value is `'light'`. Try editing the default theme to be `'dark'`.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext('light');

export default function MyApp() {
  const \[theme, setTheme\] = useState('light');
  return (
    <\>
      <ThemeContext.Provider value\={theme}\>
        <Form />
      </ThemeContext.Provider\>
      <Button onClick\={() \=> {
        setTheme(theme === 'dark' ? 'light' : 'dark');
      }}\>
        Toggle theme
      </Button\>
    </\>
  )
}

function Form({ children }) {
  return (
    <Panel title\="Welcome"\>
      <Button\>Sign up</Button\>
      <Button\>Log in</Button\>
    </Panel\>
  );
}

function Panel({ title, children }) {
  const theme = useContext(ThemeContext);
  const className = 'panel-' + theme;
  return (
    <section className\={className}\>
      <h1\>{title}</h1\>
      {children}
    </section\>
  )
}

function Button({ children, onClick }) {
  const theme = useContext(ThemeContext);
  const className = 'button-' + theme;
  return (
    <button className\={className} onClick\={onClick}\>
      {children}
    </button\>
  );
}

Show more

* * *

### Overriding context for a part of the tree[](#overriding-context-for-a-part-of-the-tree "Link for Overriding context for a part of the tree ")

You can override the context for a part of the tree by wrapping that part in a provider with a different value.

    <ThemeContext.Provider value="dark">  ...  <ThemeContext.Provider value="light">    <Footer />  </ThemeContext.Provider>  ...</ThemeContext.Provider>

You can nest and override providers as many times as you need.

#### Examples of overriding context[](#examples "Link for Examples of overriding context")

1. Overriding a theme 2. Automatically nested headings

#### 

Example 1 of 2:

Overriding a theme[](#overriding-a-theme "Link for this heading")

Here, the button _inside_ the `Footer` receives a different context value (`"light"`) than the buttons outside (`"dark"`).

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createContext, useContext } from 'react';

const ThemeContext = createContext(null);

export default function MyApp() {
  return (
    <ThemeContext.Provider value\="dark"\>
      <Form />
    </ThemeContext.Provider\>
  )
}

function Form() {
  return (
    <Panel title\="Welcome"\>
      <Button\>Sign up</Button\>
      <Button\>Log in</Button\>
      <ThemeContext.Provider value\="light"\>
        <Footer />
      </ThemeContext.Provider\>
    </Panel\>
  );
}

function Footer() {
  return (
    <footer\>
      <Button\>Settings</Button\>
    </footer\>
  );
}

function Panel({ title, children }) {
  const theme = useContext(ThemeContext);
  const className = 'panel-' + theme;
  return (
    <section className\={className}\>
      {title && <h1\>{title}</h1\>}
      {children}
    </section\>
  )
}

function Button({ children }) {
  const theme = useContext(ThemeContext);
  const className = 'button-' + theme;
  return (
    <button className\={className}\>
      {children}
    </button\>
  );
}

Show more

Next Example

* * *

### Optimizing re-renders when passing objects and functions[](#optimizing-re-renders-when-passing-objects-and-functions "Link for Optimizing re-renders when passing objects and functions ")

You can pass any values via context, including objects and functions.

    function MyApp() {  const [currentUser, setCurrentUser] = useState(null);  function login(response) {    storeCredentials(response.credentials);    setCurrentUser(response.user);  }  return (    <AuthContext.Provider value={{ currentUser, login }}>      <Page />    </AuthContext.Provider>  );}

Here, the context value 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`](/reference/react/useCallback)
 and wrap the object creation into [`useMemo`](/reference/react/useMemo)
. This is a performance optimization:

    import { useCallback, useMemo } from 'react';function MyApp() {  const [currentUser, setCurrentUser] = useState(null);  const login = useCallback((response) => {    storeCredentials(response.credentials);    setCurrentUser(response.user);  }, []);  const contextValue = useMemo(() => ({    currentUser,    login  }), [currentUser, login]);  return (    <AuthContext.Provider value={contextValue}>      <Page />    </AuthContext.Provider>  );}

As a result of this change, even if `MyApp` needs to re-render, the components calling `useContext(AuthContext)` won’t need to re-render unless `currentUser` has changed.

Read more about [`useMemo`](/reference/react/useMemo#skipping-re-rendering-of-components)
 and [`useCallback`.](/reference/react/useCallback#skipping-re-rendering-of-components)

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### My component doesn’t see the value from my provider[](#my-component-doesnt-see-the-value-from-my-provider "Link for My component doesn’t see the value from my provider ")

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)
    
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, 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 "Link for this heading")

You might have a provider without a `value` in the tree:

    // 🚩 Doesn't work: no value prop<ThemeContext.Provider>   <Button /></ThemeContext.Provider>

If you forget to specify `value`, it’s like passing `value={undefined}`.

You may have also mistakingly used a different prop name by mistake:

    // 🚩 Doesn't work: prop should be called "value"<ThemeContext.Provider theme={theme}>   <Button /></ThemeContext.Provider>

In both of these cases you should see a warning from React in the console. To fix them, call the prop `value`:

    // ✅ Passing the value prop<ThemeContext.Provider value={theme}>   <Button /></ThemeContext.Provider>

Note that the [default value from your `createContext(defaultValue)` call](#specifying-a-fallback-default-value)
 is only used **if there is no matching provider above at all.** If there is a `<SomeContext.Provider value={undefined}>` component somewhere in the parent tree, the component calling `useContext(SomeContext)` _will_ receive `undefined` as the context value.

[PrevioususeCallback](/reference/react/useCallback)
[NextuseDebugValue](/reference/react/useDebugValue)

* * *

---

# useDeferredValue – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useDeferredValue[](#undefined "Link for this heading")

=======================================================

`useDeferredValue` is a React Hook that lets you defer updating a part of the UI.

    const deferredValue = useDeferredValue(value)

*   [Reference](#reference)
    *   [`useDeferredValue(value, initialValue?)`](#usedeferredvalue)
        
*   [Usage](#usage)
    *   [Showing stale content while fresh content is loading](#showing-stale-content-while-fresh-content-is-loading)
        
    *   [Indicating that the content is stale](#indicating-that-the-content-is-stale)
        
    *   [Deferring re-rendering for a part of the UI](#deferring-re-rendering-for-a-part-of-the-ui)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useDeferredValue(value, initialValue?)`[](#usedeferredvalue "Link for this heading")

Call `useDeferredValue` at the top level of your component to get a deferred version of that value.

    import { useState, useDeferredValue } from 'react';function SearchPage() {  const [query, setQuery] = useState('');  const deferredQuery = useDeferredValue(query);  // ...}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `value`: The value you want to defer. It can have any type.
*   **optional** `initialValue`: A value to use during the initial render of a component. If this option is omitted, `useDeferredValue` will not defer during the initial render, because there’s no previous version of `value` that it can render instead.

#### Returns[](#returns "Link for Returns ")

*   `currentValue`: During the initial render, the returned deferred value will be the `initialValue`, or the same as the value you provided. During updates, React will first attempt a re-render with the old value (so it will return the old value), and then try another re-render in the background with the new value (so it will return the updated value).

#### Caveats[](#caveats "Link for Caveats ")

*   When an update is inside a Transition, `useDeferredValue` always returns the new `value` and does not spawn a deferred render, since the update is already deferred.
    
*   The values you pass to `useDeferredValue` should either be primitive values (like strings and numbers) or objects created outside of rendering. If you create a new object during rendering and immediately pass it to `useDeferredValue`, it will be different on every render, causing unnecessary background re-renders.
    
*   When `useDeferredValue` receives a different value (compared with [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
    ), in addition to the current render (when it still uses the previous value), it schedules a re-render in the background with the new value. The background re-render is interruptible: if there’s another update to the `value`, React will restart the background re-render from scratch. For example, if the user is typing into an input faster than a chart receiving its deferred value can re-render, the chart will only re-render after the user stops typing.
    
*   `useDeferredValue` is integrated with [`<Suspense>`.](/reference/react/Suspense)
     If the background update caused by a new value suspends the UI, the user will not see the fallback. They will see the old deferred value until the data loads.
    
*   `useDeferredValue` does not by itself prevent extra network requests.
    
*   There is no fixed delay caused by `useDeferredValue` itself. As soon as React finishes the original re-render, React will immediately start working on the background re-render with the new deferred value. Any updates caused by events (like typing) will interrupt the background re-render and get prioritized over it.
    
*   The background re-render caused by `useDeferredValue` does not fire Effects until it’s committed to the screen. If the background re-render suspends, its Effects will run after the data loads and the UI updates.
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Showing stale content while fresh content is loading[](#showing-stale-content-while-fresh-content-is-loading "Link for Showing stale content while fresh content is loading ")

Call `useDeferredValue` at the top level of your component to defer updating some part of your UI.

    import { useState, useDeferredValue } from 'react';function SearchPage() {  const [query, setQuery] = useState('');  const deferredQuery = useDeferredValue(query);  // ...}

During the initial render, the deferred value will be the same as the value you provided.

During updates, the deferred value will “lag behind” the latest value. In particular, React will first re-render _without_ updating the deferred value, and then try to re-render with the newly received value in the background.

**Let’s walk through an example to see when this is useful.**

### Note

This example assumes you use a Suspense-enabled data source:

*   Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/)
     and [Next.js](https://nextjs.org/docs/app/getting-started/fetching-data#with-suspense)
    
*   Lazy-loading component code with [`lazy`](/reference/react/lazy)
    
*   Reading the value of a Promise with [`use`](/reference/react/use)
    

[Learn more about Suspense and its limitations.](/reference/react/Suspense)

In this example, the `SearchResults` component [suspends](/reference/react/Suspense#displaying-a-fallback-while-content-is-loading)
 while fetching the search results. Try typing `"a"`, waiting for the results, and then editing it to `"ab"`. The results for `"a"` get replaced by the loading fallback.

App.jsSearchResults.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Suspense, useState } from 'react';
import SearchResults from './SearchResults.js';

export default function App() {
  const \[query, setQuery\] = useState('');
  return (
    <\>
      <label\>
        Search albums:
        <input value\={query} onChange\={e \=> setQuery(e.target.value)} />
      </label\>
      <Suspense fallback\={<h2\>Loading...</h2\>}\>
        <SearchResults query\={query} />
      </Suspense\>
    </\>
  );
}

Show more

A common alternative UI pattern is to _defer_ updating the list of results and to keep showing the previous results until the new results are ready. Call `useDeferredValue` to pass a deferred version of the query down:

    export default function App() {  const [query, setQuery] = useState('');  const deferredQuery = useDeferredValue(query);  return (    <>      <label>        Search albums:        <input value={query} onChange={e => setQuery(e.target.value)} />      </label>      <Suspense fallback={<h2>Loading...</h2>}>        <SearchResults query={deferredQuery} />      </Suspense>    </>  );}

The `query` will update immediately, so the input will display the new value. However, the `deferredQuery` will keep its previous value until the data has loaded, so `SearchResults` will show the stale results for a bit.

Enter `"a"` in the example below, wait for the results to load, and then edit the input to `"ab"`. Notice how instead of the Suspense fallback, you now see the stale result list until the new results have loaded:

App.jsSearchResults.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Suspense, useState, useDeferredValue } from 'react';
import SearchResults from './SearchResults.js';

export default function App() {
  const \[query, setQuery\] = useState('');
  const deferredQuery = useDeferredValue(query);
  return (
    <\>
      <label\>
        Search albums:
        <input value\={query} onChange\={e \=> setQuery(e.target.value)} />
      </label\>
      <Suspense fallback\={<h2\>Loading...</h2\>}\>
        <SearchResults query\={deferredQuery} />
      </Suspense\>
    </\>
  );
}

Show more

##### Deep Dive

#### How does deferring a value work under the hood?[](#how-does-deferring-a-value-work-under-the-hood "Link for How does deferring a value work under the hood? ")

Show Details

You can think of it as happening in two steps:

1.  **First, React re-renders with the new `query` (`"ab"`) but with the old `deferredQuery` (still `"a")`.** The `deferredQuery` value, which you pass to the result list, is _deferred:_ it “lags behind” the `query` value.
    
2.  **In the background, React tries to re-render with _both_ `query` and `deferredQuery` updated to `"ab"`.** If this re-render completes, React will show it on the screen. However, if it suspends (the results for `"ab"` have not loaded yet), React will abandon this rendering attempt, and retry this re-render again after the data has loaded. The user will keep seeing the stale deferred value until the data is ready.
    

The deferred “background” rendering is interruptible. For example, if you type into the input again, React will abandon it and restart with the new value. React will always use the latest provided value.

Note that there is still a network request per each keystroke. What’s being deferred here is displaying results (until they’re ready), not the network requests themselves. Even if the user continues typing, responses for each keystroke get cached, so pressing Backspace is instant and doesn’t fetch again.

* * *

### Indicating that the content is stale[](#indicating-that-the-content-is-stale "Link for Indicating that the content is stale ")

In the example above, there is no indication that the result list for the latest query is still loading. This can be confusing to the user if the new results take a while to load. To make it more obvious to the user that the result list does not match the latest query, you can add a visual indication when the stale result list is displayed:

    <div style={{  opacity: query !== deferredQuery ? 0.5 : 1,}}>  <SearchResults query={deferredQuery} /></div>

With this change, as soon as you start typing, the stale result list gets slightly dimmed until the new result list loads. You can also add a CSS transition to delay dimming so that it feels gradual, like in the example below:

App.jsSearchResults.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Suspense, useState, useDeferredValue } from 'react';
import SearchResults from './SearchResults.js';

export default function App() {
  const \[query, setQuery\] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;
  return (
    <\>
      <label\>
        Search albums:
        <input value\={query} onChange\={e \=> setQuery(e.target.value)} />
      </label\>
      <Suspense fallback\={<h2\>Loading...</h2\>}\>
        <div style\={{
          opacity: isStale ? 0.5 : 1,
          transition: isStale ? 'opacity 0.2s 0.2s linear' : 'opacity 0s 0s linear'
        }}\>
          <SearchResults query\={deferredQuery} />
        </div\>
      </Suspense\>
    </\>
  );
}

Show more

* * *

### Deferring re-rendering for a part of the UI[](#deferring-re-rendering-for-a-part-of-the-ui "Link for Deferring re-rendering for a part of the UI ")

You can also apply `useDeferredValue` as a performance optimization. It is useful when a part of your UI is slow to re-render, there’s no easy way to optimize it, and you want to prevent it from blocking the rest of the UI.

Imagine you have a text field and a component (like a chart or a long list) that re-renders on every keystroke:

    function App() {  const [text, setText] = useState('');  return (    <>      <input value={text} onChange={e => setText(e.target.value)} />      <SlowList text={text} />    </>  );}

First, optimize `SlowList` to skip re-rendering when its props are the same. To do this, [wrap it in `memo`:](/reference/react/memo#skipping-re-rendering-when-props-are-unchanged)

    const SlowList = memo(function SlowList({ text }) {  // ...});

However, this only helps if the `SlowList` props are _the same_ as during the previous render. The problem you’re facing now is that it’s slow when they’re _different,_ and when you actually need to show different visual output.

Concretely, the main performance problem is that whenever you type into the input, the `SlowList` receives new props, and re-rendering its entire tree makes the typing feel janky. In this case, `useDeferredValue` lets you prioritize updating the input (which must be fast) over updating the result list (which is allowed to be slower):

    function App() {  const [text, setText] = useState('');  const deferredText = useDeferredValue(text);  return (    <>      <input value={text} onChange={e => setText(e.target.value)} />      <SlowList text={deferredText} />    </>  );}

This does not make re-rendering of the `SlowList` faster. However, it tells React that re-rendering the list can be deprioritized so that it doesn’t block the keystrokes. The list will “lag behind” the input and then “catch up”. Like before, React will attempt to update the list as soon as possible, but will not block the user from typing.

#### The difference between useDeferredValue and unoptimized re-rendering[](#examples "Link for The difference between useDeferredValue and unoptimized re-rendering")

1. Deferred re-rendering of the list 2. Unoptimized re-rendering of the list

#### 

Example 1 of 2:

Deferred re-rendering of the list[](#deferred-re-rendering-of-the-list "Link for this heading")

In this example, each item in the `SlowList` component is **artificially slowed down** so that you can see how `useDeferredValue` lets you keep the input responsive. Type into the input and notice that typing feels snappy while the list “lags behind” it.

App.jsSlowList.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useDeferredValue } from 'react';
import SlowList from './SlowList.js';

export default function App() {
  const \[text, setText\] = useState('');
  const deferredText = useDeferredValue(text);
  return (
    <\>
      <input value\={text} onChange\={e \=> setText(e.target.value)} />
      <SlowList text\={deferredText} />
    </\>
  );
}

Next Example

### Pitfall

This optimization requires `SlowList` to be wrapped in [`memo`.](/reference/react/memo)
 This is because whenever the `text` changes, React needs to be able to re-render the parent component quickly. During that re-render, `deferredText` still has its previous value, so `SlowList` is able to skip re-rendering (its props have not changed). Without [`memo`,](/reference/react/memo)
 it would have to re-render anyway, defeating the point of the optimization.

##### Deep Dive

#### How is deferring a value different from debouncing and throttling?[](#how-is-deferring-a-value-different-from-debouncing-and-throttling "Link for How is deferring a value different from debouncing and throttling? ")

Show Details

There are two common optimization techniques you might have used before in this scenario:

*   _Debouncing_ means you’d wait for the user to stop typing (e.g. for a second) before updating the list.
*   _Throttling_ means you’d update the list every once in a while (e.g. at most once a second).

While these techniques are helpful in some cases, `useDeferredValue` is better suited to optimizing rendering because it is deeply integrated with React itself and adapts to the user’s device.

Unlike debouncing or throttling, it doesn’t require choosing any fixed delay. If the user’s device is fast (e.g. powerful laptop), the deferred re-render would happen almost immediately and wouldn’t be noticeable. If the user’s device is slow, the list would “lag behind” the input proportionally to how slow the device is.

Also, unlike with debouncing or throttling, deferred re-renders done by `useDeferredValue` are interruptible by default. This means that if React is in the middle of re-rendering a large list, but the user makes another keystroke, React will abandon that re-render, handle the keystroke, and then start rendering in the background again. By contrast, debouncing and throttling still produce a janky experience because they’re _blocking:_ they merely postpone the moment when rendering blocks the keystroke.

If the work you’re optimizing doesn’t happen during rendering, debouncing and throttling are still useful. For example, they can let you fire fewer network requests. You can also use these techniques together.

[PrevioususeDebugValue](/reference/react/useDebugValue)
[NextuseEffect](/reference/react/useEffect)

* * *

---

# useEffect – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useEffect[](#undefined "Link for this heading")

================================================

`useEffect` is a React Hook that lets you [synchronize a component with an external system.](/learn/synchronizing-with-effects)

    useEffect(setup, dependencies?)

*   [Reference](#reference)
    *   [`useEffect(setup, dependencies?)`](#useeffect)
        
*   [Usage](#usage)
    *   [Connecting to an external system](#connecting-to-an-external-system)
        
    *   [Wrapping Effects in custom Hooks](#wrapping-effects-in-custom-hooks)
        
    *   [Controlling a non-React widget](#controlling-a-non-react-widget)
        
    *   [Fetching data with Effects](#fetching-data-with-effects)
        
    *   [Specifying reactive dependencies](#specifying-reactive-dependencies)
        
    *   [Updating state based on previous state from an Effect](#updating-state-based-on-previous-state-from-an-effect)
        
    *   [Removing unnecessary object dependencies](#removing-unnecessary-object-dependencies)
        
    *   [Removing unnecessary function dependencies](#removing-unnecessary-function-dependencies)
        
    *   [Reading the latest props and state from an Effect](#reading-the-latest-props-and-state-from-an-effect)
        
    *   [Displaying different content on the server and the client](#displaying-different-content-on-the-server-and-the-client)
        
*   [Troubleshooting](#troubleshooting)
    *   [My Effect runs twice when the component mounts](#my-effect-runs-twice-when-the-component-mounts)
        
    *   [My Effect runs after every re-render](#my-effect-runs-after-every-re-render)
        
    *   [My Effect keeps re-running in an infinite cycle](#my-effect-keeps-re-running-in-an-infinite-cycle)
        
    *   [My cleanup logic runs even though my component didn’t unmount](#my-cleanup-logic-runs-even-though-my-component-didnt-unmount)
        
    *   [My Effect does something visual, and I see a flicker before it runs](#my-effect-does-something-visual-and-i-see-a-flicker-before-it-runs)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useEffect(setup, dependencies?)`[](#useeffect "Link for this heading")

Call `useEffect` at the top level of your component to declare an Effect:

    import { useState, useEffect } from 'react';import { createConnection } from './chat.js';function ChatRoom({ roomId }) {  const [serverUrl, setServerUrl] = useState('https://localhost:1234');  useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => {      connection.disconnect();    };  }, [serverUrl, roomId]);  // ...}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `setup`: The function with your Effect’s logic. Your setup function may also optionally return a _cleanup_ function. When your component is added to the DOM, React will run your setup function. After every re-render with changed dependencies, React will first run the cleanup function (if you provided it) with the old values, and then run your setup function with the new values. After your component is removed from the DOM, React will run your cleanup function.
    
*   **optional** `dependencies`: The list of all reactive values referenced inside of the `setup` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting)
    , it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison. If you omit this argument, your Effect will re-run after every re-render of the component. [See the difference between passing an array of dependencies, an empty array, and no dependencies at all.](#examples-dependencies)
    

#### Returns[](#returns "Link for Returns ")

`useEffect` returns `undefined`.

#### Caveats[](#caveats "Link for Caveats ")

*   `useEffect` 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.
    
*   If you’re **not trying to synchronize with some external system,** [you probably don’t need an Effect.](/learn/you-might-not-need-an-effect)
    
*   When Strict Mode is on, React will **run one extra development-only setup+cleanup cycle** before the first real setup. This is a stress-test that ensures that your cleanup logic “mirrors” your setup logic and that it stops or undoes whatever the setup is doing. If this causes a problem, [implement the cleanup function.](/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development)
    
*   If some of your dependencies are objects or functions defined inside the component, there is a risk that they will **cause the Effect to re-run more often than needed.** To fix this, remove unnecessary [object](#removing-unnecessary-object-dependencies)
     and [function](#removing-unnecessary-function-dependencies)
     dependencies. You can also [extract state updates](#updating-state-based-on-previous-state-from-an-effect)
     and [non-reactive logic](#reading-the-latest-props-and-state-from-an-effect)
     outside of your Effect.
    
*   If your Effect wasn’t caused by an interaction (like a click), React will generally let the browser **paint the updated screen first before running your Effect.** If your Effect is doing something visual (for example, positioning a tooltip), and the delay is noticeable (for example, it flickers), replace `useEffect` with [`useLayoutEffect`.](/reference/react/useLayoutEffect)
    
*   If your Effect is caused by an interaction (like a click), **React may run your Effect before the browser paints the updated screen**. This ensures that the result of the Effect can be observed by the event system. Usually, this works as expected. However, if you must defer the work until after paint, such as an `alert()`, you can use `setTimeout`. See [reactwg/react-18/128](https://github.com/reactwg/react-18/discussions/128)
     for more information.
    
*   Even if your Effect was caused by an interaction (like a click), **React may allow the browser to repaint the screen before processing the state updates inside your Effect.** Usually, this works as expected. However, if you must block the browser from repainting the screen, you need to replace `useEffect` with [`useLayoutEffect`.](/reference/react/useLayoutEffect)
    
*   Effects **only run on the client.** They don’t run during server rendering.
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Connecting to an external system[](#connecting-to-an-external-system "Link for Connecting to an external system ")

Some components need to stay connected to the network, some browser API, or a third-party library, while they are displayed on the page. These systems aren’t controlled by React, so they are called _external._

To [connect your component to some external system,](/learn/synchronizing-with-effects)
 call `useEffect` at the top level of your component:

    import { useState, useEffect } from 'react';import { createConnection } from './chat.js';function ChatRoom({ roomId }) {  const [serverUrl, setServerUrl] = useState('https://localhost:1234');  useEffect(() => {  	const connection = createConnection(serverUrl, roomId);    connection.connect();  	return () => {      connection.disconnect();  	};  }, [serverUrl, roomId]);  // ...}

You need to pass two arguments to `useEffect`:

1.  A _setup function_ with setup code that connects to that system.
    *   It should return a _cleanup function_ with cleanup code that disconnects from that system.
2.  A list of dependencies including every value from your component used inside of those functions.

**React calls your setup and cleanup functions whenever it’s necessary, which may happen multiple times:**

1.  Your setup code runs when your component is added to the page _(mounts)_.
2.  After every re-render of your component where the dependencies have changed:
    *   First, your cleanup code runs with the old props and state.
    *   Then, your setup code runs with the new props and state.
3.  Your cleanup code runs one final time after your component is removed from the page _(unmounts)._

**Let’s illustrate this sequence for the example above.**

When the `ChatRoom` component above gets added to the page, it will connect to the chat room with the initial `serverUrl` and `roomId`. If either `serverUrl` or `roomId` change as a result of a re-render (say, if the user picks a different chat room in a dropdown), your Effect will _disconnect from the previous room, and connect to the next one._ When the `ChatRoom` component is removed from the page, your Effect will disconnect one last time.

**To [help you find bugs,](/learn/synchronizing-with-effects#step-3-add-cleanup-if-needed)
 in development React runs setup and cleanup one extra time before the setup.** This is a stress-test that verifies your Effect’s logic is implemented correctly. If this causes visible issues, your cleanup function is missing some logic. The cleanup function should stop or undo whatever the setup function was doing. The rule of thumb is that the user shouldn’t be able to distinguish between the setup being called once (as in production) and a _setup_ → _cleanup_ → _setup_ sequence (as in development). [See common solutions.](/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development)

**Try to [write every Effect as an independent process](/learn/lifecycle-of-reactive-effects#each-effect-represents-a-separate-synchronization-process)
 and [think about a single setup/cleanup cycle at a time.](/learn/lifecycle-of-reactive-effects#thinking-from-the-effects-perspective)
** It shouldn’t matter whether your component is mounting, updating, or unmounting. When your cleanup logic correctly “mirrors” the setup logic, your Effect is resilient to running setup and cleanup as often as needed.

### Note

An Effect lets you [keep your component synchronized](/learn/synchronizing-with-effects)
 with some external system (like a chat service). Here, _external system_ means any piece of code that’s not controlled by React, such as:

*   A timer managed with [`setInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
     and [`clearInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
    .
*   An event subscription using [`window.addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
     and [`window.removeEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener)
    .
*   A third-party animation library with an API like `animation.start()` and `animation.reset()`.

**If you’re not connecting to any external system, [you probably don’t need an Effect.](/learn/you-might-not-need-an-effect)
**

#### Examples of connecting to an external system[](#examples-connecting "Link for Examples of connecting to an external system")

1. Connecting to a chat server 2. Listening to a global browser event 3. Triggering an animation 4. Controlling a modal dialog 5. Tracking element visibility

#### 

Example 1 of 5:

Connecting to a chat server[](#connecting-to-a-chat-server "Link for this heading")

In this example, the `ChatRoom` component uses an Effect to stay connected to an external system defined in `chat.js`. Press “Open chat” to make the `ChatRoom` component appear. This sandbox runs in development mode, so there is an extra connect-and-disconnect cycle, as [explained here.](/learn/synchronizing-with-effects#step-3-add-cleanup-if-needed)
 Try changing the `roomId` and `serverUrl` using the dropdown and the input, and see how the Effect re-connects to the chat. Press “Close chat” to see the Effect disconnect one last time.

App.jschat.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

function ChatRoom({ roomId }) {
  const \[serverUrl, setServerUrl\] = useState('https://localhost:1234');

  useEffect(() \=> {
    const connection = createConnection(serverUrl, roomId);
    connection.connect();
    return () \=> {
      connection.disconnect();
    };
  }, \[roomId, serverUrl\]);

  return (
    <\>
      <label\>
        Server URL:{' '}
        <input
          value\={serverUrl}
          onChange\={e \=> setServerUrl(e.target.value)}
        />
      </label\>
      <h1\>Welcome to the {roomId} room!</h1\>
    </\>
  );
}

export default function App() {
  const \[roomId, setRoomId\] = useState('general');
  const \[show, setShow\] = useState(false);
  return (
    <\>
      <label\>
        Choose the chat room:{' '}
        <select
          value\={roomId}
          onChange\={e \=> setRoomId(e.target.value)}
        \>
          <option value\="general"\>general</option\>
          <option value\="travel"\>travel</option\>
          <option value\="music"\>music</option\>
        </select\>
      </label\>
      <button onClick\={() \=> setShow(!show)}\>
        {show ? 'Close chat' : 'Open chat'}
      </button\>
      {show && <hr />}
      {show && <ChatRoom roomId\={roomId} />}
    </\>
  );
}

Show more

Next Example

* * *

### Wrapping Effects in custom Hooks[](#wrapping-effects-in-custom-hooks "Link for Wrapping Effects in custom Hooks ")

Effects are an [“escape hatch”:](/learn/escape-hatches)
 you use them when you need to “step outside React” and when there is no better built-in solution for your use case. If you find yourself often needing to manually write Effects, it’s usually a sign that you need to extract some [custom Hooks](/learn/reusing-logic-with-custom-hooks)
 for common behaviors your components rely on.

For example, this `useChatRoom` custom Hook “hides” the logic of your Effect behind a more declarative API:

    function useChatRoom({ serverUrl, roomId }) {  useEffect(() => {    const options = {      serverUrl: serverUrl,      roomId: roomId    };    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [roomId, serverUrl]);}

Then you can use it from any component like this:

    function ChatRoom({ roomId }) {  const [serverUrl, setServerUrl] = useState('https://localhost:1234');  useChatRoom({    roomId: roomId,    serverUrl: serverUrl  });  // ...

There are also many excellent custom Hooks for every purpose available in the React ecosystem.

[Learn more about wrapping Effects in custom Hooks.](/learn/reusing-logic-with-custom-hooks)

#### Examples of wrapping Effects in custom Hooks[](#examples-custom-hooks "Link for Examples of wrapping Effects in custom Hooks")

1. Custom `useChatRoom` Hook 2. Custom `useWindowListener` Hook 3. Custom `useIntersectionObserver` Hook

#### 

Example 1 of 3:

Custom `useChatRoom` Hook[](#custom-usechatroom-hook "Link for this heading")

This example is identical to one of the [earlier examples,](#examples-connecting)
 but the logic is extracted to a custom Hook.

App.jsuseChatRoom.jschat.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';
import { useChatRoom } from './useChatRoom.js';

function ChatRoom({ roomId }) {
  const \[serverUrl, setServerUrl\] = useState('https://localhost:1234');

  useChatRoom({
    roomId: roomId,
    serverUrl: serverUrl
  });

  return (
    <\>
      <label\>
        Server URL:{' '}
        <input
          value\={serverUrl}
          onChange\={e \=> setServerUrl(e.target.value)}
        />
      </label\>
      <h1\>Welcome to the {roomId} room!</h1\>
    </\>
  );
}

export default function App() {
  const \[roomId, setRoomId\] = useState('general');
  const \[show, setShow\] = useState(false);
  return (
    <\>
      <label\>
        Choose the chat room:{' '}
        <select
          value\={roomId}
          onChange\={e \=> setRoomId(e.target.value)}
        \>
          <option value\="general"\>general</option\>
          <option value\="travel"\>travel</option\>
          <option value\="music"\>music</option\>
        </select\>
      </label\>
      <button onClick\={() \=> setShow(!show)}\>
        {show ? 'Close chat' : 'Open chat'}
      </button\>
      {show && <hr />}
      {show && <ChatRoom roomId\={roomId} />}
    </\>
  );
}

Show more

Next Example

* * *

### Controlling a non-React widget[](#controlling-a-non-react-widget "Link for Controlling a non-React widget ")

Sometimes, you want to keep an external system synchronized to some prop or state of your component.

For example, if you have a third-party map widget or a video player component written without React, you can use an Effect to call methods on it that make its state match the current state of your React component. This Effect creates an instance of a `MapWidget` class defined in `map-widget.js`. When you change the `zoomLevel` prop of the `Map` component, the Effect calls the `setZoom()` on the class instance to keep it synchronized:

App.jsMap.jsmap-widget.js

Map.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef, useEffect } from 'react';
import { MapWidget } from './map-widget.js';

export default function Map({ zoomLevel }) {
  const containerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() \=> {
    if (mapRef.current === null) {
      mapRef.current = new MapWidget(containerRef.current);
    }

    const map = mapRef.current;
    map.setZoom(zoomLevel);
  }, \[zoomLevel\]);

  return (
    <div
      style\={{ width: 200, height: 200 }}
      ref\={containerRef}
    />
  );
}

Show more

In this example, a cleanup function is not needed because the `MapWidget` class manages only the DOM node that was passed to it. After the `Map` React component is removed from the tree, both the DOM node and the `MapWidget` class instance will be automatically garbage-collected by the browser JavaScript engine.

* * *

### Fetching data with Effects[](#fetching-data-with-effects "Link for Fetching data with Effects ")

You can use an Effect to fetch data for your component. Note that [if you use a framework,](/learn/start-a-new-react-project#production-grade-react-frameworks)
 using your framework’s data fetching mechanism will be a lot more efficient than writing Effects manually.

If you want to fetch data from an Effect manually, your code might look like this:

    import { useState, useEffect } from 'react';import { fetchBio } from './api.js';export default function Page() {  const [person, setPerson] = useState('Alice');  const [bio, setBio] = useState(null);  useEffect(() => {    let ignore = false;    setBio(null);    fetchBio(person).then(result => {      if (!ignore) {        setBio(result);      }    });    return () => {      ignore = true;    };  }, [person]);  // ...

Note the `ignore` variable which is initialized to `false`, and is set to `true` during cleanup. This ensures [your code doesn’t suffer from “race conditions”:](https://maxrozen.com/race-conditions-fetching-data-react-with-useeffect)
 network responses may arrive in a different order than you sent them.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { fetchBio } from './api.js';

export default function Page() {
  const \[person, setPerson\] = useState('Alice');
  const \[bio, setBio\] = useState(null);
  useEffect(() \=> {
    let ignore = false;
    setBio(null);
    fetchBio(person).then(result \=> {
      if (!ignore) {
        setBio(result);
      }
    });
    return () \=> {
      ignore = true;
    }
  }, \[person\]);

  return (
    <\>
      <select value\={person} onChange\={e \=> {
        setPerson(e.target.value);
      }}\>
        <option value\="Alice"\>Alice</option\>
        <option value\="Bob"\>Bob</option\>
        <option value\="Taylor"\>Taylor</option\>
      </select\>
      <hr />
      <p\><i\>{bio ?? 'Loading...'}</i\></p\>
    </\>
  );
}

Show more

You can also rewrite using the [`async` / `await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
 syntax, but you still need to provide a cleanup function:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { fetchBio } from './api.js';

export default function Page() {
  const \[person, setPerson\] = useState('Alice');
  const \[bio, setBio\] = useState(null);
  useEffect(() \=> {
    async function startFetching() {
      setBio(null);
      const result = await fetchBio(person);
      if (!ignore) {
        setBio(result);
      }
    }

    let ignore = false;
    startFetching();
    return () \=> {
      ignore = true;
    }
  }, \[person\]);

  return (
    <\>
      <select value\={person} onChange\={e \=> {
        setPerson(e.target.value);
      }}\>
        <option value\="Alice"\>Alice</option\>
        <option value\="Bob"\>Bob</option\>
        <option value\="Taylor"\>Taylor</option\>
      </select\>
      <hr />
      <p\><i\>{bio ?? 'Loading...'}</i\></p\>
    </\>
  );
}

Show more

Writing data fetching directly in Effects gets repetitive and makes it difficult to add optimizations like caching and server rendering later. [It’s easier to use a custom Hook—either your own or maintained by the community.](/learn/reusing-logic-with-custom-hooks#when-to-use-custom-hooks)

##### Deep Dive

#### What are good alternatives to data fetching in Effects?[](#what-are-good-alternatives-to-data-fetching-in-effects "Link for What are good alternatives to data fetching in Effects? ")

Show Details

Writing `fetch` calls inside Effects is a [popular way to fetch data](https://www.robinwieruch.de/react-hooks-fetch-data/)
, especially in fully client-side apps. This is, however, a very manual approach and it has significant downsides:

*   **Effects don’t run on the server.** This means that the initial server-rendered HTML will only include a loading state with no data. The client computer will have to download all JavaScript and render your app only to discover that now it needs to load the data. This is not very efficient.
*   **Fetching directly in Effects makes it easy to create “network waterfalls”.** You render the parent component, it fetches some data, renders the child components, and then they start fetching their data. If the network is not very fast, this is significantly slower than fetching all data in parallel.
*   **Fetching directly in Effects usually means you don’t preload or cache data.** For example, if the component unmounts and then mounts again, it would have to fetch the data again.
*   **It’s not very ergonomic.** There’s quite a bit of boilerplate code involved when writing `fetch` calls in a way that doesn’t suffer from bugs like [race conditions.](https://maxrozen.com/race-conditions-fetching-data-react-with-useeffect)
    

This list of downsides is not specific to React. It applies to fetching data on mount with any library. Like with routing, data fetching is not trivial to do well, so we recommend the following approaches:

*   **If you use a [framework](/learn/start-a-new-react-project#production-grade-react-frameworks)
    , use its built-in data fetching mechanism.** Modern React frameworks have integrated data fetching mechanisms that are efficient and don’t suffer from the above pitfalls.
*   **Otherwise, consider using or building a client-side cache.** Popular open source solutions include [React Query](https://tanstack.com/query/latest/)
    , [useSWR](https://swr.vercel.app/)
    , and [React Router 6.4+.](https://beta.reactrouter.com/en/main/start/overview)
     You can build your own solution too, in which case you would use Effects under the hood but also add logic for deduplicating requests, caching responses, and avoiding network waterfalls (by preloading data or hoisting data requirements to routes).

You can continue fetching data directly in Effects if neither of these approaches suit you.

* * *

### Specifying reactive dependencies[](#specifying-reactive-dependencies "Link for Specifying reactive dependencies ")

**Notice that you can’t “choose” the dependencies of your Effect.** Every reactive value used by your Effect’s code must be declared as a dependency. Your Effect’s dependency list is determined by the surrounding code:

    function ChatRoom({ roomId }) { // This is a reactive value  const [serverUrl, setServerUrl] = useState('https://localhost:1234'); // This is a reactive value too  useEffect(() => {    const connection = createConnection(serverUrl, roomId); // This Effect reads these reactive values    connection.connect();    return () => connection.disconnect();  }, [serverUrl, roomId]); // ✅ So you must specify them as dependencies of your Effect  // ...}

If either `serverUrl` or `roomId` change, your Effect will reconnect to the chat using the new values.

**[Reactive values](/learn/lifecycle-of-reactive-effects#effects-react-to-reactive-values)
 include props and all variables and functions declared directly inside of your component.** Since `roomId` and `serverUrl` are reactive values, you can’t remove them from the dependencies. If you try to omit them and [your linter is correctly configured for React,](/learn/editor-setup#linting)
 the linter will flag this as a mistake you need to fix:

    function ChatRoom({ roomId }) {  const [serverUrl, setServerUrl] = useState('https://localhost:1234');    useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => connection.disconnect();  }, []); // 🔴 React Hook useEffect has missing dependencies: 'roomId' and 'serverUrl'  // ...}

**To remove a dependency, you need to [“prove” to the linter that it _doesn’t need_ to be a dependency.](/learn/removing-effect-dependencies#removing-unnecessary-dependencies)
** For example, you can move `serverUrl` out of your component to prove that it’s not reactive and won’t change on re-renders:

    const serverUrl = 'https://localhost:1234'; // Not a reactive value anymorefunction ChatRoom({ roomId }) {  useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => connection.disconnect();  }, [roomId]); // ✅ All dependencies declared  // ...}

Now that `serverUrl` is not a reactive value (and can’t change on a re-render), it doesn’t need to be a dependency. **If your Effect’s code doesn’t use any reactive values, its dependency list should be empty (`[]`):**

    const serverUrl = 'https://localhost:1234'; // Not a reactive value anymoreconst roomId = 'music'; // Not a reactive value anymorefunction ChatRoom() {  useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => connection.disconnect();  }, []); // ✅ All dependencies declared  // ...}

[An Effect with empty dependencies](/learn/lifecycle-of-reactive-effects#what-an-effect-with-empty-dependencies-means)
 doesn’t re-run when any of your component’s props or state change.

### Pitfall

If you have an existing codebase, you might have some Effects that suppress the linter like this:

    useEffect(() => {  // ...  // 🔴 Avoid suppressing the linter like this:  // eslint-ignore-next-line react-hooks/exhaustive-deps}, []);

**When dependencies don’t match the code, there is a high risk of introducing bugs.** By suppressing the linter, you “lie” to React about the values your Effect depends on. [Instead, prove they’re unnecessary.](/learn/removing-effect-dependencies#removing-unnecessary-dependencies)

#### Examples of passing reactive dependencies[](#examples-dependencies "Link for Examples of passing reactive dependencies")

1. Passing a dependency array 2. Passing an empty dependency array 3. Passing no dependency array at all

#### 

Example 1 of 3:

Passing a dependency array[](#passing-a-dependency-array "Link for this heading")

If you specify the dependencies, your Effect runs **after the initial render _and_ after re-renders with changed dependencies.**

    useEffect(() => {  // ...}, [a, b]); // Runs again if a or b are different

In the below example, `serverUrl` and `roomId` are [reactive values,](/learn/lifecycle-of-reactive-effects#effects-react-to-reactive-values)
 so they both must be specified as dependencies. As a result, selecting a different room in the dropdown or editing the server URL input causes the chat to re-connect. However, since `message` isn’t used in the Effect (and so it isn’t a dependency), editing the message doesn’t re-connect to the chat.

App.jschat.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

function ChatRoom({ roomId }) {
  const \[serverUrl, setServerUrl\] = useState('https://localhost:1234');
  const \[message, setMessage\] = useState('');

  useEffect(() \=> {
    const connection = createConnection(serverUrl, roomId);
    connection.connect();
    return () \=> {
      connection.disconnect();
    };
  }, \[serverUrl, roomId\]);

  return (
    <\>
      <label\>
        Server URL:{' '}
        <input
          value\={serverUrl}
          onChange\={e \=> setServerUrl(e.target.value)}
        />
      </label\>
      <h1\>Welcome to the {roomId} room!</h1\>
      <label\>
        Your message:{' '}
        <input value\={message} onChange\={e \=> setMessage(e.target.value)} />
      </label\>
    </\>
  );
}

export default function App() {
  const \[show, setShow\] = useState(false);
  const \[roomId, setRoomId\] = useState('general');
  return (
    <\>
      <label\>
        Choose the chat room:{' '}
        <select
          value\={roomId}
          onChange\={e \=> setRoomId(e.target.value)}
        \>
          <option value\="general"\>general</option\>
          <option value\="travel"\>travel</option\>
          <option value\="music"\>music</option\>
        </select\>
        <button onClick\={() \=> setShow(!show)}\>
          {show ? 'Close chat' : 'Open chat'}
        </button\>
      </label\>
      {show && <hr />}
      {show && <ChatRoom roomId\={roomId}/>}
    </\>
  );
}

Show more

Next Example

* * *

### Updating state based on previous state from an Effect[](#updating-state-based-on-previous-state-from-an-effect "Link for Updating state based on previous state from an Effect ")

When you want to update state based on previous state from an Effect, you might run into a problem:

    function Counter() {  const [count, setCount] = useState(0);  useEffect(() => {    const intervalId = setInterval(() => {      setCount(count + 1); // You want to increment the counter every second...    }, 1000)    return () => clearInterval(intervalId);  }, [count]); // 🚩 ... but specifying `count` as a dependency always resets the interval.  // ...}

Since `count` is a reactive value, it must be specified in the list of dependencies. However, that causes the Effect to cleanup and setup again every time the `count` changes. This is not ideal.

To fix this, [pass the `c => c + 1` state updater](/reference/react/useState#updating-state-based-on-the-previous-state)
 to `setCount`:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';

export default function Counter() {
  const \[count, setCount\] = useState(0);

  useEffect(() \=> {
    const intervalId = setInterval(() \=> {
      setCount(c \=> c + 1); // ✅ Pass a state updater
    }, 1000);
    return () \=> clearInterval(intervalId);
  }, \[\]); // ✅ Now count is not a dependency

  return <h1\>{count}</h1\>;
}

Now that you’re passing `c => c + 1` instead of `count + 1`, [your Effect no longer needs to depend on `count`.](/learn/removing-effect-dependencies#are-you-reading-some-state-to-calculate-the-next-state)
 As a result of this fix, it won’t need to cleanup and setup the interval again every time the `count` changes.

* * *

### Removing unnecessary object dependencies[](#removing-unnecessary-object-dependencies "Link for Removing unnecessary object dependencies ")

If your Effect depends on an object or a function created during rendering, it might run too often. For example, this Effect re-connects after every render because the `options` object is [different for every render:](/learn/removing-effect-dependencies#does-some-reactive-value-change-unintentionally)

    const serverUrl = 'https://localhost:1234';function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  const options = { // 🚩 This object is created from scratch on every re-render    serverUrl: serverUrl,    roomId: roomId  };  useEffect(() => {    const connection = createConnection(options); // It's used inside the Effect    connection.connect();    return () => connection.disconnect();  }, [options]); // 🚩 As a result, these dependencies are always different on a re-render  // ...

Avoid using an object created during rendering as a dependency. Instead, create the object inside the Effect:

App.jschat.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

const serverUrl = 'https://localhost:1234';

function ChatRoom({ roomId }) {
  const \[message, setMessage\] = useState('');

  useEffect(() \=> {
    const options = {
      serverUrl: serverUrl,
      roomId: roomId
    };
    const connection = createConnection(options);
    connection.connect();
    return () \=> connection.disconnect();
  }, \[roomId\]);

  return (
    <\>
      <h1\>Welcome to the {roomId} room!</h1\>
      <input value\={message} onChange\={e \=> setMessage(e.target.value)} />
    </\>
  );
}

export default function App() {
  const \[roomId, setRoomId\] = useState('general');
  return (
    <\>
      <label\>
        Choose the chat room:{' '}
        <select
          value\={roomId}
          onChange\={e \=> setRoomId(e.target.value)}
        \>
          <option value\="general"\>general</option\>
          <option value\="travel"\>travel</option\>
          <option value\="music"\>music</option\>
        </select\>
      </label\>
      <hr />
      <ChatRoom roomId\={roomId} />
    </\>
  );
}

Show more

Now that you create the `options` object inside the Effect, the Effect itself only depends on the `roomId` string.

With this fix, typing into the input doesn’t reconnect the chat. Unlike an object which gets re-created, a string like `roomId` doesn’t change unless you set it to another value. [Read more about removing dependencies.](/learn/removing-effect-dependencies)

* * *

### Removing unnecessary function dependencies[](#removing-unnecessary-function-dependencies "Link for Removing unnecessary function dependencies ")

If your Effect depends on an object or a function created during rendering, it might run too often. For example, this Effect re-connects after every render because the `createOptions` function is [different for every render:](/learn/removing-effect-dependencies#does-some-reactive-value-change-unintentionally)

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  function createOptions() { // 🚩 This function is created from scratch on every re-render    return {      serverUrl: serverUrl,      roomId: roomId    };  }  useEffect(() => {    const options = createOptions(); // It's used inside the Effect    const connection = createConnection();    connection.connect();    return () => connection.disconnect();  }, [createOptions]); // 🚩 As a result, these dependencies are always different on a re-render  // ...

By itself, creating a function from scratch on every re-render is not a problem. You don’t need to optimize that. However, if you use it as a dependency of your Effect, it will cause your Effect to re-run after every re-render.

Avoid using a function created during rendering as a dependency. Instead, declare it inside the Effect:

App.jschat.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useEffect } from 'react';
import { createConnection } from './chat.js';

const serverUrl = 'https://localhost:1234';

function ChatRoom({ roomId }) {
  const \[message, setMessage\] = useState('');

  useEffect(() \=> {
    function createOptions() {
      return {
        serverUrl: serverUrl,
        roomId: roomId
      };
    }

    const options = createOptions();
    const connection = createConnection(options);
    connection.connect();
    return () \=> connection.disconnect();
  }, \[roomId\]);

  return (
    <\>
      <h1\>Welcome to the {roomId} room!</h1\>
      <input value\={message} onChange\={e \=> setMessage(e.target.value)} />
    </\>
  );
}

export default function App() {
  const \[roomId, setRoomId\] = useState('general');
  return (
    <\>
      <label\>
        Choose the chat room:{' '}
        <select
          value\={roomId}
          onChange\={e \=> setRoomId(e.target.value)}
        \>
          <option value\="general"\>general</option\>
          <option value\="travel"\>travel</option\>
          <option value\="music"\>music</option\>
        </select\>
      </label\>
      <hr />
      <ChatRoom roomId\={roomId} />
    </\>
  );
}

Show more

Now that you define the `createOptions` function inside the Effect, the Effect itself only depends on the `roomId` string. With this fix, typing into the input doesn’t reconnect the chat. Unlike a function which gets re-created, a string like `roomId` doesn’t change unless you set it to another value. [Read more about removing dependencies.](/learn/removing-effect-dependencies)

* * *

### Reading the latest props and state from an Effect[](#reading-the-latest-props-and-state-from-an-effect "Link for Reading the latest props and state from an Effect ")

### Under Construction

This section describes an **experimental API that has not yet been released** in a stable version of React.

By default, when you read a reactive value from an Effect, you have to add it as a dependency. This ensures that your Effect “reacts” to every change of that value. For most dependencies, that’s the behavior you want.

**However, sometimes you’ll want to read the _latest_ props and state from an Effect without “reacting” to them.** For example, imagine you want to log the number of the items in the shopping cart for every page visit:

    function Page({ url, shoppingCart }) {  useEffect(() => {    logVisit(url, shoppingCart.length);  }, [url, shoppingCart]); // ✅ All dependencies declared  // ...}

**What if you want to log a new page visit after every `url` change, but _not_ if only the `shoppingCart` changes?** You can’t exclude `shoppingCart` from dependencies without breaking the [reactivity rules.](#specifying-reactive-dependencies)
 However, you can express that you _don’t want_ a piece of code to “react” to changes even though it is called from inside an Effect. [Declare an _Effect Event_](/learn/separating-events-from-effects#declaring-an-effect-event)
 with the [`useEffectEvent`](/reference/react/experimental_useEffectEvent)
 Hook, and move the code reading `shoppingCart` inside of it:

    function Page({ url, shoppingCart }) {  const onVisit = useEffectEvent(visitedUrl => {    logVisit(visitedUrl, shoppingCart.length)  });  useEffect(() => {    onVisit(url);  }, [url]); // ✅ All dependencies declared  // ...}

**Effect Events are not reactive and must always be omitted from dependencies of your Effect.** This is what lets you put non-reactive code (where you can read the latest value of some props and state) inside of them. By reading `shoppingCart` inside of `onVisit`, you ensure that `shoppingCart` won’t re-run your Effect.

[Read more about how Effect Events let you separate reactive and non-reactive code.](/learn/separating-events-from-effects#reading-latest-props-and-state-with-effect-events)

* * *

### Displaying different content on the server and the client[](#displaying-different-content-on-the-server-and-the-client "Link for Displaying different content on the server and the client ")

If your app uses server rendering (either [directly](/reference/react-dom/server)
 or via a [framework](/learn/start-a-new-react-project#production-grade-react-frameworks)
), your component will render in two different environments. On the server, it will render to produce the initial HTML. On the client, React will run the rendering code again so that it can attach your event handlers to that HTML. This is why, for [hydration](/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html)
 to work, your initial render output must be identical on the client and the server.

In rare cases, you might need to display different content on the client. For example, if your app reads some data from [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
, it can’t possibly do that on the server. Here is how you could implement this:

    function MyComponent() {  const [didMount, setDidMount] = useState(false);  useEffect(() => {    setDidMount(true);  }, []);  if (didMount) {    // ... return client-only JSX ...  }  else {    // ... return initial JSX ...  }}

While the app is loading, the user will see the initial render output. Then, when it’s loaded and hydrated, your Effect will run and set `didMount` to `true`, triggering a re-render. This will switch to the client-only render output. Effects don’t run on the server, so this is why `didMount` was `false` during the initial server render.

Use this pattern sparingly. Keep in mind that users with a slow connection will see the initial content for quite a bit of time—potentially, many seconds—so you don’t want to make jarring changes to your component’s appearance. In many cases, you can avoid the need for this by conditionally showing different things with CSS.

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### My Effect runs twice when the component mounts[](#my-effect-runs-twice-when-the-component-mounts "Link for My Effect runs twice when the component mounts ")

When Strict Mode is on, in development, React runs setup and cleanup one extra time before the actual setup.

This is a stress-test that verifies your Effect’s logic is implemented correctly. If this causes visible issues, your cleanup function is missing some logic. The cleanup function should stop or undo whatever the setup function was doing. The rule of thumb is that the user shouldn’t be able to distinguish between the setup being called once (as in production) and a setup → cleanup → setup sequence (as in development).

Read more about [how this helps find bugs](/learn/synchronizing-with-effects#step-3-add-cleanup-if-needed)
 and [how to fix your logic.](/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development)

* * *

### My Effect runs after every re-render[](#my-effect-runs-after-every-re-render "Link for My Effect runs after every re-render ")

First, check that you haven’t forgotten to specify the dependency array:

    useEffect(() => {  // ...}); // 🚩 No dependency array: re-runs after every render!

If you’ve specified the dependency array but your Effect still re-runs in a loop, it’s because one of your dependencies is different on every re-render.

You can debug this problem by manually logging your dependencies to the console:

      useEffect(() => {    // ..  }, [serverUrl, roomId]);  console.log([serverUrl, roomId]);

You can then right-click on the arrays from different re-renders in the console and select “Store as a global variable” for both of them. Assuming the first one got saved as `temp1` and the second one got saved as `temp2`, you can then use the browser console to check whether each dependency in both arrays is the same:

    Object.is(temp1[0], temp2[0]); // Is the first dependency the same between the arrays?Object.is(temp1[1], temp2[1]); // Is the second dependency the same between the arrays?Object.is(temp1[2], temp2[2]); // ... and so on for every dependency ...

When you find the dependency that is different on every re-render, you can usually fix it in one of these ways:

*   [Updating state based on previous state from an Effect](#updating-state-based-on-previous-state-from-an-effect)
    
*   [Removing unnecessary object dependencies](#removing-unnecessary-object-dependencies)
    
*   [Removing unnecessary function dependencies](#removing-unnecessary-function-dependencies)
    
*   [Reading the latest props and state from an Effect](#reading-the-latest-props-and-state-from-an-effect)
    

As a last resort (if these methods didn’t help), wrap its creation with [`useMemo`](/reference/react/useMemo#memoizing-a-dependency-of-another-hook)
 or [`useCallback`](/reference/react/useCallback#preventing-an-effect-from-firing-too-often)
 (for functions).

* * *

### My Effect keeps re-running in an infinite cycle[](#my-effect-keeps-re-running-in-an-infinite-cycle "Link for My Effect keeps re-running in an infinite cycle ")

If your Effect runs in an infinite cycle, these two things must be true:

*   Your Effect is updating some state.
*   That state leads to a re-render, which causes the Effect’s dependencies to change.

Before you start fixing the problem, ask yourself whether your Effect is connecting to some external system (like DOM, network, a third-party widget, and so on). Why does your Effect need to set state? Does it synchronize with that external system? Or are you trying to manage your application’s data flow with it?

If there is no external system, consider whether [removing the Effect altogether](/learn/you-might-not-need-an-effect)
 would simplify your logic.

If you’re genuinely synchronizing with some external system, think about why and under what conditions your Effect should update the state. Has something changed that affects your component’s visual output? If you need to keep track of some data that isn’t used by rendering, a [ref](/reference/react/useRef#referencing-a-value-with-a-ref)
 (which doesn’t trigger re-renders) might be more appropriate. Verify your Effect doesn’t update the state (and trigger re-renders) more than needed.

Finally, if your Effect is updating the state at the right time, but there is still a loop, it’s because that state update leads to one of the Effect’s dependencies changing. [Read how to debug dependency changes.](/reference/react/useEffect#my-effect-runs-after-every-re-render)

* * *

### My cleanup logic runs even though my component didn’t unmount[](#my-cleanup-logic-runs-even-though-my-component-didnt-unmount "Link for My cleanup logic runs even though my component didn’t unmount ")

The cleanup function runs not only during unmount, but before every re-render with changed dependencies. Additionally, in development, React [runs setup+cleanup one extra time immediately after component mounts.](#my-effect-runs-twice-when-the-component-mounts)

If you have cleanup code without corresponding setup code, it’s usually a code smell:

    useEffect(() => {  // 🔴 Avoid: Cleanup logic without corresponding setup logic  return () => {    doSomething();  };}, []);

Your cleanup logic should be “symmetrical” to the setup logic, and should stop or undo whatever setup did:

      useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => {      connection.disconnect();    };  }, [serverUrl, roomId]);

[Learn how the Effect lifecycle is different from the component’s lifecycle.](/learn/lifecycle-of-reactive-effects#the-lifecycle-of-an-effect)

* * *

### My Effect does something visual, and I see a flicker before it runs[](#my-effect-does-something-visual-and-i-see-a-flicker-before-it-runs "Link for My Effect does something visual, and I see a flicker before it runs ")

If your Effect must block the browser from [painting the screen,](/learn/render-and-commit#epilogue-browser-paint)
 replace `useEffect` with [`useLayoutEffect`](/reference/react/useLayoutEffect)
. Note that **this shouldn’t be needed for the vast majority of Effects.** You’ll only need this if it’s crucial to run your Effect before the browser paint: for example, to measure and position a tooltip before the user sees it.

[PrevioususeDeferredValue](/reference/react/useDeferredValue)
[NextuseId](/reference/react/useId)

* * *

---

# useId – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useId[](#undefined "Link for this heading")

============================================

`useId` is a React Hook for generating unique IDs that can be passed to accessibility attributes.

    const id = useId()

*   [Reference](#reference)
    *   [`useId()`](#useid)
        
*   [Usage](#usage)
    *   [Generating unique IDs for accessibility attributes](#generating-unique-ids-for-accessibility-attributes)
        
    *   [Generating IDs for several related elements](#generating-ids-for-several-related-elements)
        
    *   [Specifying a shared prefix for all generated IDs](#specifying-a-shared-prefix-for-all-generated-ids)
        
    *   [Using the same ID prefix on the client and the server](#using-the-same-id-prefix-on-the-client-and-the-server)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useId()`[](#useid "Link for this heading")

Call `useId` at the top level of your component to generate a unique ID:

    import { useId } from 'react';function PasswordField() {  const passwordHintId = useId();  // ...

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

`useId` does not take any parameters.

#### Returns[](#returns "Link for Returns ")

`useId` returns a unique ID string associated with this particular `useId` call in this particular component.

#### Caveats[](#caveats "Link for Caveats ")

*   `useId` 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.
    
*   `useId` **should not be used to generate keys** in a list. [Keys should be generated from your data.](/learn/rendering-lists#where-to-get-your-key)
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Pitfall

**Do not call `useId` to generate keys in a list.** [Keys should be generated from your data.](/learn/rendering-lists#where-to-get-your-key)

### Generating unique IDs for accessibility attributes[](#generating-unique-ids-for-accessibility-attributes "Link for Generating unique IDs for accessibility attributes ")

Call `useId` at the top level of your component to generate a unique ID:

    import { useId } from 'react';function PasswordField() {  const passwordHintId = useId();  // ...

You can then pass the generated ID to different attributes:

    <>  <input type="password" aria-describedby={passwordHintId} />  <p id={passwordHintId}></>

**Let’s walk through an example to see when this is useful.**

[HTML accessibility attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA)
 like [`aria-describedby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby)
 let you specify that two tags are related to each other. For example, you can specify that an element (like an input) is described by another element (like a paragraph).

In regular HTML, you would write it like this:

    <label>  Password:  <input    type="password"    aria-describedby="password-hint"  /></label><p id="password-hint">  The password should contain at least 18 characters</p>

However, hardcoding IDs like this is not a good practice in React. A component may be rendered more than once on the page—but IDs have to be unique! Instead of hardcoding an ID, generate a unique ID with `useId`:

    import { useId } from 'react';function PasswordField() {  const passwordHintId = useId();  return (    <>      <label>        Password:        <input          type="password"          aria-describedby={passwordHintId}        />      </label>      <p id={passwordHintId}>        The password should contain at least 18 characters      </p>    </>  );}

Now, even if `PasswordField` appears multiple times on the screen, the generated IDs won’t clash.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useId } from 'react';

function PasswordField() {
  const passwordHintId = useId();
  return (
    <\>
      <label\>
        Password:
        <input
          type\="password"
          aria-describedby\={passwordHintId}
        />
      </label\>
      <p id\={passwordHintId}\>
        The password should contain at least 18 characters
      </p\>
    </\>
  );
}

export default function App() {
  return (
    <\>
      <h2\>Choose password</h2\>
      <PasswordField />
      <h2\>Confirm password</h2\>
      <PasswordField />
    </\>
  );
}

Show more

[Watch this video](https://www.youtube.com/watch?v=0dNzNcuEuOo)
 to see the difference in the user experience with assistive technologies.

### Pitfall

With [server rendering](/reference/react-dom/server)
, **`useId` requires an identical component tree on the server and the client**. If the trees you render on the server and the client don’t match exactly, the generated IDs won’t match.

##### Deep Dive

#### Why is useId better than an incrementing counter?[](#why-is-useid-better-than-an-incrementing-counter "Link for Why is useId better than an incrementing counter? ")

Show Details

You might be wondering why `useId` is better than incrementing a global variable like `nextId++`.

The primary benefit of `useId` is that React ensures that it works with [server rendering.](/reference/react-dom/server)
 During server rendering, your components generate HTML output. Later, on the client, [hydration](/reference/react-dom/client/hydrateRoot)
 attaches your event handlers to the generated HTML. For hydration to work, the client output must match the server HTML.

This is very difficult to guarantee with an incrementing counter because the order in which the Client Components are hydrated may not match the order in which the server HTML was emitted. By calling `useId`, you ensure that hydration will work, and the output will match between the server and the client.

Inside React, `useId` is generated from the “parent path” of the calling component. This is why, if the client and the server tree are the same, the “parent path” will match up regardless of rendering order.

* * *

### Generating IDs for several related elements[](#generating-ids-for-several-related-elements "Link for Generating IDs for several related elements ")

If you need to give IDs to multiple related elements, you can call `useId` to generate a shared prefix for them:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useId } from 'react';

export default function Form() {
  const id = useId();
  return (
    <form\>
      <label htmlFor\={id + '-firstName'}\>First Name:</label\>
      <input id\={id + '-firstName'} type\="text" />
      <hr />
      <label htmlFor\={id + '-lastName'}\>Last Name:</label\>
      <input id\={id + '-lastName'} type\="text" />
    </form\>
  );
}

This lets you avoid calling `useId` for every single element that needs a unique ID.

* * *

### Specifying a shared prefix for all generated IDs[](#specifying-a-shared-prefix-for-all-generated-ids "Link for Specifying a shared prefix for all generated IDs ")

If you render multiple independent React applications on a single page, pass `identifierPrefix` as an option to your [`createRoot`](/reference/react-dom/client/createRoot#parameters)
 or [`hydrateRoot`](/reference/react-dom/client/hydrateRoot)
 calls. This ensures that the IDs generated by the two different apps never clash because every identifier generated with `useId` will start with the distinct prefix you’ve specified.

index.jsindex.htmlApp.js

index.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createRoot } from 'react-dom/client';
import App from './App.js';
import './styles.css';

const root1 = createRoot(document.getElementById('root1'), {
  identifierPrefix: 'my-first-app-'
});
root1.render(<App />);

const root2 = createRoot(document.getElementById('root2'), {
  identifierPrefix: 'my-second-app-'
});
root2.render(<App />);

* * *

### Using the same ID prefix on the client and the server[](#using-the-same-id-prefix-on-the-client-and-the-server "Link for Using the same ID prefix on the client and the server ")

If you [render multiple independent React apps on the same page](#specifying-a-shared-prefix-for-all-generated-ids)
, and some of these apps are server-rendered, make sure that the `identifierPrefix` you pass to the [`hydrateRoot`](/reference/react-dom/client/hydrateRoot)
 call on the client side is the same as the `identifierPrefix` you pass to the [server APIs](/reference/react-dom/server)
 such as [`renderToPipeableStream`.](/reference/react-dom/server/renderToPipeableStream)

    // Serverimport { renderToPipeableStream } from 'react-dom/server';const { pipe } = renderToPipeableStream(  <App />,  { identifierPrefix: 'react-app1' });

    // Clientimport { hydrateRoot } from 'react-dom/client';const domNode = document.getElementById('root');const root = hydrateRoot(  domNode,  reactNode,  { identifierPrefix: 'react-app1' });

You do not need to pass `identifierPrefix` if you only have one React app on the page.

[PrevioususeEffect](/reference/react/useEffect)
[NextuseImperativeHandle](/reference/react/useImperativeHandle)

* * *

---

# useImperativeHandle – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useImperativeHandle[](#undefined "Link for this heading")

==========================================================

`useImperativeHandle` is a React Hook that lets you customize the handle exposed as a [ref.](/learn/manipulating-the-dom-with-refs)

    useImperativeHandle(ref, createHandle, dependencies?)

*   [Reference](#reference)
    *   [`useImperativeHandle(ref, createHandle, dependencies?)`](#useimperativehandle)
        
*   [Usage](#usage)
    *   [Exposing a custom ref handle to the parent component](#exposing-a-custom-ref-handle-to-the-parent-component)
        
    *   [Exposing your own imperative methods](#exposing-your-own-imperative-methods)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useImperativeHandle(ref, createHandle, dependencies?)`[](#useimperativehandle "Link for this heading")

Call `useImperativeHandle` at the top level of your component to customize the ref handle it exposes:

    import { useImperativeHandle } from 'react';function MyInput({ ref }) {  useImperativeHandle(ref, () => {    return {      // ... your methods ...    };  }, []);  // ...

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `ref`: The `ref` you received as a prop to the `MyInput` component.
    
*   `createHandle`: A function that takes no arguments and returns the ref handle you want to expose. That ref handle can have any type. Usually, you will return an object with the methods you want to expose.
    
*   **optional** `dependencies`: The list of all reactive values referenced inside of the `createHandle` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting)
    , it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison. If a re-render resulted in a change to some dependency, or if you omitted this argument, your `createHandle` function will re-execute, and the newly created handle will be assigned to the ref.
    

### Note

Starting with React 19, [`ref` is available as a prop.](/blog/2024/12/05/react-19#ref-as-a-prop)
 In React 18 and earlier, it was necessary to get the `ref` from [`forwardRef`.](/reference/react/forwardRef)

#### Returns[](#returns "Link for Returns ")

`useImperativeHandle` returns `undefined`.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Exposing a custom ref handle to the parent component[](#exposing-a-custom-ref-handle-to-the-parent-component "Link for Exposing a custom ref handle to the parent component ")

To expose a DOM node to the parent element, pass in the `ref` prop to the node.

    function MyInput({ ref }) {  return <input ref={ref} />;};

With the code above, [a ref to `MyInput` will receive the `<input>` DOM node.](/learn/manipulating-the-dom-with-refs)
 However, you can expose a custom value instead. To customize the exposed handle, call `useImperativeHandle` at the top level of your component:

    import { useImperativeHandle } from 'react';function MyInput({ ref }) {  useImperativeHandle(ref, () => {    return {      // ... your methods ...    };  }, []);  return <input />;};

Note that in the code above, the `ref` is no longer passed to the `<input>`.

For example, suppose you don’t want to expose the entire `<input>` DOM node, but you want to expose two of its methods: `focus` and `scrollIntoView`. To do this, keep the real browser DOM in a separate ref. Then use `useImperativeHandle` to expose a handle with only the methods that you want the parent component to call:

    import { useRef, useImperativeHandle } from 'react';function MyInput({ ref }) {  const inputRef = useRef(null);  useImperativeHandle(ref, () => {    return {      focus() {        inputRef.current.focus();      },      scrollIntoView() {        inputRef.current.scrollIntoView();      },    };  }, []);  return <input ref={inputRef} />;};

Now, if the parent component gets a ref to `MyInput`, it will be able to call the `focus` and `scrollIntoView` methods on it. However, it will not have full access to the underlying `<input>` DOM node.

App.jsMyInput.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef } from 'react';
import MyInput from './MyInput.js';

export default function Form() {
  const ref = useRef(null);

  function handleClick() {
    ref.current.focus();
    // This won't work because the DOM node isn't exposed:
    // ref.current.style.opacity = 0.5;
  }

  return (
    <form\>
      <MyInput placeholder\="Enter your name" ref\={ref} />
      <button type\="button" onClick\={handleClick}\>
        Edit
      </button\>
    </form\>
  );
}

Show more

* * *

### Exposing your own imperative methods[](#exposing-your-own-imperative-methods "Link for Exposing your own imperative methods ")

The methods you expose via an imperative handle don’t have to match the DOM methods exactly. For example, this `Post` component exposes a `scrollAndFocusAddComment` method via an imperative handle. This lets the parent `Page` scroll the list of comments _and_ focus the input field when you click the button:

App.jsPost.jsCommentList.jsAddComment.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef } from 'react';
import Post from './Post.js';

export default function Page() {
  const postRef = useRef(null);

  function handleClick() {
    postRef.current.scrollAndFocusAddComment();
  }

  return (
    <\>
      <button onClick\={handleClick}\>
        Write a comment
      </button\>
      <Post ref\={postRef} />
    </\>
  );
}

Show more

### Pitfall

**Do not overuse refs.** You should only use refs for _imperative_ behaviors that you can’t express as props: for example, scrolling to a node, focusing a node, triggering an animation, selecting text, and so on.

**If you can express something as a prop, you should not use a ref.** For example, instead of exposing an imperative handle like `{ open, close }` from a `Modal` component, it is better to take `isOpen` as a prop like `<Modal isOpen={isOpen} />`. [Effects](/learn/synchronizing-with-effects)
 can help you expose imperative behaviors via props.

[PrevioususeId](/reference/react/useId)
[NextuseInsertionEffect](/reference/react/useInsertionEffect)

* * *

---

# useInsertionEffect – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useInsertionEffect[](#undefined "Link for this heading")

=========================================================

### Pitfall

`useInsertionEffect` is for CSS-in-JS library authors. Unless you are working on a CSS-in-JS library and need a place to inject the styles, you probably want [`useEffect`](/reference/react/useEffect)
 or [`useLayoutEffect`](/reference/react/useLayoutEffect)
 instead.

`useInsertionEffect` allows inserting elements into the DOM before any layout Effects fire.

    useInsertionEffect(setup, dependencies?)

*   [Reference](#reference)
    *   [`useInsertionEffect(setup, dependencies?)`](#useinsertioneffect)
        
*   [Usage](#usage)
    *   [Injecting dynamic styles from CSS-in-JS libraries](#injecting-dynamic-styles-from-css-in-js-libraries)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useInsertionEffect(setup, dependencies?)`[](#useinsertioneffect "Link for this heading")

Call `useInsertionEffect` to insert styles before any Effects fire that may need to read layout:

    import { useInsertionEffect } from 'react';// Inside your CSS-in-JS libraryfunction useCSS(rule) {  useInsertionEffect(() => {    // ... inject <style> tags here ...  });  return rule;}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `setup`: The function with your Effect’s logic. Your setup function may also optionally return a _cleanup_ function. When your component is added to the DOM, but before any layout Effects fire, React will run your setup function. After every re-render with changed dependencies, React will first run the cleanup function (if you provided it) with the old values, and then run your setup function with the new values. When your component is removed from the DOM, React will run your cleanup function.
    
*   **optional** `dependencies`: The list of all reactive values referenced inside of the `setup` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting)
    , it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison algorithm. If you don’t specify the dependencies at all, your Effect will re-run after every re-render of the component.
    

#### Returns[](#returns "Link for Returns ")

`useInsertionEffect` returns `undefined`.

#### Caveats[](#caveats "Link for Caveats ")

*   Effects only run on the client. They don’t run during server rendering.
*   You can’t update state from inside `useInsertionEffect`.
*   By the time `useInsertionEffect` runs, refs are not attached yet.
*   `useInsertionEffect` may run either before or after the DOM has been updated. You shouldn’t rely on the DOM being updated at any particular time.
*   Unlike other types of Effects, which fire cleanup for every Effect and then setup for every Effect, `useInsertionEffect` will fire both cleanup and setup one component at a time. This results in an “interleaving” of the cleanup and setup functions.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Injecting dynamic styles from CSS-in-JS libraries[](#injecting-dynamic-styles-from-css-in-js-libraries "Link for Injecting dynamic styles from CSS-in-JS libraries ")

Traditionally, you would style React components using plain CSS.

    // In your JS file:<button className="success" />// In your CSS file:.success { color: green; }

Some teams prefer to author styles directly in JavaScript code instead of writing CSS files. This usually requires using a CSS-in-JS library or a tool. There are three common approaches to CSS-in-JS:

1.  Static extraction to CSS files with a compiler
2.  Inline styles, e.g. `<div style={{ opacity: 1 }}>`
3.  Runtime injection of `<style>` tags

If you use CSS-in-JS, we recommend a combination of the first two approaches (CSS files for static styles, inline styles for dynamic styles). **We don’t recommend runtime `<style>` tag injection for two reasons:**

1.  Runtime injection forces the browser to recalculate the styles a lot more often.
2.  Runtime injection can be very slow if it happens at the wrong time in the React lifecycle.

The first problem is not solvable, but `useInsertionEffect` helps you solve the second problem.

Call `useInsertionEffect` to insert the styles before any layout Effects fire:

    // Inside your CSS-in-JS librarylet isInserted = new Set();function useCSS(rule) {  useInsertionEffect(() => {    // As explained earlier, we don't recommend runtime injection of <style> tags.    // But if you have to do it, then it's important to do in useInsertionEffect.    if (!isInserted.has(rule)) {      isInserted.add(rule);      document.head.appendChild(getStyleForRule(rule));    }  });  return rule;}function Button() {  const className = useCSS('...');  return <div className={className} />;}

Similarly to `useEffect`, `useInsertionEffect` does not run on the server. If you need to collect which CSS rules have been used on the server, you can do it during rendering:

    let collectedRulesSet = new Set();function useCSS(rule) {  if (typeof window === 'undefined') {    collectedRulesSet.add(rule);  }  useInsertionEffect(() => {    // ...  });  return rule;}

[Read more about upgrading CSS-in-JS libraries with runtime injection to `useInsertionEffect`.](https://github.com/reactwg/react-18/discussions/110)

##### Deep Dive

#### How is this better than injecting styles during rendering or useLayoutEffect?[](#how-is-this-better-than-injecting-styles-during-rendering-or-uselayouteffect "Link for How is this better than injecting styles during rendering or useLayoutEffect? ")

Show Details

If you insert styles during rendering and React is processing a [non-blocking update,](/reference/react/useTransition#marking-a-state-update-as-a-non-blocking-transition)
 the browser will recalculate the styles every single frame while rendering a component tree, which can be **extremely slow.**

`useInsertionEffect` is better than inserting styles during [`useLayoutEffect`](/reference/react/useLayoutEffect)
 or [`useEffect`](/reference/react/useEffect)
 because it ensures that by the time other Effects run in your components, the `<style>` tags have already been inserted. Otherwise, layout calculations in regular Effects would be wrong due to outdated styles.

[PrevioususeImperativeHandle](/reference/react/useImperativeHandle)
[NextuseLayoutEffect](/reference/react/useLayoutEffect)

* * *

---

# useOptimistic – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useOptimistic[](#undefined "Link for this heading")

====================================================

`useOptimistic` is a React Hook that lets you optimistically update the UI.

      const [optimisticState, addOptimistic] = useOptimistic(state, updateFn);

*   [Reference](#reference)
    *   [`useOptimistic(state, updateFn)`](#use)
        
*   [Usage](#usage)
    *   [Optimistically updating forms](#optimistically-updating-with-forms)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useOptimistic(state, updateFn)`[](#use "Link for this heading")

`useOptimistic` is a React Hook that lets you show a different state while an async action is underway. It accepts some state as an argument and returns a copy of that state that can be different during the duration of an async action such as a network request. You provide a function that takes the current state and the input to the action, and returns the optimistic state to be used while the action is pending.

This state is called the “optimistic” state because it is usually used to immediately present the user with the result of performing an action, even though the action actually takes time to complete.

    import { useOptimistic } from 'react';function AppContainer() {  const [optimisticState, addOptimistic] = useOptimistic(    state,    // updateFn    (currentState, optimisticValue) => {      // merge and return new state      // with optimistic value    }  );}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `state`: the value to be returned initially and whenever no action is pending.
*   `updateFn(currentState, optimisticValue)`: a function that takes the current state and the optimistic value passed to `addOptimistic` and returns the resulting optimistic state. It must be a pure function. `updateFn` takes in two parameters. The `currentState` and the `optimisticValue`. The return value will be the merged value of the `currentState` and `optimisticValue`.

#### Returns[](#returns "Link for Returns ")

*   `optimisticState`: The resulting optimistic state. It is equal to `state` unless an action is pending, in which case it is equal to the value returned by `updateFn`.
*   `addOptimistic`: `addOptimistic` is the dispatching function to call when you have an optimistic update. It takes one argument, `optimisticValue`, of any type and will call the `updateFn` with `state` and `optimisticValue`.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Optimistically updating forms[](#optimistically-updating-with-forms "Link for Optimistically updating forms ")

The `useOptimistic` Hook provides a way to optimistically update the user interface before a background operation, like a network request, completes. In the context of forms, this technique helps to make apps feel more responsive. When a user submits a form, instead of waiting for the server’s response to reflect the changes, the interface is immediately updated with the expected outcome.

For example, when a user types a message into the form and hits the “Send” button, the `useOptimistic` Hook allows the message to immediately appear in the list with a “Sending…” label, even before the message is actually sent to a server. This “optimistic” approach gives the impression of speed and responsiveness. The form then attempts to truly send the message in the background. Once the server confirms the message has been received, the “Sending…” label is removed.

App.jsactions.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useOptimistic, useState, useRef } from "react";
import { deliverMessage } from "./actions.js";

function Thread({ messages, sendMessage }) {
  const formRef = useRef();
  async function formAction(formData) {
    addOptimisticMessage(formData.get("message"));
    formRef.current.reset();
    await sendMessage(formData);
  }
  const \[optimisticMessages, addOptimisticMessage\] = useOptimistic(
    messages,
    (state, newMessage) \=> \[\
      ...state,\
      {\
        text: newMessage,\
        sending: true\
      }\
    \]
  );

  return (
    <\>
      {optimisticMessages.map((message, index) \=> (
        <div key\={index}\>
          {message.text}
          {!!message.sending && <small\> (Sending...)</small\>}
        </div\>
      ))}
      <form action\={formAction} ref\={formRef}\>
        <input type\="text" name\="message" placeholder\="Hello!" />
        <button type\="submit"\>Send</button\>
      </form\>
    </\>
  );
}

export default function App() {
  const \[messages, setMessages\] = useState(\[\
    { text: "Hello there!", sending: false, key: 1 }\
  \]);
  async function sendMessage(formData) {
    const sentMessage = await deliverMessage(formData.get("message"));
    setMessages((messages) \=> \[...messages, { text: sentMessage }\]);
  }
  return <Thread messages\={messages} sendMessage\={sendMessage} />;
}

Show more

[PrevioususeMemo](/reference/react/useMemo)
[NextuseReducer](/reference/react/useReducer)

* * *

---

# useReducer – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useReducer[](#undefined "Link for this heading")

=================================================

`useReducer` is a React Hook that lets you add a [reducer](/learn/extracting-state-logic-into-a-reducer)
 to your component.

    const [state, dispatch] = useReducer(reducer, initialArg, init?)

*   [Reference](#reference)
    *   [`useReducer(reducer, initialArg, init?)`](#usereducer)
        
    *   [`dispatch` function](#dispatch)
        
*   [Usage](#usage)
    *   [Adding a reducer to a component](#adding-a-reducer-to-a-component)
        
    *   [Writing the reducer function](#writing-the-reducer-function)
        
    *   [Avoiding recreating the initial state](#avoiding-recreating-the-initial-state)
        
*   [Troubleshooting](#troubleshooting)
    *   [I’ve dispatched an action, but logging gives me the old state value](#ive-dispatched-an-action-but-logging-gives-me-the-old-state-value)
        
    *   [I’ve dispatched an action, but the screen doesn’t update](#ive-dispatched-an-action-but-the-screen-doesnt-update)
        
    *   [A part of my reducer state becomes undefined after dispatching](#a-part-of-my-reducer-state-becomes-undefined-after-dispatching)
        
    *   [My entire reducer state becomes undefined after dispatching](#my-entire-reducer-state-becomes-undefined-after-dispatching)
        
    *   [I’m getting an error: “Too many re-renders”](#im-getting-an-error-too-many-re-renders)
        
    *   [My reducer or initializer function runs twice](#my-reducer-or-initializer-function-runs-twice)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useReducer(reducer, initialArg, init?)`[](#usereducer "Link for this heading")

Call `useReducer` at the top level of your component to manage its state with a [reducer.](/learn/extracting-state-logic-into-a-reducer)

    import { useReducer } from 'react';function reducer(state, action) {  // ...}function MyComponent() {  const [state, dispatch] = useReducer(reducer, { age: 42 });  // ...

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `reducer`: The reducer function that specifies how the state gets updated. It must be pure, should take the state and action as arguments, and should return the next state. State and action can be of any types.
*   `initialArg`: The value from which the initial state is calculated. It can be a value of any type. How the initial state is calculated from it depends on the next `init` argument.
*   **optional** `init`: The initializer function that should return the initial state. If it’s not specified, the initial state is set to `initialArg`. Otherwise, the initial state is set to the result of calling `init(initialArg)`.

#### Returns[](#returns "Link for Returns ")

`useReducer` returns an array with exactly two values:

1.  The current state. During the first render, it’s set to `init(initialArg)` or `initialArg` (if there’s no `init`).
2.  The [`dispatch` function](#dispatch)
     that lets you update the state to a different value and trigger a re-render.

#### Caveats[](#caveats "Link for 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.
*   The `dispatch` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire. If the linter lets you omit a dependency without errors, it is safe to do. [Learn more about removing Effect dependencies.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
    
*   In Strict Mode, React will **call your reducer and initializer twice** in order to [help you find accidental impurities.](#my-reducer-or-initializer-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 your logic. The result from one of the calls is ignored.

* * *

### `dispatch` function[](#dispatch "Link for this heading")

The `dispatch` function returned by `useReducer` lets you update the state to a different value and trigger a re-render. You need to pass the action as the only argument to the `dispatch` function:

    const [state, dispatch] = useReducer(reducer, { age: 42 });function handleClick() {  dispatch({ type: 'incremented_age' });  // ...

React will set the next state to the result of calling the `reducer` function you’ve provided with the current `state` and the action you’ve passed to `dispatch`.

#### Parameters[](#dispatch-parameters "Link for Parameters ")

*   `action`: The action performed by the user. It can be a value of any type. By convention, an action is usually an object with a `type` property identifying it and, optionally, other properties with additional information.

#### Returns[](#dispatch-returns "Link for Returns ")

`dispatch` functions do not have a return value.

#### Caveats[](#setstate-caveats "Link for Caveats ")

*   The `dispatch` function **only updates the state variable for the _next_ render**. If you read the state variable after calling the `dispatch` function, [you will still get the old value](#ive-dispatched-an-action-but-logging-gives-me-the-old-state-value)
     that was on the screen before your call.
    
*   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`.](/reference/react-dom/flushSync)
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Adding a reducer to a component[](#adding-a-reducer-to-a-component "Link for Adding a reducer to a component ")

Call `useReducer` at the top level of your component to manage state with a [reducer.](/learn/extracting-state-logic-into-a-reducer)

    import { useReducer } from 'react';function reducer(state, action) {  // ...}function MyComponent() {  const [state, dispatch] = useReducer(reducer, { age: 42 });  // ...

`useReducer` returns an array with exactly two items:

1.  The current state of this state variable, initially set to the initial state you provided.
2.  The `dispatch` function that lets you change it in response to interaction.

To update what’s on the screen, call `dispatch` with an object representing what the user did, called an _action_:

    function handleClick() {  dispatch({ type: 'incremented_age' });}

React will pass the current state and the action to your reducer function. Your reducer will calculate and return the next state. React will store that next state, render your component with it, and update the UI.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useReducer } from 'react';

function reducer(state, action) {
  if (action.type === 'incremented\_age') {
    return {
      age: state.age + 1
    };
  }
  throw Error('Unknown action.');
}

export default function Counter() {
  const \[state, dispatch\] = useReducer(reducer, { age: 42 });

  return (
    <\>
      <button onClick\={() \=> {
        dispatch({ type: 'incremented\_age' })
      }}\>
        Increment age
      </button\>
      <p\>Hello! You are {state.age}.</p\>
    </\>
  );
}

Show more

`useReducer` is very similar to [`useState`](/reference/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)

* * *

### Writing the reducer function[](#writing-the-reducer-function "Link for Writing the reducer function ")

A reducer function is declared like this:

    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`, calculate and return some next state.

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      return {        name: state.name,        age: state.age + 1      };    }    case 'changed_name': {      return {        name: action.nextName,        age: state.age      };    }  }  throw Error('Unknown action: ' + action.type);}

Actions can have any shape. By convention, it’s common to pass objects with a `type` property identifying the action. It should include the minimal necessary information that the reducer needs to compute the next state.

    function Form() {  const [state, dispatch] = useReducer(reducer, { name: 'Taylor', age: 42 });    function handleButtonClick() {    dispatch({ type: 'incremented_age' });  }  function handleInputChange(e) {    dispatch({      type: 'changed_name',      nextName: e.target.value    });  }  // ...

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.

### Pitfall

State is read-only. Don’t modify any objects or arrays in state:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      // 🚩 Don't mutate an object in state like this:      state.age = state.age + 1;      return state;    }

Instead, always return new objects from your reducer:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      // ✅ Instead, return a new object      return {        ...state,        age: state.age + 1      };    }

Read [updating objects in state](/learn/updating-objects-in-state)
 and [updating arrays in state](/learn/updating-arrays-in-state)
 to learn more.

#### Basic useReducer examples[](#examples-basic "Link for Basic useReducer examples")

1. Form (object) 2. Todo list (array) 3. Writing concise update logic with Immer

#### 

Example 1 of 3:

Form (object)[](#form-object "Link for this heading")

In this example, the reducer manages a state object with two fields: `name` and `age`.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useReducer } from 'react';

function reducer(state, action) {
  switch (action.type) {
    case 'incremented\_age': {
      return {
        name: state.name,
        age: state.age + 1
      };
    }
    case 'changed\_name': {
      return {
        name: action.nextName,
        age: state.age
      };
    }
  }
  throw Error('Unknown action: ' + action.type);
}

const initialState = { name: 'Taylor', age: 42 };

export default function Form() {
  const \[state, dispatch\] = useReducer(reducer, initialState);

  function handleButtonClick() {
    dispatch({ type: 'incremented\_age' });
  }

  function handleInputChange(e) {
    dispatch({
      type: 'changed\_name',
      nextName: e.target.value
    }); 
  }

  return (
    <\>
      <input
        value\={state.name}
        onChange\={handleInputChange}
      />
      <button onClick\={handleButtonClick}\>
        Increment age
      </button\>
      <p\>Hello, {state.name}. You are {state.age}.</p\>
    </\>
  );
}

Show more

Next Example

* * *

### Avoiding recreating the initial state[](#avoiding-recreating-the-initial-state "Link for Avoiding recreating the initial state ")

React saves the initial state once and ignores it on the next renders.

    function createInitialState(username) {  // ...}function TodoList({ username }) {  const [state, dispatch] = useReducer(reducer, createInitialState(username));  // ...

Although the result of `createInitialState(username)` is only used for the initial render, you’re still calling this function on every render. This can be wasteful if it’s creating large arrays or performing expensive calculations.

To solve this, you may **pass it as an _initializer_ function** to `useReducer` as the third argument instead:

    function createInitialState(username) {  // ...}function TodoList({ username }) {  const [state, dispatch] = useReducer(reducer, username, createInitialState);  // ...

Notice that you’re passing `createInitialState`, which is the _function itself_, and not `createInitialState()`, which is the result of calling it. This way, the initial state does not get re-created after initialization.

In the above example, `createInitialState` takes a `username` argument. If your initializer doesn’t need any information to compute the initial state, you may pass `null` as the second argument to `useReducer`.

#### The difference between passing an initializer and passing the initial state directly[](#examples-initializer "Link for The difference between passing an initializer and passing the initial state directly")

1. Passing the initializer function 2. Passing the initial state directly

#### 

Example 1 of 2:

Passing the initializer function[](#passing-the-initializer-function "Link for this heading")

This example passes the initializer function, so the `createInitialState` function only runs during initialization. It does not run when component re-renders, such as when you type into the input.

TodoList.js

TodoList.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useReducer } from 'react';

function createInitialState(username) {
  const initialTodos = \[\];
  for (let i = 0; i < 50; i++) {
    initialTodos.push({
      id: i,
      text: username + "'s task #" + (i + 1)
    });
  }
  return {
    draft: '',
    todos: initialTodos,
  };
}

function reducer(state, action) {
  switch (action.type) {
    case 'changed\_draft': {
      return {
        draft: action.nextDraft,
        todos: state.todos,
      };
    };
    case 'added\_todo': {
      return {
        draft: '',
        todos: \[{\
          id: state.todos.length,\
          text: state.draft\
        }, ...state.todos\]
      }
    }
  }
  throw Error('Unknown action: ' + action.type);
}

export default function TodoList({ username }) {
  const \[state, dispatch\] = useReducer(
    reducer,
    username,
    createInitialState
  );
  return (
    <\>
      <input
        value\={state.draft}
        onChange\={e \=> {
          dispatch({
            type: 'changed\_draft',
            nextDraft: e.target.value
          })
        }}
      />
      <button onClick\={() \=> {
        dispatch({ type: 'added\_todo' });
      }}\>Add</button\>
      <ul\>
        {state.todos.map(item \=> (
          <li key\={item.id}\>
            {item.text}
          </li\>
        ))}
      </ul\>
    </\>
  );
}

Show more

Next Example

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### I’ve dispatched an action, but logging gives me the old state value[](#ive-dispatched-an-action-but-logging-gives-me-the-old-state-value "Link for I’ve dispatched an action, but logging gives me the old state value ")

Calling the `dispatch` function **does not change state in the running code**:

    function handleClick() {  console.log(state.age);  // 42  dispatch({ type: 'incremented_age' }); // Request a re-render with 43  console.log(state.age);  // Still 42!  setTimeout(() => {    console.log(state.age); // Also 42!  }, 5000);}

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:

    const action = { type: 'incremented_age' };dispatch(action);const nextState = reducer(state, action);console.log(state);     // { age: 42 }console.log(nextState); // { age: 43 }

* * *

### I’ve dispatched an action, but the screen doesn’t update[](#ive-dispatched-an-action-but-the-screen-doesnt-update "Link for I’ve dispatched an action, but the screen doesn’t update ")

React will **ignore your update if the next state is equal to the previous state,** as determined by an [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
 comparison. This usually happens when you change an object or an array in state directly:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      // 🚩 Wrong: mutating existing object      state.age++;      return state;    }    case 'changed_name': {      // 🚩 Wrong: mutating existing object      state.name = action.nextName;      return state;    }    // ...  }}

You mutated an existing `state` object and returned it, so React ignored the update. To fix this, you need to ensure that you’re always [updating objects in state](/learn/updating-objects-in-state)
 and [updating arrays in state](/learn/updating-arrays-in-state)
 instead of mutating them:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      // ✅ Correct: creating a new object      return {        ...state,        age: state.age + 1      };    }    case 'changed_name': {      // ✅ Correct: creating a new object      return {        ...state,        name: action.nextName      };    }    // ...  }}

* * *

### A part of my reducer state becomes undefined after dispatching[](#a-part-of-my-reducer-state-becomes-undefined-after-dispatching "Link for A part of my reducer state becomes undefined after dispatching ")

Make sure that every `case` branch **copies all of the existing fields** when returning the new state:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      return {        ...state, // Don't forget this!        age: state.age + 1      };    }    // ...

Without `...state` above, the returned next state would only contain the `age` field and nothing else.

* * *

### My entire reducer state becomes undefined after dispatching[](#my-entire-reducer-state-becomes-undefined-after-dispatching "Link for My entire reducer state becomes undefined after dispatching ")

If your state unexpectedly becomes `undefined`, you’re likely forgetting to `return` state in one of the cases, or your action type doesn’t match any of the `case` statements. To find why, throw an error outside the `switch`:

    function reducer(state, action) {  switch (action.type) {    case 'incremented_age': {      // ...    }    case 'edited_name': {      // ...    }  }  throw Error('Unknown action: ' + action.type);}

You can also use a static type checker like TypeScript to catch such mistakes.

* * *

### I’m getting an error: “Too many re-renders”[](#im-getting-an-error-too-many-re-renders "Link for I’m getting an error: “Too many re-renders” ")

You might get an error that says: `Too many re-renders. React limits the number of renders to prevent an infinite loop.` Typically, this means that you’re unconditionally dispatching an action _during render_, so your component enters a loop: render, dispatch (which causes a render), render, dispatch (which causes a render), and so on. Very often, this is caused by a mistake in specifying an event handler:

    // 🚩 Wrong: calls the handler during renderreturn <button onClick={handleClick()}>Click me</button>// ✅ Correct: passes down the event handlerreturn <button onClick={handleClick}>Click me</button>// ✅ Correct: passes down an inline functionreturn <button onClick={(e) => handleClick(e)}>Click me</button>

If you can’t find the cause of this error, click on the arrow next to the error in the console and look through the JavaScript stack to find the specific `dispatch` function call responsible for the error.

* * *

### My reducer or initializer function runs twice[](#my-reducer-or-initializer-function-runs-twice "Link for My reducer or initializer function runs twice ")

In [Strict Mode](/reference/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.

For example, this impure reducer function mutates an array in state:

    function reducer(state, action) {  switch (action.type) {    case 'added_todo': {      // 🚩 Mistake: mutating state      state.todos.push({ id: nextId++, text: action.text });      return state;    }    // ...  }}

Because React calls your reducer function twice, you’ll see the todo was added twice, so you’ll know that there is a mistake. In this example, you can fix the mistake by [replacing the array instead of mutating it](/learn/updating-arrays-in-state#adding-to-an-array)
:

    function reducer(state, action) {  switch (action.type) {    case 'added_todo': {      // ✅ Correct: replacing with new state      return {        ...state,        todos: [          ...state.todos,          { id: nextId++, text: action.text }        ]      };    }    // ...  }}

Now that this reducer function is pure, calling it an extra time doesn’t make a difference in behavior. This is why React calling it twice helps you find mistakes. **Only component, initializer, and reducer functions need to be pure.** Event handlers don’t need to be pure, so React will never call your event handlers twice.

Read [keeping components pure](/learn/keeping-components-pure)
 to learn more.

[PrevioususeOptimistic](/reference/react/useOptimistic)
[NextuseRef](/reference/react/useRef)

* * *

---

# useMemo – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useMemo[](#undefined "Link for this heading")

==============================================

`useMemo` is a React Hook that lets you cache the result of a calculation between re-renders.

    const cachedValue = useMemo(calculateValue, dependencies)

*   [Reference](#reference)
    *   [`useMemo(calculateValue, dependencies)`](#usememo)
        
*   [Usage](#usage)
    *   [Skipping expensive recalculations](#skipping-expensive-recalculations)
        
    *   [Skipping re-rendering of components](#skipping-re-rendering-of-components)
        
    *   [Preventing an Effect from firing too often](#preventing-an-effect-from-firing-too-often)
        
    *   [Memoizing a dependency of another Hook](#memoizing-a-dependency-of-another-hook)
        
    *   [Memoizing a function](#memoizing-a-function)
        
*   [Troubleshooting](#troubleshooting)
    *   [My calculation runs twice on every re-render](#my-calculation-runs-twice-on-every-re-render)
        
    *   [My `useMemo` call is supposed to return an object, but returns undefined](#my-usememo-call-is-supposed-to-return-an-object-but-returns-undefined)
        
    *   [Every time my component renders, the calculation in `useMemo` re-runs](#every-time-my-component-renders-the-calculation-in-usememo-re-runs)
        
    *   [I need to call `useMemo` for each list item in a loop, but it’s not allowed](#i-need-to-call-usememo-for-each-list-item-in-a-loop-but-its-not-allowed)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useMemo(calculateValue, dependencies)`[](#usememo "Link for this heading")

Call `useMemo` at the top level of your component to cache a calculation between re-renders:

    import { useMemo } from 'react';function TodoList({ todos, tab }) {  const visibleTodos = useMemo(    () => filterTodos(todos, tab),    [todos, tab]  );  // ...}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `calculateValue`: The function calculating the value that you want to cache. It should be pure, should take no arguments, and should return a value of any type. React will call your function during the initial render. On next renders, React will return the same value again if the `dependencies` have not changed since the last render. Otherwise, it will call `calculateValue`, return its result, and store it so it can be reused later.
    
*   `dependencies`: The list of all reactive values referenced inside of the `calculateValue` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting)
    , it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like `[dep1, dep2, dep3]`. React will compare each dependency with its previous value using the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
     comparison.
    

#### Returns[](#returns "Link for Returns ")

On the initial render, `useMemo` returns the result of calling `calculateValue` with no arguments.

During next renders, it will either return an already stored value from the last render (if the dependencies haven’t changed), or call `calculateValue` again, and return the result that `calculateValue` has returned.

#### Caveats[](#caveats "Link for 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 your logic. 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 be fine if you rely on `useMemo` solely as a performance optimization. Otherwise, a [state variable](/reference/react/useState#avoiding-recreating-the-initial-state)
     or a [ref](/reference/react/useRef#avoiding-recreating-the-ref-contents)
     may be more appropriate.

### Note

Caching return values like this is also known as [_memoization_,](https://en.wikipedia.org/wiki/Memoization)
 which is why this Hook is called `useMemo`.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Skipping expensive recalculations[](#skipping-expensive-recalculations "Link for Skipping expensive recalculations ")

To cache a calculation between re-renders, wrap it in a `useMemo` call at the top level of your component:

    import { useMemo } from 'react';function TodoList({ todos, tab, theme }) {  const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);  // ...}

You need to pass two things to `useMemo`:

1.  A calculation function that takes no arguments, like `() =>`, and returns what you wanted to calculate.
2.  A list of dependencies including every value within your component that’s used inside your calculation.

On the initial render, the value you’ll get from `useMemo` will be the result of calling your calculation.

On every subsequent render, React will compare the dependencies with the dependencies you passed during the last render. If none of the dependencies have changed (compared with [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
), `useMemo` will return the value you already calculated before. Otherwise, React will re-run your calculation and return the new value.

In other words, `useMemo` caches a calculation result between re-renders until its dependencies change.

**Let’s walk through an example to see when this is useful.**

By default, React will re-run the entire body of your component every time that it re-renders. For example, if this `TodoList` updates its state or receives new props from its parent, the `filterTodos` function will re-run:

    function TodoList({ todos, tab, theme }) {  const visibleTodos = filterTodos(todos, tab);  // ...}

Usually, this isn’t a problem because most calculations are very fast. However, if you’re filtering or transforming a large array, or doing some expensive computation, you might want to skip doing it again if data hasn’t changed. If both `todos` and `tab` are the same as they were during the last render, wrapping the calculation in `useMemo` like earlier lets you reuse `visibleTodos` you’ve already calculated before.

This type of caching is called _[memoization.](https://en.wikipedia.org/wiki/Memoization)
_

### Note

**You should only rely on `useMemo` as a performance optimization.** If your code doesn’t work without it, find the underlying problem and fix it first. Then you may add `useMemo` to improve performance.

##### Deep Dive

#### How to tell if a calculation is expensive?[](#how-to-tell-if-a-calculation-is-expensive "Link for How to tell if a calculation is expensive? ")

Show Details

In general, unless you’re creating or looping over thousands of objects, it’s probably not expensive. If you want to get more confidence, you can add a console log to measure the time spent in a piece of code:

    console.time('filter array');const visibleTodos = filterTodos(todos, tab);console.timeEnd('filter array');

Perform the interaction you’re measuring (for example, typing into the input). You will then see logs like `filter array: 0.15ms` in your console. If the overall logged time adds up to a significant amount (say, `1ms` or more), it might make sense to memoize that calculation. As an experiment, you can then wrap the calculation in `useMemo` to verify whether the total logged time has decreased for that interaction or not:

    console.time('filter array');const visibleTodos = useMemo(() => {  return filterTodos(todos, tab); // Skipped if todos and tab haven't changed}, [todos, tab]);console.timeEnd('filter array');

`useMemo` won’t make the _first_ render faster. It only helps you skip unnecessary work on updates.

Keep in mind that your machine is probably faster than your users’ so it’s a good idea to test the performance with an artificial slowdown. For example, Chrome offers a [CPU Throttling](https://developer.chrome.com/blog/new-in-devtools-61/#throttling)
 option for this.

Also note that measuring performance in development will not give you the most accurate results. (For example, when [Strict Mode](/reference/react/StrictMode)
 is on, you will see each component render twice rather than once.) To get the most accurate timings, build your app for production and test it on a device like your users have.

##### Deep Dive

#### Should you add useMemo everywhere?[](#should-you-add-usememo-everywhere "Link for Should you add useMemo everywhere? ")

Show Details

If your app is like this site, and most interactions are coarse (like replacing a page or an entire section), memoization is usually unnecessary. On the other hand, if your app is more like a drawing editor, and most interactions are granular (like moving shapes), then you might find memoization very helpful.

Optimizing with `useMemo` is only valuable in a few cases:

*   The calculation you’re putting in `useMemo` is noticeably slow, and its dependencies rarely change.
*   You pass it as a prop to a component wrapped in [`memo`.](/reference/react/memo)
     You want to skip re-rendering if the value hasn’t changed. Memoization lets your component re-render only when dependencies aren’t 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.`](/reference/react/useEffect)
    

There is no benefit to wrapping a calculation in `useMemo` 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.

**In practice, you can make a lot of memoization unnecessary by following a few principles:**

1.  When a component visually wraps other components, let it [accept JSX as children.](/learn/passing-props-to-a-component#passing-jsx-as-children)
     This way, when the wrapper component updates its own state, React knows that its children don’t need to re-render.
2.  Prefer local state and don’t [lift state up](/learn/sharing-state-between-components)
     any further than necessary. For example, don’t keep transient state like forms and whether an item is hovered at the top of your tree or in a global state library.
3.  Keep your [rendering logic pure.](/learn/keeping-components-pure)
     If re-rendering a component causes a problem or produces some noticeable visual artifact, it’s a bug in your component! Fix the bug instead of adding memoization.
4.  Avoid [unnecessary Effects that update state.](/learn/you-might-not-need-an-effect)
     Most performance problems in React apps are caused by chains of updates originating from Effects that cause your components to render over and over.
5.  Try to [remove unnecessary dependencies from your Effects.](/learn/removing-effect-dependencies)
     For example, instead of memoization, it’s often simpler to move some object or a function inside an Effect or outside the component.

If a specific interaction still feels laggy, [use the React Developer Tools profiler](https://legacy.reactjs.org/blog/2018/09/10/introducing-the-react-profiler.html)
 to see which components would benefit the most from memoization, and add memoization where needed. These principles make your components easier to debug and understand, so it’s good to follow them in any case. In the long term, we’re researching [doing granular memoization automatically](https://www.youtube.com/watch?v=lGEMwh32soc)
 to solve this once and for all.

#### The difference between useMemo and calculating a value directly[](#examples-recalculation "Link for The difference between useMemo and calculating a value directly")

1. Skipping recalculation with `useMemo` 2. Always recalculating a value

#### 

Example 1 of 2:

Skipping recalculation with `useMemo`[](#skipping-recalculation-with-usememo "Link for this heading")

In this example, the `filterTodos` implementation is **artificially slowed down** so that you can see what happens when some JavaScript function you’re calling during rendering is genuinely slow. Try switching the tabs and toggling the theme.

Switching the tabs feels slow because it forces the slowed down `filterTodos` to re-execute. That’s expected because the `tab` has changed, and so the entire calculation _needs_ to re-run. (If you’re curious why it runs twice, it’s explained [here.](#my-calculation-runs-twice-on-every-re-render)
)

Toggle the theme. **Thanks to `useMemo`, it’s fast despite the artificial slowdown!** The slow `filterTodos` call was skipped because both `todos` and `tab` (which you pass as dependencies to `useMemo`) haven’t changed since the last render.

App.jsTodoList.jsutils.js

TodoList.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useMemo } from 'react';
import { filterTodos } from './utils.js'

export default function TodoList({ todos, theme, tab }) {
  const visibleTodos = useMemo(
    () \=> filterTodos(todos, tab),
    \[todos, tab\]
  );
  return (
    <div className\={theme}\>
      <p\><b\>Note: <code\>filterTodos</code\> is artificially slowed down!</b\></p\>
      <ul\>
        {visibleTodos.map(todo \=> (
          <li key\={todo.id}\>
            {todo.completed ?
              <s\>{todo.text}</s\> :
              todo.text
            }
          </li\>
        ))}
      </ul\>
    </div\>
  );
}

Show more

Next Example

* * *

### Skipping re-rendering of components[](#skipping-re-rendering-of-components "Link for Skipping re-rendering of components ")

In some cases, `useMemo` can also help you optimize performance of re-rendering child components. To illustrate this, let’s say this `TodoList` component passes the `visibleTodos` as a prop to the child `List` component:

    export default function TodoList({ todos, tab, theme }) {  // ...  return (    <div className={theme}>      <List items={visibleTodos} />    </div>  );}

You’ve noticed that toggling the `theme` prop freezes the app for a moment, but if you remove `<List />` from your JSX, it feels fast. This tells you that it’s worth trying to optimize the `List` component.

**By default, when a component re-renders, React re-renders all of its children recursively.** This is why, when `TodoList` re-renders with a different `theme`, the `List` component _also_ re-renders. This is fine for components that don’t require much calculation to re-render. But if you’ve verified that a re-render is slow, you can tell `List` to skip re-rendering when its props are the same as on last render by wrapping it in [`memo`:](/reference/react/memo)

    import { memo } from 'react';const List = memo(function List({ items }) {  // ...});

**With this change, `List` will skip re-rendering if all of its props are the _same_ as on the last render.** This is where caching the calculation becomes important! Imagine that you calculated `visibleTodos` without `useMemo`:

    export default function TodoList({ todos, tab, theme }) {  // Every time the theme changes, this will be a different array...  const visibleTodos = filterTodos(todos, tab);  return (    <div className={theme}>      {/* ... so List's props will never be the same, and it will re-render every time */}      <List items={visibleTodos} />    </div>  );}

**In the above example, the `filterTodos` function always creates a _different_ array,** similar to how the `{}` object literal always creates a new object. Normally, this wouldn’t be a problem, but it means that `List` props will never be the same, and your [`memo`](/reference/react/memo)
 optimization won’t work. This is where `useMemo` comes in handy:

    export default function TodoList({ todos, tab, theme }) {  // Tell React to cache your calculation between re-renders...  const visibleTodos = useMemo(    () => filterTodos(todos, tab),    [todos, tab] // ...so as long as these dependencies don't change...  );  return (    <div className={theme}>      {/* ...List will receive the same props and can skip re-rendering */}      <List items={visibleTodos} />    </div>  );}

**By wrapping the `visibleTodos` calculation in `useMemo`, you ensure that it has the _same_ value between the re-renders** (until dependencies change). You don’t _have to_ wrap a calculation in `useMemo` unless you do it for some specific reason. In this example, the reason is that you pass it to a component wrapped in [`memo`,](/reference/react/memo)
 and this lets it skip re-rendering. There are a few other reasons to add `useMemo` which are described further on this page.

##### Deep Dive

#### Memoizing individual JSX nodes[](#memoizing-individual-jsx-nodes "Link for Memoizing individual JSX nodes ")

Show Details

Instead of wrapping `List` in [`memo`](/reference/react/memo)
, you could wrap the `<List />` JSX node itself in `useMemo`:

    export default function TodoList({ todos, tab, theme }) {  const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);  const children = useMemo(() => <List items={visibleTodos} />, [visibleTodos]);  return (    <div className={theme}>      {children}    </div>  );}

The behavior would be the same. If the `visibleTodos` haven’t changed, `List` won’t be re-rendered.

A JSX node like `<List items={visibleTodos} />` is an object like `{ type: List, props: { items: visibleTodos } }`. Creating this object is very cheap, but React doesn’t know whether its contents is the same as last time or not. This is why by default, React will re-render the `List` component.

However, if React sees the same exact JSX as during the previous render, it won’t try to re-render your component. This is because JSX nodes are [immutable.](https://en.wikipedia.org/wiki/Immutable_object)
 A JSX node object could not have changed over time, so React knows it’s safe to skip a re-render. However, for this to work, the node has to _actually be the same object_, not merely look the same in code. This is what `useMemo` does in this example.

Manually wrapping JSX nodes into `useMemo` is not convenient. For example, you can’t do this conditionally. This is usually why you would wrap components with [`memo`](/reference/react/memo)
 instead of wrapping JSX nodes.

#### The difference between skipping re-renders and always re-rendering[](#examples-rerendering "Link for The difference between skipping re-renders and always re-rendering")

1. Skipping re-rendering with `useMemo` and `memo` 2. Always re-rendering a component

#### 

Example 1 of 2:

Skipping re-rendering with `useMemo` and `memo`[](#skipping-re-rendering-with-usememo-and-memo "Link for this heading")

In this example, the `List` component is **artificially slowed down** so that you can see what happens when a React component you’re rendering is genuinely slow. Try switching the tabs and toggling the theme.

Switching the tabs feels slow because it forces the slowed down `List` to re-render. That’s expected because the `tab` has changed, and so you need to reflect the user’s new choice on the screen.

Next, try toggling the theme. **Thanks to `useMemo` together with [`memo`](/reference/react/memo)
, it’s fast despite the artificial slowdown!** The `List` skipped re-rendering because the `visibleTodos` array has not changed since the last render. The `visibleTodos` array has not changed because both `todos` and `tab` (which you pass as dependencies to `useMemo`) haven’t changed since the last render.

App.jsTodoList.jsList.jsutils.js

TodoList.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useMemo } from 'react';
import List from './List.js';
import { filterTodos } from './utils.js'

export default function TodoList({ todos, theme, tab }) {
  const visibleTodos = useMemo(
    () \=> filterTodos(todos, tab),
    \[todos, tab\]
  );
  return (
    <div className\={theme}\>
      <p\><b\>Note: <code\>List</code\> is artificially slowed down!</b\></p\>
      <List items\={visibleTodos} />
    </div\>
  );
}

Show more

Next Example

* * *

### Preventing an Effect from firing too often[](#preventing-an-effect-from-firing-too-often "Link for Preventing an Effect from firing too often ")

Sometimes, you might want to use a value inside an [Effect:](/learn/synchronizing-with-effects)

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  const options = {    serverUrl: 'https://localhost:1234',    roomId: roomId  }  useEffect(() => {    const connection = createConnection(options);    connection.connect();    // ...

This creates a problem. [Every reactive value must be declared as a dependency of your Effect.](/learn/lifecycle-of-reactive-effects#react-verifies-that-you-specified-every-reactive-value-as-a-dependency)
 However, if you declare `options` as a dependency, it will cause your Effect to constantly reconnect to the chat room:

      useEffect(() => {    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [options]); // 🔴 Problem: This dependency changes on every render  // ...

To solve this, you can wrap the object you need to call from an Effect in `useMemo`:

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  const options = useMemo(() => {    return {      serverUrl: 'https://localhost:1234',      roomId: roomId    };  }, [roomId]); // ✅ Only changes when roomId changes  useEffect(() => {    const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [options]); // ✅ Only changes when options changes  // ...

This ensures that the `options` object is the same between re-renders if `useMemo` returns the cached object.

However, since `useMemo` is performance optimization, not a semantic guarantee, React may throw away the cached value if [there is a specific reason to do that](#caveats)
. This will also cause the effect to re-fire, **so it’s even better to remove the need for a function dependency** by moving your object _inside_ the Effect:

    function ChatRoom({ roomId }) {  const [message, setMessage] = useState('');  useEffect(() => {    const options = { // ✅ No need for useMemo or object dependencies!      serverUrl: 'https://localhost:1234',      roomId: roomId    }        const connection = createConnection(options);    connection.connect();    return () => connection.disconnect();  }, [roomId]); // ✅ Only changes when roomId changes  // ...

Now your code is simpler and doesn’t need `useMemo`. [Learn more about removing Effect dependencies.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)

### Memoizing a dependency of another Hook[](#memoizing-a-dependency-of-another-hook "Link for Memoizing a dependency of another Hook ")

Suppose you have a calculation that depends on an object created directly in the component body:

    function Dropdown({ allItems, text }) {  const searchOptions = { matchMode: 'whole-word', text };  const visibleItems = useMemo(() => {    return searchItems(allItems, searchOptions);  }, [allItems, searchOptions]); // 🚩 Caution: Dependency on an object created in the component body  // ...

Depending on an object like this defeats the point of memoization. When a component re-renders, all of the code directly inside the component body runs again. **The lines of code creating the `searchOptions` object will also run on every re-render.** Since `searchOptions` is a dependency of your `useMemo` call, and it’s different every time, React knows the dependencies are different, and recalculate `searchItems` every time.

To fix this, you could memoize the `searchOptions` object _itself_ before passing it as a dependency:

    function Dropdown({ allItems, text }) {  const searchOptions = useMemo(() => {    return { matchMode: 'whole-word', text };  }, [text]); // ✅ Only changes when text changes  const visibleItems = useMemo(() => {    return searchItems(allItems, searchOptions);  }, [allItems, searchOptions]); // ✅ Only changes when allItems or searchOptions changes  // ...

In the example above, if the `text` did not change, the `searchOptions` object also won’t change. However, an even better fix is to move the `searchOptions` object declaration _inside_ of the `useMemo` calculation function:

    function Dropdown({ allItems, text }) {  const visibleItems = useMemo(() => {    const searchOptions = { matchMode: 'whole-word', text };    return searchItems(allItems, searchOptions);  }, [allItems, text]); // ✅ Only changes when allItems or text changes  // ...

Now your calculation depends on `text` directly (which is a string and can’t “accidentally” become different).

* * *

### Memoizing a function[](#memoizing-a-function "Link for Memoizing a function ")

Suppose the `Form` component is wrapped in [`memo`.](/reference/react/memo)
 You want to pass a function to it as a prop:

    export default function ProductPage({ productId, referrer }) {  function handleSubmit(orderDetails) {    post('/product/' + productId + '/buy', {      referrer,      orderDetails    });  }  return <Form onSubmit={handleSubmit} />;}

Just as `{}` creates a different object, function declarations like `function() {}` and expressions like `() => {}` produce a _different_ function on every re-render. By itself, creating a new function is not a problem. This is not something to avoid! However, if the `Form` component is memoized, presumably you want to skip re-rendering it when no props have changed. A prop that is _always_ different would defeat the point of memoization.

To memoize a function with `useMemo`, your calculation function would have to return another function:

    export default function Page({ productId, referrer }) {  const handleSubmit = useMemo(() => {    return (orderDetails) => {      post('/product/' + productId + '/buy', {        referrer,        orderDetails      });    };  }, [productId, referrer]);  return <Form onSubmit={handleSubmit} />;}

This looks clunky! **Memoizing functions is common enough that React has a built-in Hook specifically for that. Wrap your functions into [`useCallback`](/reference/react/useCallback)
 instead of `useMemo`** to avoid having to write an extra nested function:

    export default function Page({ productId, referrer }) {  const handleSubmit = useCallback((orderDetails) => {    post('/product/' + productId + '/buy', {      referrer,      orderDetails    });  }, [productId, referrer]);  return <Form onSubmit={handleSubmit} />;}

The two examples above are completely equivalent. The only benefit to `useCallback` is that it lets you avoid writing an extra nested function inside. It doesn’t do anything else. [Read more about `useCallback`.](/reference/react/useCallback)

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### My calculation runs twice on every re-render[](#my-calculation-runs-twice-on-every-re-render "Link for My calculation runs twice on every re-render ")

In [Strict Mode](/reference/react/StrictMode)
, React will call some of your functions twice instead of once:

    function TodoList({ todos, tab }) {  // This component function will run twice for every render.  const visibleTodos = useMemo(() => {    // This calculation will run twice if any of the dependencies change.    return filterTodos(todos, tab);  }, [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 and fix the mistake.

For example, this impure calculation function mutates an array you received as a prop:

      const visibleTodos = useMemo(() => {    // 🚩 Mistake: mutating a prop    todos.push({ id: 'last', text: 'Go for a walk!' });    const filtered = filterTodos(todos, tab);    return filtered;  }, [todos, tab]);

React calls your function twice, so you’d notice the todo is added twice. Your calculation shouldn’t change any existing objects, but it’s okay to change any _new_ objects you created during the calculation. For example, if the `filterTodos` function always returns a _different_ array, you can mutate _that_ array instead:

      const visibleTodos = useMemo(() => {    const filtered = filterTodos(todos, tab);    // ✅ Correct: mutating an object you created during the calculation    filtered.push({ id: 'last', text: 'Go for a walk!' });    return filtered;  }, [todos, tab]);

Read [keeping components pure](/learn/keeping-components-pure)
 to learn more about purity.

Also, check out the guides on [updating objects](/learn/updating-objects-in-state)
 and [updating arrays](/learn/updating-arrays-in-state)
 without mutation.

* * *

### My `useMemo` call is supposed to return an object, but returns undefined[](#my-usememo-call-is-supposed-to-return-an-object-but-returns-undefined "Link for this heading")

This code doesn’t work:

      // 🔴 You can't return an object from an arrow function with () => {  const searchOptions = useMemo(() => {    matchMode: 'whole-word',    text: text  }, [text]);

In JavaScript, `() => {` starts the arrow function body, so the `{` brace is not a part of your object. This is why it doesn’t return an object, and leads to mistakes. You could fix it by adding parentheses like `({` and `})`:

      // This works, but is easy for someone to break again  const searchOptions = useMemo(() => ({    matchMode: 'whole-word',    text: text  }), [text]);

However, this is still confusing and too easy for someone to break by removing the parentheses.

To avoid this mistake, write a `return` statement explicitly:

      // ✅ This works and is explicit  const searchOptions = useMemo(() => {    return {      matchMode: 'whole-word',      text: text    };  }, [text]);

* * *

### Every time my component renders, the calculation in `useMemo` re-runs[](#every-time-my-component-renders-the-calculation-in-usememo-re-runs "Link for this heading")

Make sure you’ve specified the dependency array as a second argument!

If you forget the dependency array, `useMemo` will re-run the calculation every time:

    function TodoList({ todos, tab }) {  // 🔴 Recalculates every time: no dependency array  const visibleTodos = useMemo(() => filterTodos(todos, tab));  // ...

This is the corrected version passing the dependency array as a second argument:

    function TodoList({ todos, tab }) {  // ✅ Does not recalculate unnecessarily  const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);  // ...

If this doesn’t help, then the problem is that at least one of your dependencies is different from the previous render. You can debug this problem by manually logging your dependencies to the console:

      const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);  console.log([todos, tab]);

You can then right-click on the arrays from different re-renders in the console and select “Store as a global variable” for both of them. Assuming the first one got saved as `temp1` and the second one got saved as `temp2`, you can then use the browser console to check whether each dependency in both arrays is the same:

    Object.is(temp1[0], temp2[0]); // Is the first dependency the same between the arrays?Object.is(temp1[1], temp2[1]); // Is the second dependency the same between the arrays?Object.is(temp1[2], temp2[2]); // ... and so on for every dependency ...

When you find which dependency breaks memoization, either find a way to remove it, or [memoize it as well.](#memoizing-a-dependency-of-another-hook)

* * *

### I need to call `useMemo` for each list item in a loop, but it’s not allowed[](#i-need-to-call-usememo-for-each-list-item-in-a-loop-but-its-not-allowed "Link for this heading")

Suppose the `Chart` component is wrapped in [`memo`](/reference/react/memo)
. You want to skip re-rendering every `Chart` in the list when the `ReportList` component re-renders. However, you can’t call `useMemo` in a loop:

    function ReportList({ items }) {  return (    <article>      {items.map(item => {        // 🔴 You can't call useMemo in a loop like this:        const data = useMemo(() => calculateReport(item), [item]);        return (          <figure key={item.id}>            <Chart data={data} />          </figure>        );      })}    </article>  );}

Instead, extract a component for each item and memoize data for individual items:

    function ReportList({ items }) {  return (    <article>      {items.map(item =>        <Report key={item.id} item={item} />      )}    </article>  );}function Report({ item }) {  // ✅ Call useMemo at the top level:  const data = useMemo(() => calculateReport(item), [item]);  return (    <figure>      <Chart data={data} />    </figure>  );}

Alternatively, you could remove `useMemo` and instead wrap `Report` itself in [`memo`.](/reference/react/memo)
 If the `item` prop does not change, `Report` will skip re-rendering, so `Chart` will skip re-rendering too:

    function ReportList({ items }) {  // ...}const Report = memo(function Report({ item }) {  const data = calculateReport(item);  return (    <figure>      <Chart data={data} />    </figure>  );});

[PrevioususeLayoutEffect](/reference/react/useLayoutEffect)
[NextuseOptimistic](/reference/react/useOptimistic)

* * *

---

# useRef – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useRef[](#undefined "Link for this heading")

=============================================

`useRef` is a React Hook that lets you reference a value that’s not needed for rendering.

    const ref = useRef(initialValue)

*   [Reference](#reference)
    *   [`useRef(initialValue)`](#useref)
        
*   [Usage](#usage)
    *   [Referencing a value with a ref](#referencing-a-value-with-a-ref)
        
    *   [Manipulating the DOM with a ref](#manipulating-the-dom-with-a-ref)
        
    *   [Avoiding recreating the ref contents](#avoiding-recreating-the-ref-contents)
        
*   [Troubleshooting](#troubleshooting)
    *   [I can’t get a ref to a custom component](#i-cant-get-a-ref-to-a-custom-component)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useRef(initialValue)`[](#useref "Link for this heading")

Call `useRef` at the top level of your component to declare a [ref.](/learn/referencing-values-with-refs)

    import { useRef } from 'react';function MyComponent() {  const intervalRef = useRef(0);  const inputRef = useRef(null);  // ...

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `initialValue`: The value you want the ref object’s `current` property to be initially. It can be a value of any type. This argument is ignored after the initial render.

#### Returns[](#returns "Link for Returns ")

`useRef` returns an object with a single property:

*   `current`: Initially, it’s set to the `initialValue` you have passed. You can later set it to something else. If you pass the ref object to React as a `ref` attribute to a JSX node, React will set its `current` property.

On the next renders, `useRef` will return the same object.

#### Caveats[](#caveats "Link for Caveats ")

*   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.](/reference/react/useState#my-initializer-or-updater-function-runs-twice)
     This is development-only behavior and does not affect production. Each ref object will be created twice, but one of the versions will be discarded. If your component function is pure (as it should be), this should not affect the behavior.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Referencing a value with a ref[](#referencing-a-value-with-a-ref "Link for 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)

    import { useRef } from 'react';function Stopwatch() {  const intervalRef = useRef(0);  // ...

`useRef` returns a ref object with a single `current` property initially set to the initial value you provided.

On the next renders, `useRef` will return the same object. You can change its `current` property to store information and read it later. This might remind you of [state](/reference/react/useState)
, but there is an important difference.

**Changing a ref does not trigger a re-render.** This means refs are perfect for storing information that doesn’t affect the visual output of your component. For example, if you need to store an [interval ID](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
 and retrieve it later, you can put it in a ref. To update the value inside the ref, you need to manually change its `current` property:

    function handleStartClick() {  const intervalId = setInterval(() => {    // ...  }, 1000);  intervalRef.current = intervalId;}

Later, you can read that interval ID from the ref so that you can call [clear that interval](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
:

    function handleStopClick() {  const intervalId = intervalRef.current;  clearInterval(intervalId);}

By using a ref, you ensure that:

*   You can **store information** between re-renders (unlike regular variables, which reset on every render).
*   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 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)

#### Examples of referencing a value with useRef[](#examples-value "Link for Examples of referencing a value with useRef")

1. Click counter 2. A stopwatch

#### 

Example 1 of 2:

Click counter[](#click-counter "Link for this heading")

This component uses a ref to keep track of how many times the button was clicked. Note that it’s okay to use a ref instead of state here because the click count is only read and written in an event handler.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef } from 'react';

export default function Counter() {
  let ref = useRef(0);

  function handleClick() {
    ref.current = ref.current + 1;
    alert('You clicked ' + ref.current + ' times!');
  }

  return (
    <button onClick\={handleClick}\>
      Click me!
    </button\>
  );
}

Show more

If you show `{ref.current}` in the JSX, the number won’t update on click. This is because setting `ref.current` does not trigger a re-render. Information that’s used for rendering should be state instead.

Next Example

### Pitfall

**Do not write _or read_ `ref.current` during rendering.**

React expects that the body of your component [behaves like a pure function](/learn/keeping-components-pure)
:

*   If the inputs ([props](/learn/passing-props-to-a-component)
    , [state](/learn/state-a-components-memory)
    , and [context](/learn/passing-data-deeply-with-context)
    ) are the same, it should return exactly the same JSX.
*   Calling it in a different order or with different arguments should not affect the results of other calls.

Reading or writing a ref **during rendering** breaks these expectations.

    function MyComponent() {  // ...  // 🚩 Don't write a ref during rendering  myRef.current = 123;  // ...  // 🚩 Don't read a ref during rendering  return <h1>{myOtherRef.current}</h1>;}

You can read or write refs **from event handlers or effects instead**.

    function MyComponent() {  // ...  useEffect(() => {    // ✅ You can read or write refs in effects    myRef.current = 123;  });  // ...  function handleClick() {    // ✅ You can read or write refs in event handlers    doSomething(myOtherRef.current);  }  // ...}

If you _have to_ read [or write](/reference/react/useState#storing-information-from-previous-renders)
 something during rendering, [use state](/reference/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)

* * *

### Manipulating the DOM with a ref[](#manipulating-the-dom-with-a-ref "Link for 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.

First, declare a ref object with an initial value of `null`:

    import { useRef } from 'react';function MyComponent() {  const inputRef = useRef(null);  // ...

Then pass your ref object as the `ref` attribute to the JSX of the DOM node you want to manipulate:

      // ...  return <input ref={inputRef} />;

After React creates the DOM node and puts it on the screen, React will set the `current` property of your ref object to that DOM node. Now you can access the `<input>`’s DOM node and call methods like [`focus()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)
:

      function handleClick() {    inputRef.current.focus();  }

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)

#### Examples of manipulating the DOM with useRef[](#examples-dom "Link for Examples of manipulating the DOM with useRef")

1. Focusing a text input 2. Scrolling an image into view 3. Playing and pausing a video 4. Exposing a ref to your own component

#### 

Example 1 of 4:

Focusing a text input[](#focusing-a-text-input "Link for this heading")

In this example, clicking the button will focus the input:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <\>
      <input ref\={inputRef} />
      <button onClick\={handleClick}\>
        Focus the input
      </button\>
    </\>
  );
}

Show more

Next Example

* * *

### Avoiding recreating the ref contents[](#avoiding-recreating-the-ref-contents "Link for Avoiding recreating the ref contents ")

React saves the initial ref value once and ignores it on the next renders.

    function Video() {  const playerRef = useRef(new VideoPlayer());  // ...

Although the result of `new VideoPlayer()` is only used for the initial render, you’re still calling this function on every render. This can be wasteful if it’s creating expensive objects.

To solve it, you may initialize the ref like this instead:

    function Video() {  const playerRef = useRef(null);  if (playerRef.current === null) {    playerRef.current = new VideoPlayer();  }  // ...

Normally, writing or reading `ref.current` during render is not allowed. However, it’s fine in this case because the result is always the same, and the condition only executes during initialization so it’s fully predictable.

##### Deep Dive

#### How to avoid null checks when initializing useRef later[](#how-to-avoid-null-checks-when-initializing-use-ref-later "Link for How to avoid null checks when initializing useRef later ")

Show Details

If you use a type checker and don’t want to always check for `null`, you can try a pattern like this instead:

    function Video() {  const playerRef = useRef(null);  function getPlayer() {    if (playerRef.current !== null) {      return playerRef.current;    }    const player = new VideoPlayer();    playerRef.current = player;    return player;  }  // ...

Here, the `playerRef` itself is nullable. However, you should be able to convince your type checker that there is no case in which `getPlayer()` returns `null`. Then use `getPlayer()` in your event handlers.

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### I can’t get a ref to a custom component[](#i-cant-get-a-ref-to-a-custom-component "Link for I can’t get a ref to a custom component ")

If you try to pass a `ref` to your own component like this:

    const inputRef = useRef(null);return <MyInput ref={inputRef} />;

You might get an error in the console:

Console

TypeError: Cannot read properties of null

By default, your own components don’t expose refs to the DOM nodes inside them.

To fix this, find the component that you want to get a ref to:

    export default function MyInput({ value, onChange }) {  return (    <input      value={value}      onChange={onChange}    />  );}

And then add `ref` to the list of props your component accepts and pass `ref` as a prop to the relevent child [built-in component](/reference/react-dom/components/common)
 like this:

    function MyInput({ value, onChange, ref }) {  return (    <input      value={value}      onChange={onChange}      ref={ref}    />  );};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)

[PrevioususeReducer](/reference/react/useReducer)
[NextuseState](/reference/react/useState)

* * *

---

# useState – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useState[](#undefined "Link for this heading")

===============================================

`useState` is a React Hook that lets you add a [state variable](/learn/state-a-components-memory)
 to your component.

    const [state, setState] = useState(initialState)

*   [Reference](#reference)
    *   [`useState(initialState)`](#usestate)
        
    *   [`set` functions, like `setSomething(nextState)`](#setstate)
        
*   [Usage](#usage)
    *   [Adding state to a component](#adding-state-to-a-component)
        
    *   [Updating state based on the previous state](#updating-state-based-on-the-previous-state)
        
    *   [Updating objects and arrays in state](#updating-objects-and-arrays-in-state)
        
    *   [Avoiding recreating the initial state](#avoiding-recreating-the-initial-state)
        
    *   [Resetting state with a key](#resetting-state-with-a-key)
        
    *   [Storing information from previous renders](#storing-information-from-previous-renders)
        
*   [Troubleshooting](#troubleshooting)
    *   [I’ve updated the state, but logging gives me the old value](#ive-updated-the-state-but-logging-gives-me-the-old-value)
        
    *   [I’ve updated the state, but the screen doesn’t update](#ive-updated-the-state-but-the-screen-doesnt-update)
        
    *   [I’m getting an error: “Too many re-renders”](#im-getting-an-error-too-many-re-renders)
        
    *   [My initializer or updater function runs twice](#my-initializer-or-updater-function-runs-twice)
        
    *   [I’m trying to set state to a function, but it gets called instead](#im-trying-to-set-state-to-a-function-but-it-gets-called-instead)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useState(initialState)`[](#usestate "Link for this heading")

Call `useState` at the top level of your component to declare a [state variable.](/learn/state-a-components-memory)

    import { useState } from 'react';function MyComponent() {  const [age, setAge] = useState(28);  const [name, setName] = useState('Taylor');  const [todos, setTodos] = useState(() => createTodos());  // ...

The convention is to name state variables like `[something, setSomething]` using [array destructuring.](https://javascript.info/destructuring-assignment)

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `initialState`: The value you want the state to be initially. It can be a value of any type, but there is a special behavior for functions. This argument is ignored after the initial render.
    *   If you pass a function as `initialState`, it will be treated as an _initializer function_. It should be pure, should take no arguments, and should return a value of any type. React will call your initializer function when initializing the component, and store its return value as the initial state. [See an example below.](#avoiding-recreating-the-initial-state)
        

#### Returns[](#returns "Link for Returns ")

`useState` returns an array with exactly two values:

1.  The current state. During the first render, it will match the `initialState` you have passed.
2.  The [`set` function](#setstate)
     that lets you update the state to a different value and trigger a re-render.

#### Caveats[](#caveats "Link for 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 behavior. The result from one of the calls will be ignored.

* * *

### `set` functions, like `setSomething(nextState)`[](#setstate "Link for this heading")

The `set` function returned by `useState` lets you update the state to a different value and trigger a re-render. You can pass the next state directly, or a function that calculates it from the previous state:

    const [name, setName] = useState('Edward');function handleClick() {  setName('Taylor');  setAge(a => a + 1);  // ...

#### Parameters[](#setstate-parameters "Link for Parameters ")

*   `nextState`: The value that you want the state to be. It can be a value of any type, but there is a special behavior for functions.
    *   If you pass a function as `nextState`, it will be treated as an _updater function_. It must be pure, should take the pending state as its only argument, and should return the next state. React will put your updater function in a queue and re-render your component. During the next render, React will calculate the next state by applying all of the queued updaters to the previous state. [See an example below.](#updating-state-based-on-the-previous-state)
        

#### Returns[](#setstate-returns "Link for Returns ")

`set` functions do not have a return value.

#### Caveats[](#setstate-caveats "Link for Caveats ")

*   The `set` function **only updates the state variable for the _next_ render**. If you read the state variable after calling the `set` function, [you will still get the old value](#ive-updated-the-state-but-logging-gives-me-the-old-value)
     that was on the screen before your call.
    
*   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`.](/reference/react-dom/flushSync)
    
*   The `set` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire. If the linter lets you omit a dependency without errors, it is safe to do. [Learn more about removing Effect dependencies.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
    
*   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 below.](#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 behavior. The result from one of the calls will be ignored.
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Adding state to a component[](#adding-state-to-a-component "Link for Adding state to a component ")

Call `useState` at the top level of your component to declare one or more [state variables.](/learn/state-a-components-memory)

    import { useState } from 'react';function MyComponent() {  const [age, setAge] = useState(42);  const [name, setName] = useState('Taylor');  // ...

The convention is to name state variables like `[something, setSomething]` using [array destructuring.](https://javascript.info/destructuring-assignment)

`useState` returns an array with exactly two items:

1.  The current state of this state variable, initially set to the initial state you provided.
2.  The `set` function that lets you change it to any other value in response to interaction.

To update what’s on the screen, call the `set` function with some next state:

    function handleClick() {  setName('Robin');}

React will store the next state, render your component again with the new values, and update the UI.

### Pitfall

Calling the `set` function [**does not** change the current state in the already executing code](#ive-updated-the-state-but-logging-gives-me-the-old-value)
:

    function handleClick() {  setName('Robin');  console.log(name); // Still "Taylor"!}

It only affects what `useState` will return starting from the _next_ render.

#### Basic useState examples[](#examples-basic "Link for Basic useState examples")

1. Counter (number) 2. Text field (string) 3. Checkbox (boolean) 4. Form (two variables)

#### 

Example 1 of 4:

Counter (number)[](#counter-number "Link for this heading")

In this example, the `count` state variable holds a number. Clicking the button increments it.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function Counter() {
  const \[count, setCount\] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <button onClick\={handleClick}\>
      You pressed me {count} times
    </button\>
  );
}

Next Example

* * *

### Updating state based on the previous state[](#updating-state-based-on-the-previous-state "Link for Updating state based on the previous state ")

Suppose the `age` is `42`. This handler calls `setAge(age + 1)` three times:

    function handleClick() {  setAge(age + 1); // setAge(42 + 1)  setAge(age + 1); // setAge(42 + 1)  setAge(age + 1); // setAge(42 + 1)}

However, after one click, `age` will only be `43` rather than `45`! This is because calling the `set` function [does not update](/learn/state-as-a-snapshot)
 the `age` state variable in the already running code. So each `setAge(age + 1)` call becomes `setAge(43)`.

To solve this problem, **you may pass an _updater function_** to `setAge` instead of the next state:

    function handleClick() {  setAge(a => a + 1); // setAge(42 => 43)  setAge(a => a + 1); // setAge(43 => 44)  setAge(a => a + 1); // setAge(44 => 45)}

Here, `a => a + 1` is your updater function. It takes the pending state and calculates the next state 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:

1.  `a => a + 1` will receive `42` as the pending state and return `43` as the next state.
2.  `a => a + 1` will receive `43` as the pending state and return `44` as the next state.
3.  `a => a + 1` will receive `44` as the pending state and return `45` as the next state.

There are no other queued updates, so React will store `45` as the current state in the end.

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)

##### Deep Dive

#### Is using an updater always preferred?[](#is-using-an-updater-always-preferred "Link for Is using an updater always preferred? ")

Show Details

You might hear a recommendation to always write code like `setAge(a => a + 1)` if the state you’re setting is calculated from the previous state. There is no harm in it, but it is also not always necessary.

In most cases, there is no difference between these two approaches. React always makes sure that for intentional user actions, like clicks, the `age` state variable would be updated before the next click. This means there is no risk of a click handler seeing a “stale” `age` at the beginning of the event handler.

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)

#### The difference between passing an updater and passing the next state directly[](#examples-updater "Link for The difference between passing an updater and passing the next state directly")

1. Passing the updater function 2. Passing the next state directly

#### 

Example 1 of 2:

Passing the updater function[](#passing-the-updater-function "Link for this heading")

This example passes the updater function, so the “+3” button works.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function Counter() {
  const \[age, setAge\] = useState(42);

  function increment() {
    setAge(a \=> a + 1);
  }

  return (
    <\>
      <h1\>Your age: {age}</h1\>
      <button onClick\={() \=> {
        increment();
        increment();
        increment();
      }}\>+3</button\>
      <button onClick\={() \=> {
        increment();
      }}\>+1</button\>
    </\>
  );
}

Show more

Next Example

* * *

### Updating objects and arrays in state[](#updating-objects-and-arrays-in-state "Link for Updating objects and arrays in state ")

You can put objects and arrays into state. In React, state is considered read-only, so **you should _replace_ it rather than _mutate_ your existing objects**. For example, if you have a `form` object in state, don’t mutate it:

    // 🚩 Don't mutate an object in state like this:form.firstName = 'Taylor';

Instead, replace the whole object by creating a new one:

    // ✅ Replace state with a new objectsetForm({  ...form,  firstName: 'Taylor'});

Read [updating objects in state](/learn/updating-objects-in-state)
 and [updating arrays in state](/learn/updating-arrays-in-state)
 to learn more.

#### Examples of objects and arrays in state[](#examples-objects "Link for Examples of objects and arrays in state")

1. Form (object) 2. Form (nested object) 3. List (array) 4. Writing concise update logic with Immer

#### 

Example 1 of 4:

Form (object)[](#form-object "Link for this heading")

In this example, the `form` state variable holds an object. Each input has a change handler that calls `setForm` with the next state of the entire form. The `{ ...form }` spread syntax ensures that the state object is replaced rather than mutated.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function Form() {
  const \[form, setForm\] = useState({
    firstName: 'Barbara',
    lastName: 'Hepworth',
    email: 'bhepworth@sculpture.com',
  });

  return (
    <\>
      <label\>
        First name:
        <input
          value\={form.firstName}
          onChange\={e \=> {
            setForm({
              ...form,
              firstName: e.target.value
            });
          }}
        />
      </label\>
      <label\>
        Last name:
        <input
          value\={form.lastName}
          onChange\={e \=> {
            setForm({
              ...form,
              lastName: e.target.value
            });
          }}
        />
      </label\>
      <label\>
        Email:
        <input
          value\={form.email}
          onChange\={e \=> {
            setForm({
              ...form,
              email: e.target.value
            });
          }}
        />
      </label\>
      <p\>
        {form.firstName}{' '}
        {form.lastName}{' '}
        ({form.email})
      </p\>
    </\>
  );
}

Show more

Next Example

* * *

### Avoiding recreating the initial state[](#avoiding-recreating-the-initial-state "Link for Avoiding recreating the initial state ")

React saves the initial state once and ignores it on the next renders.

    function TodoList() {  const [todos, setTodos] = useState(createInitialTodos());  // ...

Although the result of `createInitialTodos()` is only used for the initial render, you’re still calling this function on every render. This can be wasteful if it’s creating large arrays or performing expensive calculations.

To solve this, you may **pass it as an _initializer_ function** to `useState` instead:

    function TodoList() {  const [todos, setTodos] = useState(createInitialTodos);  // ...

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)

#### The difference between passing an initializer and passing the initial state directly[](#examples-initializer "Link for The difference between passing an initializer and passing the initial state directly")

1. Passing the initializer function 2. Passing the initial state directly

#### 

Example 1 of 2:

Passing the initializer function[](#passing-the-initializer-function "Link for this heading")

This example passes the initializer function, so the `createInitialTodos` function only runs during initialization. It does not run when component re-renders, such as when you type into the input.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

function createInitialTodos() {
  const initialTodos = \[\];
  for (let i = 0; i < 50; i++) {
    initialTodos.push({
      id: i,
      text: 'Item ' + (i + 1)
    });
  }
  return initialTodos;
}

export default function TodoList() {
  const \[todos, setTodos\] = useState(createInitialTodos);
  const \[text, setText\] = useState('');

  return (
    <\>
      <input
        value\={text}
        onChange\={e \=> setText(e.target.value)}
      />
      <button onClick\={() \=> {
        setText('');
        setTodos(\[{\
          id: todos.length,\
          text: text\
        }, ...todos\]);
      }}\>Add</button\>
      <ul\>
        {todos.map(item \=> (
          <li key\={item.id}\>
            {item.text}
          </li\>
        ))}
      </ul\>
    </\>
  );
}

Show more

Next Example

* * *

### Resetting state with a key[](#resetting-state-with-a-key "Link for Resetting state with a key ")

You’ll often 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.

Read [preserving and resetting state](/learn/preserving-and-resetting-state)
 to learn more.

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function App() {
  const \[version, setVersion\] = useState(0);

  function handleReset() {
    setVersion(version + 1);
  }

  return (
    <\>
      <button onClick\={handleReset}\>Reset</button\>
      <Form key\={version} />
    </\>
  );
}

function Form() {
  const \[name, setName\] = useState('Taylor');

  return (
    <\>
      <input
        value\={name}
        onChange\={e \=> setName(e.target.value)}
      />
      <p\>Hello, {name}.</p\>
    </\>
  );
}

Show more

* * *

### Storing information from previous renders[](#storing-information-from-previous-renders "Link for Storing information from previous renders ")

Usually, you will update state in event handlers. However, in rare cases you might want to adjust state in response to rendering — for example, you might want to change a state variable when a prop changes.

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](/reference/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.

In the rare case that none of these apply, there is a pattern you can use to update state based on the values that have been rendered so far, by calling a `set` function while your component is rendering.

Here’s an example. This `CountLabel` component displays the `count` prop passed to it:

    export default function CountLabel({ count }) {  return <h1>{count}</h1>}

Say you want to show whether the counter has _increased or decreased_ since the last change. The `count` prop doesn’t tell you this — you need to keep track of its previous value. Add the `prevCount` state variable to track it. Add another state variable called `trend` to hold whether the count has increased or decreased. Compare `prevCount` with `count`, and if they’re not equal, update both `prevCount` and `trend`. Now you can show both the current count prop and _how it has changed since the last render_.

App.jsCountLabel.js

CountLabel.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function CountLabel({ count }) {
  const \[prevCount, setPrevCount\] = useState(count);
  const \[trend, setTrend\] = useState(null);
  if (prevCount !== count) {
    setPrevCount(count);
    setTrend(count > prevCount ? 'increasing' : 'decreasing');
  }
  return (
    <\>
      <h1\>{count}</h1\>
      {trend && <p\>The count is {trend}</p\>}
    </\>
  );
}

Show more

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 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). If your condition is below all the Hook calls, you may add an early `return;` to restart rendering earlier.

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### I’ve updated the state, but logging gives me the old value[](#ive-updated-the-state-but-logging-gives-me-the-old-value "Link for I’ve updated the state, but logging gives me the old value ")

Calling the `set` function **does not change state in the running code**:

    function handleClick() {  console.log(count);  // 0  setCount(count + 1); // Request a re-render with 1  console.log(count);  // Still 0!  setTimeout(() => {    console.log(count); // Also 0!  }, 5000);}

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:

    const nextCount = count + 1;setCount(nextCount);console.log(count);     // 0console.log(nextCount); // 1

* * *

### I’ve updated the state, but the screen doesn’t update[](#ive-updated-the-state-but-the-screen-doesnt-update "Link for I’ve updated the state, but the screen doesn’t update ")

React will **ignore your update if the next state is equal to the previous state,** as determined by an [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
 comparison. This usually happens when you change an object or an array in state directly:

    obj.x = 10;  // 🚩 Wrong: mutating existing objectsetObj(obj); // 🚩 Doesn't do anything

You mutated an existing `obj` object and passed it back to `setObj`, so React ignored the update. To fix this, you need to ensure that you’re always [_replacing_ objects and arrays in state instead of _mutating_ them](#updating-objects-and-arrays-in-state)
:

    // ✅ Correct: creating a new objectsetObj({  ...obj,  x: 10});

* * *

### I’m getting an error: “Too many re-renders”[](#im-getting-an-error-too-many-re-renders "Link for I’m getting an error: “Too many re-renders” ")

You might get an error that says: `Too many re-renders. React limits the number of renders to prevent an infinite loop.` Typically, this means that you’re unconditionally setting state _during render_, so your component enters a loop: render, set state (which causes a render), render, set state (which causes a render), and so on. Very often, this is caused by a mistake in specifying an event handler:

    // 🚩 Wrong: calls the handler during renderreturn <button onClick={handleClick()}>Click me</button>// ✅ Correct: passes down the event handlerreturn <button onClick={handleClick}>Click me</button>// ✅ Correct: passes down an inline functionreturn <button onClick={(e) => handleClick(e)}>Click me</button>

If you can’t find the cause of this error, click on the arrow next to the error in the console and look through the JavaScript stack to find the specific `set` function call responsible for the error.

* * *

### My initializer or updater function runs twice[](#my-initializer-or-updater-function-runs-twice "Link for My initializer or updater function runs twice ")

In [Strict Mode](/reference/react/StrictMode)
, React will call some of your functions twice instead of once:

    function TodoList() {  // This component function will run twice for every render.  const [todos, setTodos] = useState(() => {    // This initializer function will run twice during initialization.    return createTodos();  });  function handleClick() {    setTodos(prevTodos => {      // This updater function will run twice for every click.      return [...prevTodos, createTodo()];    });  }  // ...

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.

For example, this impure updater function mutates an array in state:

    setTodos(prevTodos => {  // 🚩 Mistake: mutating state  prevTodos.push(createTodo());});

Because React calls your updater function twice, you’ll see the todo was added twice, so you’ll know that there is a mistake. In this example, you can fix the mistake by [replacing the array instead of mutating it](#updating-objects-and-arrays-in-state)
:

    setTodos(prevTodos => {  // ✅ Correct: replacing with new state  return [...prevTodos, createTodo()];});

Now that this updater function is pure, calling it an extra time doesn’t make a difference in behavior. This is why React calling it twice helps you find mistakes. **Only component, initializer, and updater functions need to be pure.** Event handlers don’t need to be pure, so React will never call your event handlers twice.

Read [keeping components pure](/learn/keeping-components-pure)
 to learn more.

* * *

### I’m trying to set state to a function, but it gets called instead[](#im-trying-to-set-state-to-a-function-but-it-gets-called-instead "Link for I’m trying to set state to a function, but it gets called instead ")

You can’t put a function into state like this:

    const [fn, setFn] = useState(someFunction);function handleClick() {  setFn(someOtherFunction);}

Because you’re passing a function, React assumes that `someFunction` is an [initializer function](#avoiding-recreating-the-initial-state)
, and that `someOtherFunction` is an [updater function](#updating-state-based-on-the-previous-state)
, so it tries to call them and store the result. To actually _store_ a function, you have to put `() =>` before them in both cases. Then React will store the functions you pass.

    const [fn, setFn] = useState(() => someFunction);function handleClick() {  setFn(() => someOtherFunction);}

[PrevioususeRef](/reference/react/useRef)
[NextuseSyncExternalStore](/reference/react/useSyncExternalStore)

* * *

---

# useSyncExternalStore – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useSyncExternalStore[](#undefined "Link for this heading")

===========================================================

`useSyncExternalStore` is a React Hook that lets you subscribe to an external store.

    const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)

*   [Reference](#reference)
    *   [`useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)`](#usesyncexternalstore)
        
*   [Usage](#usage)
    *   [Subscribing to an external store](#subscribing-to-an-external-store)
        
    *   [Subscribing to a browser API](#subscribing-to-a-browser-api)
        
    *   [Extracting the logic to a custom Hook](#extracting-the-logic-to-a-custom-hook)
        
    *   [Adding support for server rendering](#adding-support-for-server-rendering)
        
*   [Troubleshooting](#troubleshooting)
    *   [I’m getting an error: “The result of `getSnapshot` should be cached”](#im-getting-an-error-the-result-of-getsnapshot-should-be-cached)
        
    *   [My `subscribe` function gets called after every re-render](#my-subscribe-function-gets-called-after-every-re-render)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)`[](#usesyncexternalstore "Link for this heading")

Call `useSyncExternalStore` at the top level of your component to read a value from an external data store.

    import { useSyncExternalStore } from 'react';import { todosStore } from './todoStore.js';function TodosApp() {  const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);  // ...}

It returns the snapshot of the data in the store. You need to pass two functions as arguments:

1.  The `subscribe` function should subscribe to the store and return a function that unsubscribes.
2.  The `getSnapshot` function should read a snapshot of the data from the store.

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `subscribe`: A function that takes a single `callback` argument and subscribes it to the store. When the store changes, it should invoke the provided `callback`, which will cause React to re-call `getSnapshot` and (if needed) re-render the component. The `subscribe` function should return a function that cleans up the subscription.
    
*   `getSnapshot`: A function that returns a snapshot of the data in the store that’s needed by the component. While the store has not changed, repeated calls to `getSnapshot` must return the same value. If the store changes and the returned value is different (as compared by [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
    ), React re-renders the component.
    
*   **optional** `getServerSnapshot`: A function that returns the initial snapshot of the data in the store. It will be used only during server rendering and during hydration of server-rendered content on the client. The server snapshot must be the same between the client and the server, and is usually serialized and passed from the server to the client. If you omit this argument, rendering the component on the server will throw an error.
    

#### Returns[](#returns "Link for Returns ")

The current snapshot of the store which you can use in your rendering logic.

#### Caveats[](#caveats "Link for Caveats ")

*   The store snapshot returned by `getSnapshot` must be immutable. If the underlying store has mutable data, return a new immutable snapshot if the data has changed. Otherwise, return a cached last snapshot.
    
*   If a different `subscribe` function is passed during a re-render, React will re-subscribe to the store using the newly passed `subscribe` function. You can prevent this by declaring `subscribe` outside the component.
    
*   If the store is mutated during a [non-blocking Transition update](/reference/react/useTransition)
    , React will fall back to performing that update as blocking. Specifically, for every Transition update, React will call `getSnapshot` a second time just before applying changes to the DOM. If it returns a different value than when it was called originally, React will restart the update from scratch, this time applying it as a blocking update, to ensure that every component on screen is reflecting the same version of the store.
    
*   It’s not recommended to _suspend_ a render based on a store value returned by `useSyncExternalStore`. The reason is that mutations to the external store cannot be marked as [non-blocking Transition updates](/reference/react/useTransition)
    , so they will trigger the nearest [`Suspense` fallback](/reference/react/Suspense)
    , replacing already-rendered content on screen with a loading spinner, which typically makes a poor UX.
    
    For example, the following are discouraged:
    
        const LazyProductDetailPage = lazy(() => import('./ProductDetailPage.js'));function ShoppingApp() {  const selectedProductId = useSyncExternalStore(...);  // ❌ Calling `use` with a Promise dependent on `selectedProductId`  const data = use(fetchItem(selectedProductId))  // ❌ Conditionally rendering a lazy component based on `selectedProductId`  return selectedProductId != null ? <LazyProductDetailPage /> : <FeaturedProducts />;}
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Subscribing to an external store[](#subscribing-to-an-external-store "Link for Subscribing to an external store ")

Most of your React components will only read data from their [props,](/learn/passing-props-to-a-component)
 [state,](/reference/react/useState)
 and [context.](/reference/react/useContext)
 However, sometimes a component needs to read some data from some store outside of React that changes over time. This includes:

*   Third-party state management libraries that hold state outside of React.
*   Browser APIs that expose a mutable value and events to subscribe to its changes.

Call `useSyncExternalStore` at the top level of your component to read a value from an external data store.

    import { useSyncExternalStore } from 'react';import { todosStore } from './todoStore.js';function TodosApp() {  const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);  // ...}

It returns the snapshot of the data in the store. You need to pass two functions as arguments:

1.  The `subscribe` function should subscribe to the store and return a function that unsubscribes.
2.  The `getSnapshot` function should read a snapshot of the data from the store.

React will use these functions to keep your component subscribed to the store and re-render it on changes.

For example, in the sandbox below, `todosStore` is implemented as an external store that stores data outside of React. The `TodosApp` component connects to that external store with the `useSyncExternalStore` Hook.

App.jstodoStore.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useSyncExternalStore } from 'react';
import { todosStore } from './todoStore.js';

export default function TodosApp() {
  const todos = useSyncExternalStore(todosStore.subscribe, todosStore.getSnapshot);
  return (
    <\>
      <button onClick\={() \=> todosStore.addTodo()}\>Add todo</button\>
      <hr />
      <ul\>
        {todos.map(todo \=> (
          <li key\={todo.id}\>{todo.text}</li\>
        ))}
      </ul\>
    </\>
  );
}

Show more

### Note

When possible, we recommend using built-in React state with [`useState`](/reference/react/useState)
 and [`useReducer`](/reference/react/useReducer)
 instead. The `useSyncExternalStore` API is mostly useful if you need to integrate with existing non-React code.

* * *

### Subscribing to a browser API[](#subscribing-to-a-browser-api "Link for Subscribing to a browser API ")

Another reason to add `useSyncExternalStore` is when you want to subscribe to some value exposed by the browser that changes over time. For example, suppose that you want your component to display whether the network connection is active. The browser exposes this information via a property called [`navigator.onLine`.](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine)

This value can change without React’s knowledge, so you should read it with `useSyncExternalStore`.

    import { useSyncExternalStore } from 'react';function ChatIndicator() {  const isOnline = useSyncExternalStore(subscribe, getSnapshot);  // ...}

To implement the `getSnapshot` function, read the current value from the browser API:

    function getSnapshot() {  return navigator.onLine;}

Next, you need to implement the `subscribe` function. For example, when `navigator.onLine` changes, the browser fires the [`online`](https://developer.mozilla.org/en-US/docs/Web/API/Window/online_event)
 and [`offline`](https://developer.mozilla.org/en-US/docs/Web/API/Window/offline_event)
 events on the `window` object. You need to subscribe the `callback` argument to the corresponding events, and then return a function that cleans up the subscriptions:

    function subscribe(callback) {  window.addEventListener('online', callback);  window.addEventListener('offline', callback);  return () => {    window.removeEventListener('online', callback);    window.removeEventListener('offline', callback);  };}

Now React knows how to read the value from the external `navigator.onLine` API and how to subscribe to its changes. Disconnect your device from the network and notice that the component re-renders in response:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useSyncExternalStore } from 'react';

export default function ChatIndicator() {
  const isOnline = useSyncExternalStore(subscribe, getSnapshot);
  return <h1\>{isOnline ? '✅ Online' : '❌ Disconnected'}</h1\>;
}

function getSnapshot() {
  return navigator.onLine;
}

function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () \=> {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

Show more

* * *

### Extracting the logic to a custom Hook[](#extracting-the-logic-to-a-custom-hook "Link for Extracting the logic to a custom Hook ")

Usually you won’t write `useSyncExternalStore` directly in your components. Instead, you’ll typically call it from your own custom Hook. This lets you use the same external store from different components.

For example, this custom `useOnlineStatus` Hook tracks whether the network is online:

    import { useSyncExternalStore } from 'react';export function useOnlineStatus() {  const isOnline = useSyncExternalStore(subscribe, getSnapshot);  return isOnline;}function getSnapshot() {  // ...}function subscribe(callback) {  // ...}

Now different components can call `useOnlineStatus` without repeating the underlying implementation:

App.jsuseOnlineStatus.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useOnlineStatus } from './useOnlineStatus.js';

function StatusBar() {
  const isOnline = useOnlineStatus();
  return <h1\>{isOnline ? '✅ Online' : '❌ Disconnected'}</h1\>;
}

function SaveButton() {
  const isOnline = useOnlineStatus();

  function handleSaveClick() {
    console.log('✅ Progress saved');
  }

  return (
    <button disabled\={!isOnline} onClick\={handleSaveClick}\>
      {isOnline ? 'Save progress' : 'Reconnecting...'}
    </button\>
  );
}

export default function App() {
  return (
    <\>
      <SaveButton />
      <StatusBar />
    </\>
  );
}

Show more

* * *

### Adding support for server rendering[](#adding-support-for-server-rendering "Link for Adding support for server rendering ")

If your React app uses [server rendering,](/reference/react-dom/server)
 your React components will also run outside the browser environment to generate the initial HTML. This creates a few challenges when connecting to an external store:

*   If you’re connecting to a browser-only API, it won’t work because it does not exist on the server.
*   If you’re connecting to a third-party data store, you’ll need its data to match between the server and client.

To solve these issues, pass a `getServerSnapshot` function as the third argument to `useSyncExternalStore`:

    import { useSyncExternalStore } from 'react';export function useOnlineStatus() {  const isOnline = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);  return isOnline;}function getSnapshot() {  return navigator.onLine;}function getServerSnapshot() {  return true; // Always show "Online" for server-generated HTML}function subscribe(callback) {  // ...}

The `getServerSnapshot` function is similar to `getSnapshot`, but it runs only in two situations:

*   It runs on the server when generating the HTML.
*   It runs on the client during [hydration](/reference/react-dom/client/hydrateRoot)
    , i.e. when React takes the server HTML and makes it interactive.

This lets you provide the initial snapshot value which will be used before the app becomes interactive. If there is no meaningful initial value for the server rendering, omit this argument to [force rendering on the client.](/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content)

### Note

Make sure that `getServerSnapshot` returns the same exact data on the initial client render as it returned on the server. For example, if `getServerSnapshot` returned some prepopulated store content on the server, you need to transfer this content to the client. One way to do this is to emit a `<script>` tag during server rendering that sets a global like `window.MY_STORE_DATA`, and read from that global on the client in `getServerSnapshot`. Your external store should provide instructions on how to do that.

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### I’m getting an error: “The result of `getSnapshot` should be cached”[](#im-getting-an-error-the-result-of-getsnapshot-should-be-cached "Link for this heading")

This error means your `getSnapshot` function returns a new object every time it’s called, for example:

    function getSnapshot() {  // 🔴 Do not return always different objects from getSnapshot  return {    todos: myStore.todos  };}

React will re-render the component if `getSnapshot` return value is different from the last time. This is why, if you always return a different value, you will enter an infinite loop and get this error.

Your `getSnapshot` object should only return a different object if something has actually changed. If your store contains immutable data, you can return that data directly:

    function getSnapshot() {  // ✅ You can return immutable data  return myStore.todos;}

If your store data is mutable, your `getSnapshot` function should return an immutable snapshot of it. This means it _does_ need to create new objects, but it shouldn’t do this for every single call. Instead, it should store the last calculated snapshot, and return the same snapshot as the last time if the data in the store has not changed. How you determine whether mutable data has changed depends on your mutable store.

* * *

### My `subscribe` function gets called after every re-render[](#my-subscribe-function-gets-called-after-every-re-render "Link for this heading")

This `subscribe` function is defined _inside_ a component so it is different on every re-render:

    function ChatIndicator() {  // 🚩 Always a different function, so React will resubscribe on every re-render  function subscribe() {    // ...  }    const isOnline = useSyncExternalStore(subscribe, getSnapshot);  // ...}

React will resubscribe to your store if you pass a different `subscribe` function between re-renders. If this causes performance issues and you’d like to avoid resubscribing, move the `subscribe` function outside:

    // ✅ Always the same function, so React won't need to resubscribefunction subscribe() {  // ...}function ChatIndicator() {  const isOnline = useSyncExternalStore(subscribe, getSnapshot);  // ...}

Alternatively, wrap `subscribe` into [`useCallback`](/reference/react/useCallback)
 to only resubscribe when some argument changes:

    function ChatIndicator({ userId }) {  // ✅ Same function as long as userId doesn't change  const subscribe = useCallback(() => {    // ...  }, [userId]);    const isOnline = useSyncExternalStore(subscribe, getSnapshot);  // ...}

[PrevioususeState](/reference/react/useState)
[NextuseTransition](/reference/react/useTransition)

* * *

---

# Built-in React Components – React

[API Reference](/reference/react)

Built-in React Components[](#undefined "Link for this heading")

================================================================

React exposes a few built-in components that you can use in your JSX.

* * *

Built-in components[](#built-in-components "Link for Built-in components ")

----------------------------------------------------------------------------

*   [`<Fragment>`](/reference/react/Fragment)
    , alternatively written as `<>...</>`, lets you group multiple JSX nodes together.
*   [`<Profiler>`](/reference/react/Profiler)
     lets you measure rendering performance of a React tree programmatically.
*   [`<Suspense>`](/reference/react/Suspense)
     lets you display a fallback while the child components are loading.
*   [`<StrictMode>`](/reference/react/StrictMode)
     enables extra development-only checks that help you find bugs early.

* * *

Your own components[](#your-own-components "Link for Your own components ")

----------------------------------------------------------------------------

You can also [define your own components](/learn/your-first-component)
 as JavaScript functions.

[PrevioususeTransition](/reference/react/useTransition)
[Next<Fragment> (<>)](/reference/react/Fragment)

* * *

---

# useTransition – React

[API Reference](/reference/react)

[Hooks](/reference/react/hooks)

useTransition[](#undefined "Link for this heading")

====================================================

`useTransition` is a React Hook that lets you render a part of the UI in the background.

    const [isPending, startTransition] = useTransition()

*   [Reference](#reference)
    *   [`useTransition()`](#usetransition)
        
    *   [`startTransition(action)`](#starttransition)
        
*   [Usage](#usage)
    *   [Perform non-blocking updates with Actions](#perform-non-blocking-updates-with-actions)
        
    *   [Exposing `action` prop from components](#exposing-action-props-from-components)
        
    *   [Displaying a pending visual state](#displaying-a-pending-visual-state)
        
    *   [Preventing unwanted loading indicators](#preventing-unwanted-loading-indicators)
        
    *   [Building a Suspense-enabled router](#building-a-suspense-enabled-router)
        
    *   [Displaying an error to users with an error boundary](#displaying-an-error-to-users-with-error-boundary)
        
*   [Troubleshooting](#troubleshooting)
    *   [Updating an input in a Transition doesn’t work](#updating-an-input-in-a-transition-doesnt-work)
        
    *   [React doesn’t treat my state update as a Transition](#react-doesnt-treat-my-state-update-as-a-transition)
        
    *   [React doesn’t treat my state update after `await` as a Transition](#react-doesnt-treat-my-state-update-after-await-as-a-transition)
        
    *   [I want to call `useTransition` from outside a component](#i-want-to-call-usetransition-from-outside-a-component)
        
    *   [The function I pass to `startTransition` executes immediately](#the-function-i-pass-to-starttransition-executes-immediately)
        
    *   [My state updates in Transitions are out of order](#my-state-updates-in-transitions-are-out-of-order)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `useTransition()`[](#usetransition "Link for this heading")

Call `useTransition` at the top level of your component to mark some state updates as Transitions.

    import { useTransition } from 'react';function TabContainer() {  const [isPending, startTransition] = useTransition();  // ...}

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

`useTransition` does not take any parameters.

#### Returns[](#returns "Link for Returns ")

`useTransition` returns an array with exactly two items:

1.  The `isPending` flag that tells you whether there is a pending Transition.
2.  The [`startTransition` function](#starttransition)
     that lets you mark updates as a Transition.

* * *

### `startTransition(action)`[](#starttransition "Link for this heading")

The `startTransition` function returned by `useTransition` lets you mark an update as a Transition.

    function TabContainer() {  const [isPending, startTransition] = useTransition();  const [tab, setTab] = useState('about');  function selectTab(nextTab) {    startTransition(() => {      setTab(nextTab);    });  }  // ...}

### Note

#### Functions called in `startTransition` are called “Actions”.[](#functions-called-in-starttransition-are-called-actions "Link for this heading")

The function passed to `startTransition` is called an “Action”. By convention, any callback called inside `startTransition` (such as a callback prop) should be named `action` or include the “Action” suffix:

    function SubmitButton({ submitAction }) {  const [isPending, startTransition] = useTransition();  return (    <button      disabled={isPending}      onClick={() => {        startTransition(() => {          submitAction();        });      }}    >      Submit    </button>  );}

#### Parameters[](#starttransition-parameters "Link for Parameters ")

*   `action`: A function that updates some state by calling one or more [`set` functions](/reference/react/useState#setstate)
    . React calls `action` immediately with no parameters and marks all state updates scheduled synchronously during the `action` function call as Transitions. Any async calls that are awaited in the `action` will be included in the Transition, but currently require wrapping any `set` functions after the `await` in an additional `startTransition` (see [Troubleshooting](#react-doesnt-treat-my-state-update-after-await-as-a-transition)
    ). State updates marked as Transitions will be [non-blocking](#marking-a-state-update-as-a-non-blocking-transition)
     and [will not display unwanted loading indicators](#preventing-unwanted-loading-indicators)
    .

#### Returns[](#starttransition-returns "Link for Returns ")

`startTransition` does not return anything.

#### Caveats[](#starttransition-caveats "Link for Caveats ")

*   `useTransition` is a Hook, so it can only be called inside components or custom Hooks. If you need to start a Transition somewhere else (for example, from a data library), call the standalone [`startTransition`](/reference/react/startTransition)
     instead.
    
*   You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook value, try [`useDeferredValue`](/reference/react/useDeferredValue)
     instead.
    
*   The function you pass to `startTransition` is called immediately, marking all state updates that happen while it executes as Transitions. If you try to perform state updates in a `setTimeout`, for example, they won’t be marked as Transitions.
    
*   You must wrap any state updates after any async requests in another `startTransition` to mark them as Transitions. This is a known limitation that we will fix in the future (see [Troubleshooting](#react-doesnt-treat-my-state-update-after-await-as-a-transition)
    ).
    
*   The `startTransition` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire. If the linter lets you omit a dependency without errors, it is safe to do. [Learn more about removing Effect dependencies.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
    
*   A state update marked as a Transition will be interrupted by other state updates. For example, if you update a chart component inside a Transition, but then start typing into an input while the chart is in the middle of a re-render, React will restart the rendering work on the chart component after handling the input update.
    
*   Transition updates can’t be used to control text inputs.
    
*   If there are multiple ongoing Transitions, React currently batches them together. This is a limitation that may be removed in a future release.
    

Usage[](#usage "Link for Usage ")

----------------------------------

### Perform non-blocking updates with Actions[](#perform-non-blocking-updates-with-actions "Link for Perform non-blocking updates with Actions ")

Call `useTransition` at the top of your component to create Actions, and access the pending state:

    import {useState, useTransition} from 'react';function CheckoutForm() {  const [isPending, startTransition] = useTransition();  // ...}

`useTransition` returns an array with exactly two items:

1.  The `isPending` flag that tells you whether there is a pending Transition.
2.  The `startTransition` function that lets you create an Action.

To start a Transition, pass a function to `startTransition` like this:

    import {useState, useTransition} from 'react';import {updateQuantity} from './api';function CheckoutForm() {  const [isPending, startTransition] = useTransition();  const [quantity, setQuantity] = useState(1);  function onSubmit(newQuantity) {    startTransition(async function () {      const savedQuantity = await updateQuantity(newQuantity);      startTransition(() => {        setQuantity(savedQuantity);      });    });  }  // ...}

The function passed to `startTransition` is called the “Action”. You can update state and (optionally) perform side effects within an Action, and the work will be done in the background without blocking user interactions on the page. A Transition can include multiple Actions, and while a Transition is in progress, your UI stays responsive. For example, if the user clicks a tab but then changes their mind and clicks another tab, the second click will be immediately handled without waiting for the first update to finish.

To give the user feedback about in-progress Transitions, to `isPending` state switches to `true` at the first call to `startTransition`, and stays `true` until all Actions complete and the final state is shown to the user. Transitions ensure side effects in Actions to complete in order to [prevent unwanted loading indicators](#preventing-unwanted-loading-indicators)
, and you can provide immediate feedback while the Transition is in progress with `useOptimistic`.

#### The difference between Actions and regular event handling[](#examples "Link for The difference between Actions and regular event handling")

1. Updating the quantity in an Action 2. Updating the quantity without an Action

#### 

Example 1 of 2:

Updating the quantity in an Action[](#updating-the-quantity-in-an-action "Link for this heading")

In this example, the `updateQuantity` function simulates a request to the server to update the item’s quantity in the cart. This function is _artificially slowed down_ so that it takes at least a second to complete the request.

Update the quantity multiple times quickly. Notice that the pending “Total” state is shown while any requests are in progress, and the “Total” updates only after the final request is complete. Because the update is in an Action, the “quantity” can continue to be updated while the request is in progress.

App.jsItem.jsTotal.jsapi.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useTransition } from "react";
import { updateQuantity } from "./api";
import Item from "./Item";
import Total from "./Total";

export default function App({}) {
  const \[quantity, setQuantity\] = useState(1);
  const \[isPending, startTransition\] = useTransition();

  const updateQuantityAction = async newQuantity \=> {
    // To access the pending state of a transition,
    // call startTransition again.
    startTransition(async () \=> {
      const savedQuantity = await updateQuantity(newQuantity);
      startTransition(() \=> {
        setQuantity(savedQuantity);
      });
    });
  };

  return (
    <div\>
      <h1\>Checkout</h1\>
      <Item action\={updateQuantityAction}/>
      <hr />
      <Total quantity\={quantity} isPending\={isPending} />
    </div\>
  );
}

Show more

This is a basic example to demonstrate how Actions work, but this example does not handle requests completing out of order. When updating the quantity multiple times, it’s possible for the previous requests to finish after later requests causing the quantity to update out of order. This is a known limitation that we will fix in the future (see [Troubleshooting](#my-state-updates-in-transitions-are-out-of-order)
 below).

For common use cases, React provides built-in abstractions such as:

*   [`useActionState`](/reference/react/useActionState)
    
*   [`<form>` actions](/reference/react-dom/components/form)
    
*   [Server Functions](/reference/rsc/server-functions)
    

These solutions handle request ordering for you. When using Transitions to build your own custom hooks or libraries that manage async state transitions, you have greater control over the request ordering, but you must handle it yourself.

Next Example

* * *

### Exposing `action` prop from components[](#exposing-action-props-from-components "Link for this heading")

You can expose an `action` prop from a component to allow a parent to call an Action.

For example, this `TabButton` component wraps its `onClick` logic in an `action` prop:

    export default function TabButton({ action, children, isActive }) {  const [isPending, startTransition] = useTransition();  if (isActive) {    return <b>{children}</b>  }  return (    <button onClick={() => {      startTransition(() => {        action();      });    }}>      {children}    </button>  );}

Because the parent component updates its state inside the `action`, that state update gets marked as a Transition. This means you can click on “Posts” and then immediately click “Contact” and it does not block user interactions:

App.jsTabButton.jsAboutTab.jsPostsTab.jsContactTab.js

TabButton.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useTransition } from 'react';

export default function TabButton({ action, children, isActive }) {
  const \[isPending, startTransition\] = useTransition();
  if (isActive) {
    return <b\>{children}</b\>
  }
  return (
    <button onClick\={() \=> {
      startTransition(() \=> {
        action();
      });
    }}\>
      {children}
    </button\>
  );
}

Show more

* * *

### Displaying a pending visual state[](#displaying-a-pending-visual-state "Link for Displaying a pending visual state ")

You can use the `isPending` boolean value returned by `useTransition` to indicate to the user that a Transition is in progress. For example, the tab button can have a special “pending” visual state:

    function TabButton({ action, children, isActive }) {  const [isPending, startTransition] = useTransition();  // ...  if (isPending) {    return <b className="pending">{children}</b>;  }  // ...

Notice how clicking “Posts” now feels more responsive because the tab button itself updates right away:

App.jsTabButton.jsAboutTab.jsPostsTab.jsContactTab.js

TabButton.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useTransition } from 'react';

export default function TabButton({ action, children, isActive }) {
  const \[isPending, startTransition\] = useTransition();
  if (isActive) {
    return <b\>{children}</b\>
  }
  if (isPending) {
    return <b className\="pending"\>{children}</b\>;
  }
  return (
    <button onClick\={() \=> {
      startTransition(() \=> {
        action();
      });
    }}\>
      {children}
    </button\>
  );
}

Show more

* * *

### Preventing unwanted loading indicators[](#preventing-unwanted-loading-indicators "Link for Preventing unwanted loading indicators ")

In this example, the `PostsTab` component fetches some data using [use](/reference/react/use)
. When you click the “Posts” tab, the `PostsTab` component _suspends_, causing the closest loading fallback to appear:

App.jsTabButton.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Suspense, useState } from 'react';
import TabButton from './TabButton.js';
import AboutTab from './AboutTab.js';
import PostsTab from './PostsTab.js';
import ContactTab from './ContactTab.js';

export default function TabContainer() {
  const \[tab, setTab\] = useState('about');
  return (
    <Suspense fallback\={<h1\>🌀 Loading...</h1\>}\>
      <TabButton
        isActive\={tab === 'about'}
        action\={() \=> setTab('about')}
      \>
        About
      </TabButton\>
      <TabButton
        isActive\={tab === 'posts'}
        action\={() \=> setTab('posts')}
      \>
        Posts
      </TabButton\>
      <TabButton
        isActive\={tab === 'contact'}
        action\={() \=> setTab('contact')}
      \>
        Contact
      </TabButton\>
      <hr />
      {tab === 'about' && <AboutTab />}
      {tab === 'posts' && <PostsTab />}
      {tab === 'contact' && <ContactTab />}
    </Suspense\>
  );
}

Show more

Hiding the entire tab container to show a loading indicator leads to a jarring user experience. If you add `useTransition` to `TabButton`, you can instead display the pending state in the tab button instead.

Notice that clicking “Posts” no longer replaces the entire tab container with a spinner:

App.jsTabButton.js

TabButton.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useTransition } from 'react';

export default function TabButton({ action, children, isActive }) {
  const \[isPending, startTransition\] = useTransition();
  if (isActive) {
    return <b\>{children}</b\>
  }
  if (isPending) {
    return <b className\="pending"\>{children}</b\>;
  }
  return (
    <button onClick\={() \=> {
      startTransition(() \=> {
        action();
      });
    }}\>
      {children}
    </button\>
  );
}

Show more

[Read more about using Transitions with Suspense.](/reference/react/Suspense#preventing-already-revealed-content-from-hiding)

### Note

Transitions only “wait” long enough to avoid hiding _already revealed_ content (like the tab container). If the Posts tab had a [nested `<Suspense>` boundary,](/reference/react/Suspense#revealing-nested-content-as-it-loads)
 the Transition would not “wait” for it.

* * *

### Building a Suspense-enabled router[](#building-a-suspense-enabled-router "Link for Building a Suspense-enabled router ")

If you’re building a React framework or a router, we recommend marking page navigations as Transitions.

    function Router() {  const [page, setPage] = useState('/');  const [isPending, startTransition] = useTransition();  function navigate(url) {    startTransition(() => {      setPage(url);    });  }  // ...

This is recommended for three reasons:

*   [Transitions are interruptible,](#marking-a-state-update-as-a-non-blocking-transition)
     which lets the user click away without waiting for the re-render to complete.
*   [Transitions prevent unwanted loading indicators,](#preventing-unwanted-loading-indicators)
     which lets the user avoid jarring jumps on navigation.
*   [Transitions wait for all pending actions](#perform-non-blocking-updates-with-actions)
     which lets the user wait for side effects to complete before the new page is shown.

Here is a simplified router example using Transitions for navigations.

App.jsLayout.jsIndexPage.jsArtistPage.jsAlbums.jsBiography.jsPanel.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Suspense, useState, useTransition } from 'react';
import IndexPage from './IndexPage.js';
import ArtistPage from './ArtistPage.js';
import Layout from './Layout.js';

export default function App() {
  return (
    <Suspense fallback\={<BigSpinner />}\>
      <Router />
    </Suspense\>
  );
}

function Router() {
  const \[page, setPage\] = useState('/');
  const \[isPending, startTransition\] = useTransition();

  function navigate(url) {
    startTransition(() \=> {
      setPage(url);
    });
  }

  let content;
  if (page === '/') {
    content = (
      <IndexPage navigate\={navigate} />
    );
  } else if (page === '/the-beatles') {
    content = (
      <ArtistPage
        artist\={{
          id: 'the-beatles',
          name: 'The Beatles',
        }}
      />
    );
  }
  return (
    <Layout isPending\={isPending}\>
      {content}
    </Layout\>
  );
}

function BigSpinner() {
  return <h2\>🌀 Loading...</h2\>;
}

Show more

### Note

[Suspense-enabled](/reference/react/Suspense)
 routers are expected to wrap the navigation updates into Transitions by default.

* * *

### Displaying an error to users with an error boundary[](#displaying-an-error-to-users-with-error-boundary "Link for Displaying an error to users with an error boundary ")

If a function passed to `startTransition` throws an error, you can display an error to your user with an [error boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
. To use an error boundary, wrap the component where you are calling the `useTransition` in an error boundary. Once the function passed to `startTransition` errors, the fallback for the error boundary will be displayed.

AddCommentContainer.js

AddCommentContainer.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useTransition } from "react";
import { ErrorBoundary } from "react-error-boundary";

export function AddCommentContainer() {
  return (
    <ErrorBoundary fallback\={<p\>⚠️Something went wrong</p\>}\>
      <AddCommentButton />
    </ErrorBoundary\>
  );
}

function addComment(comment) {
  // For demonstration purposes to show Error Boundary
  if (comment == null) {
    throw new Error("Example Error: An error thrown to trigger error boundary");
  }
}

function AddCommentButton() {
  const \[pending, startTransition\] = useTransition();

  return (
    <button
      disabled\={pending}
      onClick\={() \=> {
        startTransition(() \=> {
          // Intentionally not passing a comment
          // so error gets thrown
          addComment();
        });
      }}
    \>
      Add comment
    </button\>
  );
}

Show more

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### Updating an input in a Transition doesn’t work[](#updating-an-input-in-a-transition-doesnt-work "Link for Updating an input in a Transition doesn’t work ")

You can’t use a Transition for a state variable that controls an input:

    const [text, setText] = useState('');// ...function handleChange(e) {  // ❌ Can't use Transitions for controlled input state  startTransition(() => {    setText(e.target.value);  });}// ...return <input value={text} onChange={handleChange} />;

This is because Transitions are non-blocking, but updating an input in response to the change event should happen synchronously. If you want to run a Transition in response to typing, you have two options:

1.  You can declare two separate state variables: one for the input state (which always updates synchronously), and one that you will update in a Transition. This lets you control the input using the synchronous state, and pass the Transition state variable (which will “lag behind” the input) to the rest of your rendering logic.
2.  Alternatively, you can have one state variable, and add [`useDeferredValue`](/reference/react/useDeferredValue)
     which will “lag behind” the real value. It will trigger non-blocking re-renders to “catch up” with the new value automatically.

* * *

### React doesn’t treat my state update as a Transition[](#react-doesnt-treat-my-state-update-as-a-transition "Link for React doesn’t treat my state update as a Transition ")

When you wrap a state update in a Transition, make sure that it happens _during_ the `startTransition` call:

    startTransition(() => {  // ✅ Setting state *during* startTransition call  setPage('/about');});

The function you pass to `startTransition` must be synchronous. You can’t mark an update as a Transition like this:

    startTransition(() => {  // ❌ Setting state *after* startTransition call  setTimeout(() => {    setPage('/about');  }, 1000);});

Instead, you could do this:

    setTimeout(() => {  startTransition(() => {    // ✅ Setting state *during* startTransition call    setPage('/about');  });}, 1000);

* * *

### React doesn’t treat my state update after `await` as a Transition[](#react-doesnt-treat-my-state-update-after-await-as-a-transition "Link for this heading")

When you use `await` inside a `startTransition` function, the state updates that happen after the `await` are not marked as Transitions. You must wrap state updates after each `await` in a `startTransition` call:

    startTransition(async () => {  await someAsyncFunction();  // ❌ Not using startTransition after await  setPage('/about');});

However, this works instead:

    startTransition(async () => {  await someAsyncFunction();  // ✅ Using startTransition *after* await  startTransition(() => {    setPage('/about');  });});

This is a JavaScript limitation due to React losing the scope of the async context. In the future, when [AsyncContext](https://github.com/tc39/proposal-async-context)
 is available, this limitation will be removed.

* * *

### I want to call `useTransition` from outside a component[](#i-want-to-call-usetransition-from-outside-a-component "Link for this heading")

You can’t call `useTransition` outside a component because it’s a Hook. In this case, use the standalone [`startTransition`](/reference/react/startTransition)
 method instead. It works the same way, but it doesn’t provide the `isPending` indicator.

* * *

### The function I pass to `startTransition` executes immediately[](#the-function-i-pass-to-starttransition-executes-immediately "Link for this heading")

If you run this code, it will print 1, 2, 3:

    console.log(1);startTransition(() => {  console.log(2);  setPage('/about');});console.log(3);

**It is expected to print 1, 2, 3.** The function you pass to `startTransition` does not get delayed. Unlike with the browser `setTimeout`, it does not run the callback later. React executes your function immediately, but any state updates scheduled _while it is running_ are marked as Transitions. You can imagine that it works like this:

    // A simplified version of how React workslet isInsideTransition = false;function startTransition(scope) {  isInsideTransition = true;  scope();  isInsideTransition = false;}function setState() {  if (isInsideTransition) {    // ... schedule a Transition state update ...  } else {    // ... schedule an urgent state update ...  }}

### My state updates in Transitions are out of order[](#my-state-updates-in-transitions-are-out-of-order "Link for My state updates in Transitions are out of order ")

If you `await` inside `startTransition`, you might see the updates happen out of order.

In this example, the `updateQuantity` function simulates a request to the server to update the item’s quantity in the cart. This function _artificially returns the every other request after the previous_ to simulate race conditions for network requests.

Try updating the quantity once, then update it quickly multiple times. You might see the incorrect total:

App.jsItem.jsTotal.jsapi.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, useTransition } from "react";
import { updateQuantity } from "./api";
import Item from "./Item";
import Total from "./Total";

export default function App({}) {
  const \[quantity, setQuantity\] = useState(1);
  const \[isPending, startTransition\] = useTransition();
  // Store the actual quantity in separate state to show the mismatch.
  const \[clientQuantity, setClientQuantity\] = useState(1);
  
  const updateQuantityAction = newQuantity \=> {
    setClientQuantity(newQuantity);

    // Access the pending state of the transition,
    // by wrapping in startTransition again.
    startTransition(async () \=> {
      const savedQuantity = await updateQuantity(newQuantity);
      startTransition(() \=> {
        setQuantity(savedQuantity);
      });
    });
  };

  return (
    <div\>
      <h1\>Checkout</h1\>
      <Item action\={updateQuantityAction}/>
      <hr />
      <Total clientQuantity\={clientQuantity} savedQuantity\={quantity} isPending\={isPending} />
    </div\>
  );
}

Show more

When clicking multiple times, it’s possible for previous requests to finish after later requests. When this happens, React currently has no way to know the intended order. This is because the updates are scheduled asynchronously, and React loses context of the order across the async boundary.

This is expected, because Actions within a Transition do not guarantee execution order. For common use cases, React provides higher-level abstractions like [`useActionState`](/reference/react/useActionState)
 and [`<form>` actions](/reference/react-dom/components/form)
 that handle ordering for you. For advanced use cases, you’ll need to implement your own queuing and abort logic to handle this.

[PrevioususeSyncExternalStore](/reference/react/useSyncExternalStore)
[NextComponents](/reference/react/components)

* * *

---

# <Fragment> (<>...</>) – React

[API Reference](/reference/react)

[Components](/reference/react/components)

<Fragment> (<>...</>)[](#undefined "Link for this heading")

============================================================

`<Fragment>`, often used via `<>...</>` syntax, lets you group elements without a wrapper node.

    <>  <OneChild />  <AnotherChild /></>

*   [Reference](#reference)
    *   [`<Fragment>`](#fragment)
        
*   [Usage](#usage)
    *   [Returning multiple elements](#returning-multiple-elements)
        
    *   [Assigning multiple elements to a variable](#assigning-multiple-elements-to-a-variable)
        
    *   [Grouping elements with text](#grouping-elements-with-text)
        
    *   [Rendering a list of Fragments](#rendering-a-list-of-fragments)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `<Fragment>`[](#fragment "Link for this heading")

Wrap elements in `<Fragment>` to group them together in situations where you need a single element. Grouping elements in `Fragment` has no effect on the resulting DOM; it is the same as if the elements were not grouped. The empty JSX tag `<></>` is shorthand for `<Fragment></Fragment>` in most cases.

#### Props[](#props "Link for Props ")

*   **optional** `key`: Fragments declared with the explicit `<Fragment>` syntax may have [keys.](/learn/rendering-lists#keeping-list-items-in-order-with-key)
    

#### Caveats[](#caveats "Link for Caveats ")

*   If you want to pass `key` to a Fragment, you can’t use the `<>...</>` syntax. You have to explicitly import `Fragment` from `'react'` and render `<Fragment key={yourKey}>...</Fragment>`.
    
*   React does not [reset state](/learn/preserving-and-resetting-state)
     when you go from rendering `<><Child /></>` to `[<Child />]` or back, or when you go from rendering `<><Child /></>` to `<Child />` and back. This only works a single level deep: for example, going from `<><><Child /></></>` to `<Child />` resets the state. See the precise semantics [here.](https://gist.github.com/clemmy/b3ef00f9507909429d8aa0d3ee4f986b)
    

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Returning multiple elements[](#returning-multiple-elements "Link for Returning multiple elements ")

Use `Fragment`, or the equivalent `<>...</>` syntax, to group multiple elements together. You can use it to put multiple elements in any place where a single element can go. For example, a component can only return one element, but by using a Fragment you can group multiple elements together and then return them as a group:

    function Post() {  return (    <>      <PostTitle />      <PostBody />    </>  );}

Fragments are useful because grouping elements with a Fragment has no effect on layout or styles, unlike if you wrapped the elements in another container like a DOM element. If you inspect this example with the browser tools, you’ll see that all `<h1>` and `<article>` DOM nodes appear as siblings without wrappers around them:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

export default function Blog() {
  return (
    <\>
      <Post title\="An update" body\="It's been a while since I posted..." />
      <Post title\="My new blog" body\="I am starting a new blog!" />
    </\>
  )
}

function Post({ title, body }) {
  return (
    <\>
      <PostTitle title\={title} />
      <PostBody body\={body} />
    </\>
  );
}

function PostTitle({ title }) {
  return <h1\>{title}</h1\>
}

function PostBody({ body }) {
  return (
    <article\>
      <p\>{body}</p\>
    </article\>
  );
}

Show more

##### Deep Dive

#### How to write a Fragment without the special syntax?[](#how-to-write-a-fragment-without-the-special-syntax "Link for How to write a Fragment without the special syntax? ")

Show Details

The example above is equivalent to importing `Fragment` from React:

    import { Fragment } from 'react';function Post() {  return (    <Fragment>      <PostTitle />      <PostBody />    </Fragment>  );}

Usually you won’t need this unless you need to [pass a `key` to your `Fragment`.](#rendering-a-list-of-fragments)

* * *

### Assigning multiple elements to a variable[](#assigning-multiple-elements-to-a-variable "Link for Assigning multiple elements to a variable ")

Like any other element, you can assign Fragment elements to variables, pass them as props, and so on:

    function CloseDialog() {  const buttons = (    <>      <OKButton />      <CancelButton />    </>  );  return (    <AlertDialog buttons={buttons}>      Are you sure you want to leave this page?    </AlertDialog>  );}

* * *

### Grouping elements with text[](#grouping-elements-with-text "Link for Grouping elements with text ")

You can use `Fragment` to group text together with components:

    function DateRangePicker({ start, end }) {  return (    <>      From      <DatePicker date={start} />      to      <DatePicker date={end} />    </>  );}

* * *

### Rendering a list of Fragments[](#rendering-a-list-of-fragments "Link for Rendering a list of Fragments ")

Here’s a situation where you need to write `Fragment` explicitly instead of using the `<></>` syntax. When you [render multiple elements in a loop](/learn/rendering-lists)
, you need to assign a `key` to each element. If the elements within the loop are Fragments, you need to use the normal JSX element syntax in order to provide the `key` attribute:

    function Blog() {  return posts.map(post =>    <Fragment key={post.id}>      <PostTitle title={post.title} />      <PostBody body={post.body} />    </Fragment>  );}

You can inspect the DOM to verify that there are no wrapper elements around the Fragment children:

App.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { Fragment } from 'react';

const posts = \[\
  { id: 1, title: 'An update', body: "It's been a while since I posted..." },\
  { id: 2, title: 'My new blog', body: 'I am starting a new blog!' }\
\];

export default function Blog() {
  return posts.map(post \=>
    <Fragment key\={post.id}\>
      <PostTitle title\={post.title} />
      <PostBody body\={post.body} />
    </Fragment\>
  );
}

function PostTitle({ title }) {
  return <h1\>{title}</h1\>
}

function PostBody({ body }) {
  return (
    <article\>
      <p\>{body}</p\>
    </article\>
  );
}

Show more

[PreviousComponents](/reference/react/components)
[Next<Profiler>](/reference/react/Profiler)

* * *

---

# <Profiler> – React

[API Reference](/reference/react)

[Components](/reference/react/components)

<Profiler>[](#undefined "Link for this heading")

=================================================

`<Profiler>` lets you measure rendering performance of a React tree programmatically.

    <Profiler id="App" onRender={onRender}>  <App /></Profiler>

*   [Reference](#reference)
    *   [`<Profiler>`](#profiler)
        
    *   [`onRender` callback](#onrender-callback)
        
*   [Usage](#usage)
    *   [Measuring rendering performance programmatically](#measuring-rendering-performance-programmatically)
        
    *   [Measuring different parts of the application](#measuring-different-parts-of-the-application)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `<Profiler>`[](#profiler "Link for this heading")

Wrap a component tree in a `<Profiler>` to measure its rendering performance.

    <Profiler id="App" onRender={onRender}>  <App /></Profiler>

#### Props[](#props "Link for Props ")

*   `id`: A string identifying the part of the UI you are measuring.
*   `onRender`: An [`onRender` callback](#onrender-callback)
     that React calls every time components within the profiled tree update. It receives information about what was rendered and how much time it took.

#### Caveats[](#caveats "Link for Caveats ")

*   Profiling adds some additional overhead, so **it is disabled in the production build by default.** To opt into production profiling, you need to enable a [special production build with profiling enabled.](https://fb.me/react-profiling)
    

* * *

### `onRender` callback[](#onrender-callback "Link for this heading")

React will call your `onRender` callback with information about what was rendered.

    function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime) {  // Aggregate or log render timings...}

#### Parameters[](#onrender-parameters "Link for Parameters ")

*   `id`: The string `id` prop of the `<Profiler>` tree that has just committed. This lets you identify which part of the tree was committed if you are using multiple profilers.
*   `phase`: `"mount"`, `"update"` or `"nested-update"`. This lets you know whether the tree has just been mounted for the first time or re-rendered due to a change in props, state, or Hooks.
*   `actualDuration`: The number of milliseconds spent rendering the `<Profiler>` and its descendants for the current update. This indicates how well the subtree makes use of memoization (e.g. [`memo`](/reference/react/memo)
     and [`useMemo`](/reference/react/useMemo)
    ). Ideally this value should decrease significantly after the initial mount as many of the descendants will only need to re-render if their specific props change.
*   `baseDuration`: The number of milliseconds estimating how much time it would take to re-render the entire `<Profiler>` subtree without any optimizations. It is calculated by summing up the most recent render durations of each component in the tree. This value estimates a worst-case cost of rendering (e.g. the initial mount or a tree with no memoization). Compare `actualDuration` against it to see if memoization is working.
*   `startTime`: A numeric timestamp for when React began rendering the current update.
*   `commitTime`: A numeric timestamp for when React committed the current update. This value is shared between all profilers in a commit, enabling them to be grouped if desirable.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Measuring rendering performance programmatically[](#measuring-rendering-performance-programmatically "Link for Measuring rendering performance programmatically ")

Wrap the `<Profiler>` component around a React tree to measure its rendering performance.

    <App>  <Profiler id="Sidebar" onRender={onRender}>    <Sidebar />  </Profiler>  <PageContent /></App>

It requires two props: an `id` (string) and an `onRender` callback (function) which React calls any time a component within the tree “commits” an update.

### Pitfall

Profiling adds some additional overhead, so **it is disabled in the production build by default.** To opt into production profiling, you need to enable a [special production build with profiling enabled.](https://fb.me/react-profiling)

### Note

`<Profiler>` lets you gather measurements programmatically. If you’re looking for an interactive profiler, try the Profiler tab in [React Developer Tools](/learn/react-developer-tools)
. It exposes similar functionality as a browser extension.

* * *

### Measuring different parts of the application[](#measuring-different-parts-of-the-application "Link for Measuring different parts of the application ")

You can use multiple `<Profiler>` components to measure different parts of your application:

    <App>  <Profiler id="Sidebar" onRender={onRender}>    <Sidebar />  </Profiler>  <Profiler id="Content" onRender={onRender}>    <Content />  </Profiler></App>

You can also nest `<Profiler>` components:

    <App>  <Profiler id="Sidebar" onRender={onRender}>    <Sidebar />  </Profiler>  <Profiler id="Content" onRender={onRender}>    <Content>      <Profiler id="Editor" onRender={onRender}>        <Editor />      </Profiler>      <Preview />    </Content>  </Profiler></App>

Although `<Profiler>` is a lightweight component, it should be used only when necessary. Each use adds some CPU and memory overhead to an application.

* * *

[Previous<Fragment> (<>)](/reference/react/Fragment)
[Next<StrictMode>](/reference/react/StrictMode)

* * *

---

# <StrictMode> – React

[API Reference](/reference/react)

[Components](/reference/react/components)

<StrictMode>[](#undefined "Link for this heading")

===================================================

`<StrictMode>` lets you find common bugs in your components early during development.

    <StrictMode>  <App /></StrictMode>

*   [Reference](#reference)
    *   [`<StrictMode>`](#strictmode)
        
*   [Usage](#usage)
    *   [Enabling Strict Mode for entire app](#enabling-strict-mode-for-entire-app)
        
    *   [Enabling Strict Mode for a part of the app](#enabling-strict-mode-for-a-part-of-the-app)
        
    *   [Fixing bugs found by double rendering in development](#fixing-bugs-found-by-double-rendering-in-development)
        
    *   [Fixing bugs found by re-running Effects in development](#fixing-bugs-found-by-re-running-effects-in-development)
        
    *   [Fixing bugs found by re-running ref callbacks in development](#fixing-bugs-found-by-re-running-ref-callbacks-in-development)
        
    *   [Fixing deprecation warnings enabled by Strict Mode](#fixing-deprecation-warnings-enabled-by-strict-mode)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `<StrictMode>`[](#strictmode "Link for this heading")

Use `StrictMode` to enable additional development behaviors and warnings for the component tree inside:

    import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';const root = createRoot(document.getElementById('root'));root.render(  <StrictMode>    <App />  </StrictMode>);

[See more examples below.](#usage)

Strict Mode enables the following development-only behaviors:

*   Your components will [re-render an extra time](#fixing-bugs-found-by-double-rendering-in-development)
     to find bugs caused by impure rendering.
*   Your components will [re-run Effects an extra time](#fixing-bugs-found-by-re-running-effects-in-development)
     to find bugs caused by missing Effect cleanup.
*   Your components will [re-run refs callbacks an extra time](#fixing-bugs-found-by-re-running-ref-callbacks-in-development)
     to find bugs caused by missing ref cleanup.
*   Your components will [be checked for usage of deprecated APIs.](#fixing-deprecation-warnings-enabled-by-strict-mode)
    

#### Props[](#props "Link for Props ")

`StrictMode` accepts no props.

#### Caveats[](#caveats "Link for Caveats ")

*   There is no way to opt out of Strict Mode inside a tree wrapped in `<StrictMode>`. This gives you confidence that all components inside `<StrictMode>` are checked. If two teams working on a product disagree whether they find the checks valuable, they need to either reach consensus or move `<StrictMode>` down in the tree.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Enabling Strict Mode for entire app[](#enabling-strict-mode-for-entire-app "Link for Enabling Strict Mode for entire app ")

Strict Mode enables extra development-only checks for the entire component tree inside the `<StrictMode>` component. These checks help you find common bugs in your components early in the development process.

To enable Strict Mode for your entire app, wrap your root component with `<StrictMode>` when you render it:

    import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';const root = createRoot(document.getElementById('root'));root.render(  <StrictMode>    <App />  </StrictMode>);

We recommend wrapping your entire app in Strict Mode, especially for newly created apps. If you use a framework that calls [`createRoot`](/reference/react-dom/client/createRoot)
 for you, check its documentation for how to enable Strict Mode.

Although the Strict Mode checks **only run in development,** they help you find bugs that already exist in your code but can be tricky to reliably reproduce in production. Strict Mode lets you fix bugs before your users report them.

### Note

Strict Mode enables the following checks in development:

*   Your components will [re-render an extra time](#fixing-bugs-found-by-double-rendering-in-development)
     to find bugs caused by impure rendering.
*   Your components will [re-run Effects an extra time](#fixing-bugs-found-by-re-running-effects-in-development)
     to find bugs caused by missing Effect cleanup.
*   Your components will [re-run ref callbacks an extra time](#fixing-bugs-found-by-re-running-ref-callbacks-in-development)
     to find bugs caused by missing ref cleanup.
*   Your components will [be checked for usage of deprecated APIs.](#fixing-deprecation-warnings-enabled-by-strict-mode)
    

**All of these checks are development-only and do not impact the production build.**

* * *

### Enabling Strict Mode for a part of the app[](#enabling-strict-mode-for-a-part-of-the-app "Link for Enabling Strict Mode for a part of the app ")

You can also enable Strict Mode for any part of your application:

    import { StrictMode } from 'react';function App() {  return (    <>      <Header />      <StrictMode>        <main>          <Sidebar />          <Content />        </main>      </StrictMode>      <Footer />    </>  );}

In this example, Strict Mode checks will not run against the `Header` and `Footer` components. However, they will run on `Sidebar` and `Content`, as well as all of the components inside them, no matter how deep.

### Note

When `StrictMode` is enabled for a part of the app, React will only enable behaviors that are possible in production. For example, if `<StrictMode>` is not enabled at the root of the app, it will not [re-run Effects an extra time](#fixing-bugs-found-by-re-running-effects-in-development)
 on initial mount, since this would cause child effects to double fire without the parent effects, which cannot happen in production.

* * *

### Fixing bugs found by double rendering in development[](#fixing-bugs-found-by-double-rendering-in-development "Link for Fixing bugs found by double rendering in development ")

[React assumes that every component you write is a pure function.](/learn/keeping-components-pure)
 This means that React components you write must always return the same JSX given the same inputs (props, state, and context).

Components breaking this rule behave unpredictably and cause bugs. To help you find accidentally impure code, Strict Mode calls some of your functions (only the ones that should be pure) **twice in development.** This includes:

*   Your component function body (only top-level logic, so this doesn’t include code inside event handlers)
*   Functions that you pass to [`useState`](/reference/react/useState)
    , [`set` functions](/reference/react/useState#setstate)
    , [`useMemo`](/reference/react/useMemo)
    , or [`useReducer`](/reference/react/useReducer)
    
*   Some class component methods like [`constructor`](/reference/react/Component#constructor)
    , [`render`](/reference/react/Component#render)
    , [`shouldComponentUpdate`](/reference/react/Component#shouldcomponentupdate)
     ([see the whole list](https://reactjs.org/docs/strict-mode.html#detecting-unexpected-side-effects)
    )

If a function is pure, running it twice does not change its behavior because a pure function produces the same result every time. However, if a function is impure (for example, it mutates the data it receives), running it twice tends to be noticeable (that’s what makes it impure!) This helps you spot and fix the bug early.

**Here is an example to illustrate how double rendering in Strict Mode helps you find bugs early.**

This `StoryTray` component takes an array of `stories` and adds one last “Create Story” item at the end:

index.jsApp.jsStoryTray.js

StoryTray.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

export default function StoryTray({ stories }) {
  const items = stories;
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul\>
      {items.map(story \=> (
        <li key\={story.id}\>
          {story.label}
        </li\>
      ))}
    </ul\>
  );
}

There is a mistake in the code above. However, it is easy to miss because the initial output appears correct.

This mistake will become more noticeable if the `StoryTray` component re-renders multiple times. For example, let’s make the `StoryTray` re-render with a different background color whenever you hover over it:

index.jsApp.jsStoryTray.js

StoryTray.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function StoryTray({ stories }) {
  const \[isHover, setIsHover\] = useState(false);
  const items = stories;
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul
      onPointerEnter\={() \=> setIsHover(true)}
      onPointerLeave\={() \=> setIsHover(false)}
      style\={{
        backgroundColor: isHover ? '#ddd' : '#fff'
      }}
    \>
      {items.map(story \=> (
        <li key\={story.id}\>
          {story.label}
        </li\>
      ))}
    </ul\>
  );
}

Show more

Notice how every time you hover over the `StoryTray` component, “Create Story” gets added to the list again. The intention of the code was to add it once at the end. But `StoryTray` directly modifies the `stories` array from the props. Every time `StoryTray` renders, it adds “Create Story” again at the end of the same array. In other words, `StoryTray` is not a pure function—running it multiple times produces different results.

To fix this problem, you can make a copy of the array, and modify that copy instead of the original one:

    export default function StoryTray({ stories }) {  const items = stories.slice(); // Clone the array  // ✅ Good: Pushing into a new array  items.push({ id: 'create', label: 'Create Story' });

This would [make the `StoryTray` function pure.](/learn/keeping-components-pure)
 Each time it is called, it would only modify a new copy of the array, and would not affect any external objects or variables. This solves the bug, but you had to make the component re-render more often before it became obvious that something is wrong with its behavior.

**In the original example, the bug wasn’t obvious. Now let’s wrap the original (buggy) code in `<StrictMode>`:**

index.jsApp.jsStoryTray.js

StoryTray.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

export default function StoryTray({ stories }) {
  const items = stories;
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul\>
      {items.map(story \=> (
        <li key\={story.id}\>
          {story.label}
        </li\>
      ))}
    </ul\>
  );
}

**Strict Mode _always_ calls your rendering function twice, so you can see the mistake right away** (“Create Story” appears twice). This lets you notice such mistakes early in the process. When you fix your component to render in Strict Mode, you _also_ fix many possible future production bugs like the hover functionality from before:

index.jsApp.jsStoryTray.js

StoryTray.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState } from 'react';

export default function StoryTray({ stories }) {
  const \[isHover, setIsHover\] = useState(false);
  const items = stories.slice(); // Clone the array
  items.push({ id: 'create', label: 'Create Story' });
  return (
    <ul
      onPointerEnter\={() \=> setIsHover(true)}
      onPointerLeave\={() \=> setIsHover(false)}
      style\={{
        backgroundColor: isHover ? '#ddd' : '#fff'
      }}
    \>
      {items.map(story \=> (
        <li key\={story.id}\>
          {story.label}
        </li\>
      ))}
    </ul\>
  );
}

Show more

Without Strict Mode, it was easy to miss the bug until you added more re-renders. Strict Mode made the same bug appear right away. Strict Mode helps you find bugs before you push them to your team and to your users.

[Read more about keeping components pure.](/learn/keeping-components-pure)

### Note

If you have [React DevTools](/learn/react-developer-tools)
 installed, any `console.log` calls during the second render call will appear slightly dimmed. React DevTools also offers a setting (off by default) to suppress them completely.

* * *

### Fixing bugs found by re-running Effects in development[](#fixing-bugs-found-by-re-running-effects-in-development "Link for Fixing bugs found by re-running Effects in development ")

Strict Mode can also help find bugs in [Effects.](/learn/synchronizing-with-effects)

Every Effect has some setup code and may have some cleanup code. Normally, React calls setup when the component _mounts_ (is added to the screen) and calls cleanup when the component _unmounts_ (is removed from the screen). React then calls cleanup and setup again if its dependencies changed since the last render.

When Strict Mode is on, React will also run **one extra setup+cleanup cycle in development for every Effect.** This may feel surprising, but it helps reveal subtle bugs that are hard to catch manually.

**Here is an example to illustrate how re-running Effects in Strict Mode helps you find bugs early.**

Consider this example that connects a component to a chat:

index.jsApp.jschat.js

index.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createRoot } from 'react-dom/client';
import './styles.css';

import App from './App';

const root = createRoot(document.getElementById("root"));
root.render(<App />);

There is an issue with this code, but it might not be immediately clear.

To make the issue more obvious, let’s implement a feature. In the example below, `roomId` is not hardcoded. Instead, the user can select the `roomId` that they want to connect to from a dropdown. Click “Open chat” and then select different chat rooms one by one. Keep track of the number of active connections in the console:

index.jsApp.jschat.js

index.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { createRoot } from 'react-dom/client';
import './styles.css';

import App from './App';

const root = createRoot(document.getElementById("root"));
root.render(<App />);

You’ll notice that the number of open connections always keeps growing. In a real app, this would cause performance and network problems. The issue is that [your Effect is missing a cleanup function:](/learn/synchronizing-with-effects#step-3-add-cleanup-if-needed)

      useEffect(() => {    const connection = createConnection(serverUrl, roomId);    connection.connect();    return () => connection.disconnect();  }, [roomId]);

Now that your Effect “cleans up” after itself and destroys the outdated connections, the leak is solved. However, notice that the problem did not become visible until you’ve added more features (the select box).

**In the original example, the bug wasn’t obvious. Now let’s wrap the original (buggy) code in `<StrictMode>`:**

index.jsApp.jschat.js

index.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './styles.css';

import App from './App';

const root = createRoot(document.getElementById("root"));
root.render(
  <StrictMode\>
    <App />
  </StrictMode\>
);

**With Strict Mode, you immediately see that there is a problem** (the number of active connections jumps to 2). Strict Mode runs an extra setup+cleanup cycle for every Effect. This Effect has no cleanup logic, so it creates an extra connection but doesn’t destroy it. This is a hint that you’re missing a cleanup function.

Strict Mode lets you notice such mistakes early in the process. When you fix your Effect by adding a cleanup function in Strict Mode, you _also_ fix many possible future production bugs like the select box from before:

index.jsApp.jschat.js

index.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './styles.css';

import App from './App';

const root = createRoot(document.getElementById("root"));
root.render(
  <StrictMode\>
    <App />
  </StrictMode\>
);

Notice how the active connection count in the console doesn’t keep growing anymore.

Without Strict Mode, it was easy to miss that your Effect needed cleanup. By running _setup → cleanup → setup_ instead of _setup_ for your Effect in development, Strict Mode made the missing cleanup logic more noticeable.

[Read more about implementing Effect cleanup.](/learn/synchronizing-with-effects#how-to-handle-the-effect-firing-twice-in-development)

* * *

### Fixing bugs found by re-running ref callbacks in development[](#fixing-bugs-found-by-re-running-ref-callbacks-in-development "Link for Fixing bugs found by re-running ref callbacks in development ")

Strict Mode can also help find bugs in [callbacks refs.](/learn/manipulating-the-dom-with-refs)

Every callback `ref` has some setup code and may have some cleanup code. Normally, React calls setup when the element is _created_ (is added to the DOM) and calls cleanup when the element is _removed_ (is removed from the DOM).

When Strict Mode is on, React will also run **one extra setup+cleanup cycle in development for every callback `ref`.** This may feel surprising, but it helps reveal subtle bugs that are hard to catch manually.

Consider this example, which allows you to select an animal and then scroll to one of them. Notice when you switch from “Cats” to “Dogs”, the console logs show that the number of animals in the list keeps growing, and the “Scroll to” buttons stop working:

index.jsApp.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef, useState } from "react";

export default function AnimalFriends() {
  const itemsRef = useRef(\[\]);
  const \[animalList, setAnimalList\] = useState(setupAnimalList);
  const \[animal, setAnimal\] = useState('cat');

  function scrollToAnimal(index) {
    const list = itemsRef.current;
    const {node} = list\[index\];
    node.scrollIntoView({
      behavior: "smooth",
      block: "nearest",
      inline: "center",
    });
  }
  
  const animals = animalList.filter(a \=> a.type === animal)
  
  return (
    <\>
      <nav\>
        <button onClick\={() \=> setAnimal('cat')}\>Cats</button\>
        <button onClick\={() \=> setAnimal('dog')}\>Dogs</button\>
      </nav\>
      <hr />
      <nav\>
        <span\>Scroll to:</span\>{animals.map((animal, index) \=> (
          <button key\={animal.src} onClick\={() \=> scrollToAnimal(index)}\>
            {index}
          </button\>
        ))}
      </nav\>
      <div\>
        <ul\>
          {animals.map((animal) \=> (
              <li
                key\={animal.src}
                ref\={(node) \=> {
                  const list = itemsRef.current;
                  const item = {animal: animal, node}; 
                  list.push(item);
                  console.log(\`✅ Adding animal to the map. Total animals: ${list.length}\`);
                  if (list.length > 10) {
                    console.log('❌ Too many animals in the list!');
                  }
                  return () \=> {
                    // 🚩 No cleanup, this is a bug!
                  }
                }}
              \>
                <img src\={animal.src} />
              </li\>
            ))}
          
        </ul\>
      </div\>
    </\>
  );
}

function setupAnimalList() {
  const animalList = \[\];
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'cat', src: "https://loremflickr.com/320/240/cat?lock=" + i});
  }
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'dog', src: "https://loremflickr.com/320/240/dog?lock=" + i});
  }

  return animalList;
}

Show more

**This is a production bug!** Since the ref callback doesn’t remove animals from the list in the cleanup, the list of animals keeps growing. This is a memory leak that can cause performance problems in a real app, and breaks the behavior of the app.

The issue is the ref callback doesn’t cleanup after itself:

    <li  ref={node => {    const list = itemsRef.current;    const item = {animal, node};    list.push(item);    return () => {      // 🚩 No cleanup, this is a bug!    }  }}</li>

Now let’s wrap the original (buggy) code in `<StrictMode>`:

index.jsApp.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef, useState } from "react";

export default function AnimalFriends() {
  const itemsRef = useRef(\[\]);
  const \[animalList, setAnimalList\] = useState(setupAnimalList);
  const \[animal, setAnimal\] = useState('cat');

  function scrollToAnimal(index) {
    const list = itemsRef.current;
    const {node} = list\[index\];
    node.scrollIntoView({
      behavior: "smooth",
      block: "nearest",
      inline: "center",
    });
  }
  
  const animals = animalList.filter(a \=> a.type === animal)
  
  return (
    <\>
      <nav\>
        <button onClick\={() \=> setAnimal('cat')}\>Cats</button\>
        <button onClick\={() \=> setAnimal('dog')}\>Dogs</button\>
      </nav\>
      <hr />
      <nav\>
        <span\>Scroll to:</span\>{animals.map((animal, index) \=> (
          <button key\={animal.src} onClick\={() \=> scrollToAnimal(index)}\>
            {index}
          </button\>
        ))}
      </nav\>
      <div\>
        <ul\>
          {animals.map((animal) \=> (
              <li
                key\={animal.src}
                ref\={(node) \=> {
                  const list = itemsRef.current;
                  const item = {animal: animal, node} 
                  list.push(item);
                  console.log(\`✅ Adding animal to the map. Total animals: ${list.length}\`);
                  if (list.length > 10) {
                    console.log('❌ Too many animals in the list!');
                  }
                  return () \=> {
                    // 🚩 No cleanup, this is a bug!
                  }
                }}
              \>
                <img src\={animal.src} />
              </li\>
            ))}
          
        </ul\>
      </div\>
    </\>
  );
}

function setupAnimalList() {
  const animalList = \[\];
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'cat', src: "https://loremflickr.com/320/240/cat?lock=" + i});
  }
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'dog', src: "https://loremflickr.com/320/240/dog?lock=" + i});
  }

  return animalList;
}

Show more

**With Strict Mode, you immediately see that there is a problem**. Strict Mode runs an extra setup+cleanup cycle for every callback ref. This callback ref has no cleanup logic, so it adds refs but doesn’t remove them. This is a hint that you’re missing a cleanup function.

Strict Mode lets you eagerly find mistakes in callback refs. When you fix your callback by adding a cleanup function in Strict Mode, you _also_ fix many possible future production bugs like the “Scroll to” bug from before:

index.jsApp.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useRef, useState } from "react";

export default function AnimalFriends() {
  const itemsRef = useRef(\[\]);
  const \[animalList, setAnimalList\] = useState(setupAnimalList);
  const \[animal, setAnimal\] = useState('cat');

  function scrollToAnimal(index) {
    const list = itemsRef.current;
    const {node} = list\[index\];
    node.scrollIntoView({
      behavior: "smooth",
      block: "nearest",
      inline: "center",
    });
  }
  
  const animals = animalList.filter(a \=> a.type === animal)
  
  return (
    <\>
      <nav\>
        <button onClick\={() \=> setAnimal('cat')}\>Cats</button\>
        <button onClick\={() \=> setAnimal('dog')}\>Dogs</button\>
      </nav\>
      <hr />
      <nav\>
        <span\>Scroll to:</span\>{animals.map((animal, index) \=> (
          <button key\={animal.src} onClick\={() \=> scrollToAnimal(index)}\>
            {index}
          </button\>
        ))}
      </nav\>
      <div\>
        <ul\>
          {animals.map((animal) \=> (
              <li
                key\={animal.src}
                ref\={(node) \=> {
                  const list = itemsRef.current;
                  const item = {animal, node};
                  list.push({animal: animal, node});
                  console.log(\`✅ Adding animal to the map. Total animals: ${list.length}\`);
                  if (list.length > 10) {
                    console.log('❌ Too many animals in the list!');
                  }
                  return () \=> {
                    list.splice(list.indexOf(item));
                    console.log(\`❌ Removing animal from the map. Total animals: ${itemsRef.current.length}\`);
                  }
                }}
              \>
                <img src\={animal.src} />
              </li\>
            ))}
          
        </ul\>
      </div\>
    </\>
  );
}

function setupAnimalList() {
  const animalList = \[\];
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'cat', src: "https://loremflickr.com/320/240/cat?lock=" + i});
  }
  for (let i = 0; i < 10; i++) {
    animalList.push({type: 'dog', src: "https://loremflickr.com/320/240/dog?lock=" + i});
  }

  return animalList;
}

Show more

Now on inital mount in StrictMode, the ref callbacks are all setup, cleaned up, and setup again:

    ...✅ Adding animal to the map. Total animals: 10...❌ Removing animal from the map. Total animals: 0...✅ Adding animal to the map. Total animals: 10

**This is expected.** Strict Mode confirms that the ref callbacks are cleaned up correctly, so the size never grows above the expected amount. After the fix, there are no memory leaks, and all the features work as expected.

Without Strict Mode, it was easy to miss the bug until you clicked around to app to notice broken features. Strict Mode made the bugs appear right away, before you push them to production.

* * *

### Fixing deprecation warnings enabled by Strict Mode[](#fixing-deprecation-warnings-enabled-by-strict-mode "Link for Fixing deprecation warnings enabled by Strict Mode ")

React warns if some component anywhere inside a `<StrictMode>` tree uses one of these deprecated APIs:

*   `UNSAFE_` class lifecycle methods like [`UNSAFE_componentWillMount`](/reference/react/Component#unsafe_componentwillmount)
    . [See alternatives.](https://reactjs.org/blog/2018/03/27/update-on-async-rendering.html#migrating-from-legacy-lifecycles)
    

These APIs are primarily used in older [class components](/reference/react/Component)
 so they rarely appear in modern apps.

[Previous<Profiler>](/reference/react/Profiler)
[Next<Suspense>](/reference/react/Suspense)

* * *

---

# createContext – React

[API Reference](/reference/react)

[APIs](/reference/react/apis)

createContext[](#undefined "Link for this heading")

====================================================

`createContext` lets you create a [context](/learn/passing-data-deeply-with-context)
 that components can provide or read.

    const SomeContext = createContext(defaultValue)

*   [Reference](#reference)
    *   [`createContext(defaultValue)`](#createcontext)
        
    *   [`SomeContext.Provider`](#provider)
        
    *   [`SomeContext.Consumer`](#consumer)
        
*   [Usage](#usage)
    *   [Creating context](#creating-context)
        
    *   [Importing and exporting context from a file](#importing-and-exporting-context-from-a-file)
        
*   [Troubleshooting](#troubleshooting)
    *   [I can’t find a way to change the context value](#i-cant-find-a-way-to-change-the-context-value)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `createContext(defaultValue)`[](#createcontext "Link for this heading")

Call `createContext` outside of any components to create a context.

    import { createContext } from 'react';const ThemeContext = createContext('light');

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `defaultValue`: The value that you want the context to have when there is no matching context provider in the tree above the component that reads context. If you don’t have any meaningful default value, specify `null`. The default value is meant as a “last resort” fallback. It is static and never changes over time.

#### Returns[](#returns "Link for Returns ")

`createContext` returns a context object.

**The context object itself does not hold any information.** It represents _which_ context other components read or provide. Typically, you will use [`SomeContext.Provider`](#provider)
 in components above to specify the context value, and call [`useContext(SomeContext)`](/reference/react/useContext)
 in components below to read it. The context object has a few properties:

*   `SomeContext.Provider` lets you provide the context value to components.
*   `SomeContext.Consumer` is an alternative and rarely used way to read the context value.

* * *

### `SomeContext.Provider`[](#provider "Link for this heading")

Wrap your components into a context provider to specify the value of this context for all components inside:

    function App() {  const [theme, setTheme] = useState('light');  // ...  return (    <ThemeContext.Provider value={theme}>      <Page />    </ThemeContext.Provider>  );}

#### Props[](#provider-props "Link for Props ")

*   `value`: The value that you want to pass to all the components reading this context inside this provider, no matter how deep. The context value can be of any type. A component calling [`useContext(SomeContext)`](/reference/react/useContext)
     inside of the provider receives the `value` of the innermost corresponding context provider above it.

* * *

### `SomeContext.Consumer`[](#consumer "Link for this heading")

Before `useContext` existed, there was an older way to read context:

    function Button() {  // 🟡 Legacy way (not recommended)  return (    <ThemeContext.Consumer>      {theme => (        <button className={theme} />      )}    </ThemeContext.Consumer>  );}

Although this older way still works, **newly written code should read context with [`useContext()`](/reference/react/useContext)
 instead:**

    function Button() {  // ✅ Recommended way  const theme = useContext(ThemeContext);  return <button className={theme} />;}

#### Props[](#consumer-props "Link for Props ")

*   `children`: A function. React will call the function you pass with the current context value determined by the same algorithm as [`useContext()`](/reference/react/useContext)
     does, and render the result you return from this function. React will also re-run this function and update the UI whenever the context from the parent components changes.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Creating context[](#creating-context "Link for Creating context ")

Context lets components [pass information deep down](/learn/passing-data-deeply-with-context)
 without explicitly passing props.

Call `createContext` outside any components to create one or more contexts.

    import { createContext } from 'react';const ThemeContext = createContext('light');const AuthContext = createContext(null);

`createContext` returns a context object. Components can read context by passing it to [`useContext()`](/reference/react/useContext)
:

    function Button() {  const theme = useContext(ThemeContext);  // ...}function Profile() {  const currentUser = useContext(AuthContext);  // ...}

By default, the values they receive will be the default values you have specified when creating the contexts. However, by itself this isn’t useful because the default values never change.

Context is useful because you can **provide other, dynamic values from your components:**

    function App() {  const [theme, setTheme] = useState('dark');  const [currentUser, setCurrentUser] = useState({ name: 'Taylor' });  // ...  return (    <ThemeContext.Provider value={theme}>      <AuthContext.Provider value={currentUser}>        <Page />      </AuthContext.Provider>    </ThemeContext.Provider>  );}

Now the `Page` component and any components inside it, no matter how deep, will “see” the passed context values. If the passed context values change, React will re-render the components reading the context as well.

[Read more about reading and providing context and see examples.](/reference/react/useContext)

* * *

### Importing and exporting context from a file[](#importing-and-exporting-context-from-a-file "Link for Importing and exporting context from a file ")

Often, components in different files will need access to the same context. This is why it’s common to declare contexts in a separate file. Then you can use the [`export` statement](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export)
 to make context available for other files:

    // Contexts.jsimport { createContext } from 'react';export const ThemeContext = createContext('light');export const AuthContext = createContext(null);

Components declared in other files can then use the [`import`](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/import)
 statement to read or provide this context:

    // Button.jsimport { ThemeContext } from './Contexts.js';function Button() {  const theme = useContext(ThemeContext);  // ...}

    // App.jsimport { ThemeContext, AuthContext } from './Contexts.js';function App() {  // ...  return (    <ThemeContext.Provider value={theme}>      <AuthContext.Provider value={currentUser}>        <Page />      </AuthContext.Provider>    </ThemeContext.Provider>  );}

This works similar to [importing and exporting components.](/learn/importing-and-exporting-components)

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### I can’t find a way to change the context value[](#i-cant-find-a-way-to-change-the-context-value "Link for I can’t find a way to change the context value ")

Code like this specifies the _default_ context value:

    const ThemeContext = createContext('light');

This value never changes. React only uses this value as a fallback if it can’t find a matching provider above.

To make context change over time, [add state and wrap components in a context provider.](/reference/react/useContext#updating-data-passed-via-context)

[PreviouscaptureOwnerStack](/reference/react/captureOwnerStack)
[Nextlazy](/reference/react/lazy)

* * *

---

# lazy – React

[API Reference](/reference/react)

[APIs](/reference/react/apis)

lazy[](#undefined "Link for this heading")

===========================================

`lazy` lets you defer loading component’s code until it is rendered for the first time.

    const SomeComponent = lazy(load)

*   [Reference](#reference)
    *   [`lazy(load)`](#lazy)
        
    *   [`load` function](#load)
        
*   [Usage](#usage)
    *   [Lazy-loading components with Suspense](#suspense-for-code-splitting)
        
*   [Troubleshooting](#troubleshooting)
    *   [My `lazy` component’s state gets reset unexpectedly](#my-lazy-components-state-gets-reset-unexpectedly)
        

* * *

Reference[](#reference "Link for Reference ")

----------------------------------------------

### `lazy(load)`[](#lazy "Link for this heading")

Call `lazy` outside your components to declare a lazy-loaded React component:

    import { lazy } from 'react';const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

[See more examples below.](#usage)

#### Parameters[](#parameters "Link for Parameters ")

*   `load`: A function that returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
     or another _thenable_ (a Promise-like object with a `then` method). React will not call `load` until the first time you attempt to render the returned component. After React first calls `load`, it will wait for it to resolve, and then render the resolved value’s `.default` as a React component. Both the returned Promise and the Promise’s resolved value will be cached, so React will not call `load` more than once. If the Promise rejects, React will `throw` the rejection reason for the nearest Error Boundary to handle.

#### Returns[](#returns "Link for Returns ")

`lazy` returns a React component you can render in your tree. While the code for the lazy component is still loading, attempting to render it will _suspend._ Use [`<Suspense>`](/reference/react/Suspense)
 to display a loading indicator while it’s loading.

* * *

### `load` function[](#load "Link for this heading")

#### Parameters[](#load-parameters "Link for Parameters ")

`load` receives no parameters.

#### Returns[](#load-returns "Link for Returns ")

You need to return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
 or some other _thenable_ (a Promise-like object with a `then` method). It needs to eventually resolve to an object whose `.default` property is a valid React component type, such as a function, [`memo`](/reference/react/memo)
, or a [`forwardRef`](/reference/react/forwardRef)
 component.

* * *

Usage[](#usage "Link for Usage ")

----------------------------------

### Lazy-loading components with Suspense[](#suspense-for-code-splitting "Link for Lazy-loading components with Suspense ")

Usually, you import components with the static [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)
 declaration:

    import MarkdownPreview from './MarkdownPreview.js';

To defer loading this component’s code until it’s rendered for the first time, replace this import with:

    import { lazy } from 'react';const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));

This code relies on [dynamic `import()`,](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
 which might require support from your bundler or framework. Using this pattern requires that the lazy component you’re importing was exported as the `default` export.

Now that your component’s code loads on demand, you also need to specify what should be displayed while it is loading. You can do this by wrapping the lazy component or any of its parents into a [`<Suspense>`](/reference/react/Suspense)
 boundary:

    <Suspense fallback={<Loading />}>  <h2>Preview</h2>  <MarkdownPreview /></Suspense>

In this example, the code for `MarkdownPreview` won’t be loaded until you attempt to render it. If `MarkdownPreview` hasn’t loaded yet, `Loading` will be shown in its place. Try ticking the checkbox:

App.jsLoading.jsMarkdownPreview.js

App.js

Reset[Fork](https://codesandbox.io/api/v1/sandboxes/define?undefined&environment=create-react-app "Open in CodeSandbox")

import { useState, Suspense, lazy } from 'react';
import Loading from './Loading.js';

const MarkdownPreview = lazy(() \=> delayForDemo(import('./MarkdownPreview.js')));

export default function MarkdownEditor() {
  const \[showPreview, setShowPreview\] = useState(false);
  const \[markdown, setMarkdown\] = useState('Hello, \*\*world\*\*!');
  return (
    <\>
      <textarea value\={markdown} onChange\={e \=> setMarkdown(e.target.value)} />
      <label\>
        <input type\="checkbox" checked\={showPreview} onChange\={e \=> setShowPreview(e.target.checked)} />
        Show preview
      </label\>
      <hr />
      {showPreview && (
        <Suspense fallback\={<Loading />}\>
          <h2\>Preview</h2\>
          <MarkdownPreview markdown\={markdown} />
        </Suspense\>
      )}
    </\>
  );
}

// Add a fixed delay so you can see the loading state
function delayForDemo(promise) {
  return new Promise(resolve \=> {
    setTimeout(resolve, 2000);
  }).then(() \=> promise);
}

Show more

This demo loads with an artificial delay. The next time you untick and tick the checkbox, `Preview` will be cached, so there will be no loading state. To see the loading state again, click “Reset” on the sandbox.

[Learn more about managing loading states with Suspense.](/reference/react/Suspense)

* * *

Troubleshooting[](#troubleshooting "Link for Troubleshooting ")

----------------------------------------------------------------

### My `lazy` component’s state gets reset unexpectedly[](#my-lazy-components-state-gets-reset-unexpectedly "Link for this heading")

Do not declare `lazy` components _inside_ other components:

    import { lazy } from 'react';function Editor() {  // 🔴 Bad: This will cause all state to be reset on re-renders  const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));  // ...}

Instead, always declare them at the top level of your module:

    import { lazy } from 'react';// ✅ Good: Declare lazy components outside of your componentsconst MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));function Editor() {  // ...}

[PreviouscreateContext](/reference/react/createContext)
[Nextmemo](/reference/react/memo)

* * *

---