Skip to content
Tutorials Center
My learning

Topics

React Reference ยท State Hooks

React useState hook

Reference for React useState: declare a state variable, update it with the setter, understand snapshots, batching, bail-out and the common mistakes.

useState gives a function component a piece of memory that survives between renders. You call it with an initial value and get back a pair: the current value and a setter function. Calling the setter asks React to render the component again with the new value.

State is a snapshot. Inside one render, the variable never changes, even if you call the setter. The new value shows up in the next render. This single idea explains most surprises people have with useState.

JSX
import { useState } from 'react';

const [count, setCount] = useState(0);

Try it

A counter and a text field
State is a snapshot

After one click the page shows count = 1, not 3: all three calls used the same snapshot value 0. To build on the previous value, pass an updater function (see useState updater functions).

Syntax

JSX
const [state, setState] = useState(initialState);
TypeScript
function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>];
type SetStateAction<S> = S | ((previous: S) => S);
Name Description
initialState The value for the first render. Ignored on later renders. If it is a function, React calls it (with no arguments) and uses the result; see lazy initialization.
state The current value: the initial value on the first render, then whatever was last stored.
setState(next) Stores next (a value or an updater function) and schedules a render.

Returns: an array of exactly two items. The setState function has a stable identity: it is the same function on every render, so it never needs to be listed in effect dependency arrays.

Edge cases: setState returns undefined. Calling it during render of the same component is allowed only as a guarded "adjust state while rendering" pattern. Calling it for a different component during render is an error.

Usage notes

  • Call it at the top level of a component or custom hook, never inside conditions, loops or nested functions (see Rules of Hooks). React matches state to hooks by call order.
  • Replace, don't mutate. For objects and arrays, create a new value ({ ...user, name }, [...items, item]). Mutating the existing object and calling the setter with it is ignored, because React compares with Object.is and sees the same reference.
  • Bail-out: if the new value is Object.is-equal to the current one, React skips rendering the children and running effects. It may still call your component function once more, so keep render pure.
  • Batching: several updates in the same event are processed together and produce one render. Since React 18 this includes updates inside timeouts, promises and native handlers.
  • Functions as state: setState(fn) treats fn as an updater. To store a function, wrap it: setState(() => fn).
  • State is per component instance. Two copies of <Counter /> have independent state, and state resets when the component is removed from the tree or its key changes.
  • Derived data is not state. If a value can be computed from props or other state, compute it during render instead of storing a copy that can go stale.
  • StrictMode in development renders components twice and calls initializer and updater functions twice to expose impure code. The extra calls are discarded.