5.3 - State and Component Memory

Components often change with user interaction. For example, typing into a form should update the input field, or clicking “buy” should put a product in the shopping cart. Components need to “remember” things: the current input value, the shopping cart.

In React, this kind of component-specific memory is called state.

The `useState` Hook

To update a component with new data, two things need to happen:

Retain the data between renders.
Trigger React to render the component with new data (re-rendering).

Why is retaining the data necessary?

Local variables don’t persist between renders.
Changes to local variables won’t trigger renders. React doesn’t realize it needs to render the component again with the new data.

The useState Hook provides those two things:

A state variable to retain the data between renders.
A state setter function to update the variable and trigger React to render the component again.

Adding a state variable

To add a state variable, import useState from React at the top of the file:

import { useState } from 'react';

warning

Hooks—functions starting with use—can only be called at the top level of your components.

You can’t call Hooks inside conditions, loops, or other nested functions.
Hooks are functions, but it’s helpful to think of them as unconditional declarations about your component’s needs.
You “use” React features at the top of your component similar to how you “import” modules at the top of your file.

When you call useState, you are telling React that you want this component to remember something. For example:

const [index, setIndex] = useState(0);

In this case, you want React to remember index.

tip

The convention is const [something, setSomething]. You could name it anything you like, but conventions make things easier to understand across projects.

The only argument to useState is the initial value of your state variable. In this example, the index’s initial value is set to 0 with useState(0).

Every time your component renders, useState gives you an array containing two values:

The state variable (index) with the value you stored.
The state setter function (setIndex) which can update the state variable and trigger React to render the component again.

Here's how this happens in action:

Let's use this gallery example to demonstrate how to use useState.

import { useState } from 'react';
// To add a state variable, import `useState` from React at the top of the file.
import { sculptureList } from './data.js'; // details not shown

export default function Gallery() {
  const [index, setIndex] = useState(0);
  // index is a state variable and setIndex is the setter function.

  function handleClick() {
    setIndex(index + 1);
  }

  let sculpture = sculptureList[index];
  return (
    <>
      <button onClick={handleClick}>
        Next
      </button>
      <h2>
        <i>{sculpture.name} </i> 
        by {sculpture.artist}
      </h2>
      <img 
        src={sculpture.url} 
        alt={sculpture.alt}
      />
    </>
  );
}

Your component renders the first time.
1. Because you passed 0 to useState as the initial value for index, it will return [0, setIndex].
2. React remembers 0 is the latest state value.
You update the state.
1. When a user clicks the button, it calls setIndex(index + 1).
2. index is 0, so it’s setIndex(1). This tells React to remember index is 1 now and triggers another render.
Your component’s second render.
1. React still sees useState(0), but because React remembers that you set index to 1, it returns [1, setIndex] instead.
And so on!

Giving a component multiple state variables

You can have as many state variables of as many types as you like in one component. This component has two state variables, a number index and a boolean showMore that’s toggled when you click “Show details”:

import { useState } from 'react';
import { sculptureList } from './data.js';

export default function Gallery() {
  const [index, setIndex] = useState(0);
  const [showMore, setShowMore] = useState(false);

  function handleNextClick() {
    setIndex(index + 1);
  }

  function handleMoreClick() {
    setShowMore(!showMore);
  }

  let sculpture = sculptureList[index];
  return (
    <>
      <button onClick={handleNextClick}>
        Next
      </button>
      <h2>
        <i>{sculpture.name} </i> 
        by {sculpture.artist}
      </h2>
      <button onClick={handleMoreClick}>
        {showMore ? 'Hide' : 'Show'} details
      </button>
      {showMore && <p>{sculpture.description}</p>}
      <img 
        src={sculpture.url} 
        alt={sculpture.alt}
      />
    </>
  );
}

It is a good idea to have multiple state variables if their state is unrelated, like index and showMore in this example.

But if you find that you often change two state variables together, it might be easier to combine them into one. For example, if you have a form with many fields, it’s more convenient to have a single state variable that holds an object than state variable per field.

State is isolated and private

State is local to a component instance on the screen. In other words, if you render the same component twice, each copy will have completely isolated state! Changing one of them will not affect the other.

This is what makes state different from regular variables that you might declare at the top of your module. State is not tied to a particular function call or a place in the code, but it’s “local” to the specific place on the screen. For example if you rendered two <Gallery /> components, their state would be stored separately.

import Gallery from './Gallery.js';

export default function Page() {
  return (
    <div className="Page">
      <Gallery />
      <Gallery />
    </div>
  );
}

Also notice how the Page component doesn’t “know” anything about the Gallery state or even whether it has any. Unlike props, state is fully private to the component declaring it. The parent component can’t change it. This lets you add state to any component or remove it without impacting the rest of the components.

What if you wanted both galleries to keep their states in sync? The right way to do it in React is to remove state from child components and add it to their closest shared parent. More on this [later].

The useState Hook​

Adding a state variable​

Here's how this happens in action:​

Giving a component multiple state variables​

State is isolated and private​

The `useState` Hook

Adding a state variable

Here's how this happens in action:

Giving a component multiple state variables

State is isolated and private