useState

const [state, setState] = useState(initialState)

• Reference
  • useState(initialState)
  • set functions, like setSomething(nextState)
• Usage
  • Adding state to a component
  • Updating state based on the previous state
  • Updating objects and arrays in state
  • Avoiding recreating the initial state
  • Resetting state with a key
  • Storing information from previous renders
• Troubleshooting
  • I’ve updated the state, but logging gives me the old value
  • I’ve updated the state, but the screen doesn’t update
  • I’m getting an error: “Too many re-renders”
  • My initializer or updater function runs twice
  • I’m trying to set state to a function, but it gets called instead

Reference

useState(initialState)

Call useState at the top level of your component to declare a state variable.

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.

See more examples below.

Parameters

Returns

useState returns an array with exactly two values:

Caveats

set functions, like setSomething(nextState)

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

Returns

set functions do not have a return value.

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 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 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. 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 .

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.

In Strict Mode, React will call your updater function twice in order to help you find accidental impurities. 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

Adding state to a component

Call useState at the top level of your component to declare one or more state variables.

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.

useState returns an array with exactly two items:

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.

function handleClick() {
  setName('Robin');
  console.log(name); // Still "Taylor"!
}