State: a component's memory

A quantity that won't go up

A shop's tea card has a quantity and a button that adds one. Here is a first try, written with what you know so far: a variable that holds the quantity, and a click handler that changes it. Click Add one three times.

1export default function TeaCard() {2  let quantity = 1;3 4  function addOne() {5    quantity = quantity + 1;6    console.log("quantity is now", quantity);7  }8 9  return (10    <div>11      <h3>Green tea</h3>12      <p>Quantity: {quantity}</p>13      <button onClick={addOne}>Add one</button>14    </div>15  );16}

Line 2 makes a variable, quantity, set to 1. addOne on lines 4 to 7 adds one to it on line 5 and prints the new value on line 6. Line 12 shows the quantity, and line 13 runs addOne on every click.

The console under the result says quantity is now 2, 3, 4: the variable really does change. The screen still says Quantity: 1. The click changed a JavaScript variable, and React drew the screen once, before any click. Nothing told it to draw again.

A component needs a way to remember a value between clicks and to show the new value when it changes. React calls that memory state. Here is the same card with a state variable:

1import { useState } from "react";2 3export default function TeaCard() {4  const [quantity, setQuantity] = useState(1);5 6  function addOne() {7    setQuantity(quantity + 1);8  }9 10  return (11    <div>12      <h3>Green tea</h3>13      <p>Quantity: {quantity}</p>14      <button onClick={addOne}>Add one</button>15    </div>16  );17}

Line 1 imports useState from React. Line 4 asks React to remember a quantity for this card, starting at 1, and gets back two things: quantity, the value now, and setQuantity, a function that changes it. Line 7 calls setQuantity(quantity + 1) instead of changing the variable. Click Add one: the screen says 2, then 3. Every call to setQuantity stores the new value and asks React to run TeaCard again, and this time line 4 hands back the new value.

Why a normal variable isn't enough

Two things stop a local variable, one declared inside the component, from working:

1. Changing it doesn't ask React to render. React draws the screen when something asks it to. A plain = is ordinary JavaScript: React never hears about it.
2. Every render starts it again. When React does render, it calls your component function from the top. Line 2's let quantity = 1 runs again and makes a new variable, set to 1. Whatever the clicks did is gone.

The first problem is easy to see. The second needs a render that something else starts. This card keeps its price in state, so Apply sale makes React render it. Click Add one three times, then Apply sale, then Add one again, and watch the console.

1import { useState } from "react";2 3export default function TeaCard() {4  let quantity = 1;5  const [price, setPrice] = useState(4);6  console.log("Render: quantity starts at", quantity);7 8  function addOne() {9    quantity = quantity + 1;10    console.log("quantity is now", quantity);11  }12 13  return (14    <div>15      <h3>Green tea: ${price}</h3>16      <p>Quantity: {quantity}</p>17      <button onClick={addOne}>Add one</button>18      <button onClick={() => setPrice(3)}>Apply sale</button>19    </div>20  );21}

Line 4 is the local variable and line 5 a piece of state, the price, starting at 4. Line 6 prints a line every time TeaCard runs. When the result first appears, the console shows Render: quantity starts at 1 with a small 2 beside it: in development, React's StrictMode calls each component twice to catch mistakes, and this page's console shows a line printed twice in a row once, with the count beside it. Keeping components pure explains why.

The three clicks print quantity is now 2, 3, and 4, and the screen stays at 1. Apply sale calls setPrice(3) on line 18, so React renders: the heading on line 15 says Green tea: $3, and the console prints Render: quantity starts at 1 again. The new render made a new quantity. Click Add one once more: the console says quantity is now 2. The count of 4 was lost.

So state has two jobs: keep a value between renders, and ask for a render when it changes. useState gives you one tool for each. Here are the two kinds of variable, side by side:

How to read the table: each row asks one question of a local variable and of a state variable.

The playground runs a card that has both, side by side. Its list shows every click on the local button and every render React makes, with the values each one saw. Press Add one to the local variable twice, then Add one with setQuantity.

1function TeaCard() {2  let localQuantity = 1;3  const [quantity, setQuantity] = useState(1);4 5  function addLocal() {6    localQuantity = localQuantity + 1;7  }8 9  function addState() {10    setQuantity(quantity + 1);11  }12 13  return (14    <div>15      <p>Local variable: {localQuantity}</p>16      <p>State: {quantity}</p>17      <button onClick={addLocal}>Add one to the local variable</button>18      <button onClick={addState}>Add one with setQuantity</button>19    </div>20  );21}

The local clicks add rows but no render: localQuantity becomes 2, then 3, and the card still says Local variable: 1. The setQuantity click adds a render row: React ran TeaCard again, localQuantity started at 1 again, and useState(1) gave 2, the value it remembered. Local variables are still useful. They hold what you work out during one render, like a line total; they just can't remember anything for the next one.

useState: a value React keeps, and a function to change it

Here is the line that gives the card its memory, from the state card above:

const [quantity, setQuantity] = useState(1);

Read it from the right:

1. useState(1) tells React: remember a value for this component, and start it at 1. The 1 is the initial value; React uses it on the first render only.
2. It returns an array of exactly two items: the value now, and a set function that changes it.
3. The square brackets on the left are array destructuring: they take the two items out and name them quantity and setQuantity.

The names are yours to choose. The habit is [something, setSomething]: [price, setPrice], [isOpen, setIsOpen]. Following it makes any React code easier to read, because the set function says which value it changes.

useState is a hook. Hooks are React functions whose names start with use, and they let a component use a React feature: here, memory. Call them at the top level of your component, not inside an if, a loop, or a click handler. The last section of this lesson shows why, and The rules of hooks covers the rules in full.

What happens on each render? This card prints what useState gave it, every time React calls it. Click Add one twice.

1import { useState } from "react";2 3export default function TeaCard() {4  const [quantity, setQuantity] = useState(1);5  console.log("Render: useState gave", quantity);6 7  return (8    <div>9      <h3>Green tea</h3>10      <p>Quantity: {quantity}</p>11      <button onClick={() => setQuantity(quantity + 1)}>Add one</button>12    </div>13  );14}

The console shows Render: useState gave 1, then 2, then 3, each with the StrictMode 2 beside it. Line 4 is the same useState(1) every time, but only the first render gets 1:

1. First render. React has nothing stored for this card yet, so it stores the initial value, 1, and line 4 gets [1, setQuantity].
2. A click. Line 11 calls setQuantity(quantity + 1), which is setQuantity(2) in this render. React stores 2 and asks for a new render.
3. Second render. React calls TeaCard again. Line 4 calls useState(1), and React hands back what it stored: [2, setQuantity]. The 1 is ignored now.

One thing to notice: setQuantity(2) doesn't change the quantity variable in the code that's running. That render keeps its 1; the next render gets 2. State as a snapshot shows what that means for your handlers, and the next lesson, Render and commit, follows what React does after you call a set function.

More than one piece of state

A component can call useState as many times as it needs, once for each thing to remember, of any type. This tea gallery remembers which tea it shows, a number, and whether the details are open, a boolean (true or false). The teas are in a second file, teas.js, in the next tab. Click Next tea and Show details.

1import { useState } from "react";2import { teas } from "./teas.js";3 4export default function TeaGallery() {5  const [index, setIndex] = useState(0);6  const [showDetails, setShowDetails] = useState(false);7  const tea = teas[index];8  const isLast = index === teas.length - 1;9 10  return (11    <div>12      <h3>{tea.name}: ${tea.price}</h3>13      <p>Tea {index + 1} of {teas.length}</p>14      <button onClick={() => setIndex(index + 1)} disabled={isLast}>15        Next tea16      </button>17      <button onClick={() => setShowDetails(!showDetails)}>18        {showDetails ? "Hide details" : "Show details"}19      </button>20      {showDetails && <p>{tea.details}</p>}21    </div>22  );23}

Line 5 keeps index, the position of the tea in the list, starting at 0. Line 6 keeps showDetails, starting at false. Line 7 picks the tea from the list, and line 8 works out whether it's the last one. Both are plain variables, worked out again from state on every render. Line 14's button adds one to index, and is turned off on the last tea. Line 17's button flips showDetails with !, and line 20 shows the details only while it's true (the Conditional rendering lesson covers &&).

The two pieces of state don't affect each other. Open the details, then press Next tea: the details stay open and show the Black tea's text, because showDetails is still true. Each call to a set function changes only its own value.

Each copy of a component has its own state

State belongs to one use of a component on the page, not to the function. Here App uses TeaCard twice. TeaCard is in its own file, in the second tab. Click Green tea's Add one twice.

1import TeaCard from "./TeaCard.jsx";2 3export default function App() {4  return (5    <div className="shelf">6      <TeaCard name="Green tea" />7      <TeaCard name="Mint tea" />8    </div>9  );10}

In TeaCard.jsx, line 4 keeps a quantity, and line 10's button adds one. In App.jsx, lines 6 and 7 use TeaCard twice. After your clicks, Green tea says Quantity: 3 and Mint tea still says Quantity: 1. Both copies run the same useState(1) line, but React keeps a separate value for each copy.

Press Edit & run and add a third card under line 7: <TeaCard name="Black tea" />. It appears with Quantity: 1, its own memory from the start.

State is also private. App can't read a card's quantity or change it; only the card's own setQuantity can. That's what makes a component safe to reuse: putting a third card on the page can't break the other two. When two components need the same value, like a cart count that every card adds to, you keep that value in their shared parent and pass it down as props. The practical section below does that, and Sharing state between components covers it in full.

How React knows which state is which

Look at the gallery again: line 5 calls useState(0) and line 6 calls useState(false). Neither call says which value it wants. React doesn't read your variable names either. So how does the second call get showDetails and not index?

By order. For every copy of every component, React keeps its state in a list. On each render, the first useState call gets the first value in the list, the second call gets the second, and so on. Here is a small model of that idea in plain JavaScript, written for this lesson. It isn't React's code, but it works the same way for one card:

const slots = [];
let next = 0;

function useState(initial) {
  const index = next;
  if (index === slots.length) slots.push(initial);
  next = next + 1;
  const setState = (value) => { slots[index] = value; };
  return [slots[index], setState];
}

function TeaCard() {
  const [quantity, setQuantity] = useState(1);
  const [showDetails] = useState(false);
  return { quantity, showDetails, setQuantity };
}

function render() {
  next = 0;
  return TeaCard();
}

const first = render();
first.setQuantity(2);
const second = render();
console.log(second.quantity, second.showDetails);

Line 1 is the model's memory, slots, and line 2 is next, the slot the next call gets. In useState (lines 4 to 10), line 5 takes the slot number, line 6 stores the starting value only if that slot is new, line 7 moves the counter on, line 8 makes a set function that writes to that one slot (it remembers index, a closure), and line 9 returns the pair. TeaCard on lines 12 to 16 calls it twice, like the gallery. render on lines 18 to 21 puts the counter back to 0, then calls the component. Lines 23 to 26 render, set the quantity to 2, render again, and print 2 false. Press Edit & run to see it, or step through it:

1const slots = [];Run2let next = 0;3 4function useState(initial) {5  const index = next;6  if (index === slots.length) slots.push(initial);7  next = next + 1;8  const setState = (value) => { slots[index] = value; };9  return [slots[index], setState];10}11 12function TeaCard() {13  const [quantity, setQuantity] = useState(1);14  const [showDetails] = useState(false);15  return { quantity, showDetails, setQuantity };16}17 18function render() {19  next = 0;20  return TeaCard();21}22 23const first = render();24first.setQuantity(2);25const second = render();26console.log(second.quantity, second.showDetails);

This only works if the calls come in the same order on every render. Put a useState inside an if, and on a render where the if is false, every later call would take its neighbour's slot. That's why hooks go at the top level of a component. React warns you when the order changes, and a linter plugin catches it as you type; The rules of hooks shows both. Real React keeps a linked list of hooks on an object for each copy of each component, which is how two cards get two lists; How hooks work inside reads that code.

Choosing what goes in state on a shop page

A real page has state in more than one place. In this shop, each card remembers its own quantity and whether you've added it, and the page remembers how many items are in the cart. Pick a quantity on each card and press Add to cart.

1import { useState } from "react";2import TeaCard from "./TeaCard.jsx";3 4export default function App() {5  const [cartCount, setCartCount] = useState(0);6 7  function addToCart(quantity) {8    setCartCount(cartCount + quantity);9  }10 11  return (12    <>13      <p>Cart: {cartCount} items</p>14      <div className="shelf">15        <TeaCard name="Green tea" price={4} onAdd={addToCart} />16        <TeaCard name="Mint tea" price={5} onAdd={addToCart} />17      </div>18    </>19  );20}

In TeaCard.jsx, line 4 keeps the quantity and line 5 keeps added, starting at false. The minus button on lines 16 to 18 is off at 1, so the quantity can't go below 1. Line 24 works out the line total during the render: it isn't state, because price and quantity already say what it is. handleAdd on lines 7 to 10 tells the page how many to add, with onAdd(quantity), then sets added, so line 25's button says Add again.

In App.jsx, line 5 keeps cartCount. The cart belongs to the whole page, so it lives in App, which passes addToCart to both cards on lines 15 and 16. Set Green tea to 2 and add it, then add one Mint tea: the cart says Cart: 3 items. Each card's quantity stays private, and the shared count lives in their parent.

Before you add state, ask two questions. Does it change while the page is open? Can you work it out from props or other state? Only something that changes and can't be worked out needs state. Sort these:

Common mix-ups

• "Changing a variable updates the screen." No. Only a set function asks React to render. A local let changes, and the screen keeps the last render's value.
• "useState(1) sets the value to 1 on every render." No. The 1 counts on the first render only. After that, useState hands back what React kept.
• "Two copies of a component share their state." No. Each copy on the page has its own. Clicking Green tea never changes Mint tea.
• "A parent can read or change its child's state." No. State is private to the component that declares it. To share a value, keep it in the parent and pass it down as a prop.
• "Everything that changes on the screen needs its own state." No. A line total that you can work out from price and quantity is a plain variable in the render.
• "React finds my state by the variable name." No. It goes by the order of the useState calls, which is why they must run in the same order every render.

Practice exercises

Predict first, then check. Each exercise shows its result, or shows it when you press Edit & run; change the code and the result updates as you type.

export default function LikeButton() {
  let likes = 0;

  function like() {
    likes = likes + 1;
    console.log("likes is now", likes);
  }

  return (
    <p>
      Likes: {likes} <button onClick={like}>Like</button>
    </p>
  );
}

1export default function LikeButton() {2  let likes = 0;3 4  function like() {5    likes = likes + 1;6    console.log("likes is now", likes);7  }8 9  return (10    <p>11      Likes: {likes} <button onClick={like}>Like</button>12    </p>13  );14}

1export default function LikeButton() {2  let likes = 0;3 4  function like() {5    likes = likes + 1;6    console.log("likes is now", likes);7  }8 9  return (10    <p>11      Likes: {likes} <button onClick={like}>Like</button>12    </p>13  );14}

1import { useState } from "react";2 3export default function LikeButton() {4  const [likes, setLikes] = useState(0);5 6  function like() {7    setLikes(likes + 1);8  }9 10  return (11    <p>12      Likes: {likes} <button onClick={like}>Like</button>13    </p>14  );15}

import TeaCard from "./TeaCard.jsx";

export default function App() {
  return (
    <div className="shelf">
      <TeaCard name="Green tea" />
      <TeaCard name="Mint tea" />
    </div>
  );
}

1import TeaCard from "./TeaCard.jsx";2 3export default function App() {4  return (5    <div className="shelf">6      <TeaCard name="Green tea" />7      <TeaCard name="Mint tea" />8    </div>9  );10}

1import { useState } from "react";2 3export default function TeaCard() {4  const [quantity, setQuantity] = useState(1);5 6  function addOne() {7    setQuantity(quantity + 1);8  }9 10  return (11    <div>12      <h3>Green tea</h3>13      <p>Quantity: {quantity}</p>14      <button onClick={addOne}>Add one</button>15    </div>16  );17}

1import { useState } from "react";2 3export default function TeaCard() {4  const [quantity, setQuantity] = useState(1);5  const [giftWrap, setGiftWrap] = useState(false);6 7  function addOne() {8    setQuantity(quantity + 1);9  }10 11  return (12    <div>13      <h3>Green tea</h3>14      <p>Quantity: {quantity}</p>15      <button onClick={addOne}>Add one</button>16      <button onClick={() => setGiftWrap(!giftWrap)}>17        Gift wrap: {giftWrap ? "on" : "off"}18      </button>19    </div>20  );21}

1import { useState } from "react";2import { teas } from "./teas.js";3 4export default function TeaGallery() {5  const [index, setIndex] = useState(0);6  const [showDetails, setShowDetails] = useState(false);7  const tea = teas[index];8  const isLast = index === teas.length - 1;9 10  return (11    <div>12      <h3>{tea.name}: ${tea.price}</h3>13      <p>Tea {index + 1} of {teas.length}</p>14      <button onClick={() => setIndex(index + 1)} disabled={isLast}>15        Next tea16      </button>17      <button onClick={() => setShowDetails(!showDetails)}>18        {showDetails ? "Hide details" : "Show details"}19      </button>20      {showDetails && <p>{tea.details}</p>}21    </div>22  );23}

1import { useState } from "react";2import { teas } from "./teas.js";3 4export default function TeaGallery() {5  const [index, setIndex] = useState(0);6  const [showDetails, setShowDetails] = useState(false);7  const tea = teas[index];8 9  return (10    <div>11      <h3>{tea.name}: ${tea.price}</h3>12      <p>Tea {index + 1} of {teas.length}</p>13      <button onClick={() => setIndex((index + 1) % teas.length)}>14        Next tea15      </button>16      <button onClick={() => setShowDetails(!showDetails)}>17        {showDetails ? "Hide details" : "Show details"}18      </button>19      {showDetails && <p>{tea.details}</p>}20    </div>21  );22}

import { useState } from "react";

function TeaCard({ start }) {
  const [quantity, setQuantity] = useState(start);

  return (
    <p>
      Quantity: {quantity}{" "}
      <button onClick={() => setQuantity(quantity + 1)}>Add one</button>
    </p>
  );
}

export default function App() {
  const [start, setStart] = useState(1);

  return (
    <>
      <button onClick={() => setStart(10)}>Bulk order</button>
      <p>Starting value: {start}</p>
      <TeaCard start={start} />
    </>
  );
}

1import { useState } from "react";2 3function TeaCard({ start }) {4  const [quantity, setQuantity] = useState(start);5 6  return (7    <p>8      Quantity: {quantity}{" "}9      <button onClick={() => setQuantity(quantity + 1)}>Add one</button>10    </p>11  );12}13 14export default function App() {15  const [start, setStart] = useState(1);16 17  return (18    <>19      <button onClick={() => setStart(10)}>Bulk order</button>20      <p>Starting value: {start}</p>21      <TeaCard key={start} start={start} />22    </>23  );24}

Check your understanding

For each code question, ask what is in state, and what asks React to render. Press Edit & run on a question's code to check your answer.

Key takeaways

• A local variable can't hold a component's memory: changing it doesn't ask React to render, and every render makes it again.
• useState(initial) returns [value, setValue]. The initial value counts on the first render only; after that, React hands back what it kept.
• Calling the set function stores the new value and asks React to render the component again.
• A component can have many state variables. Keep only what changes and can't be worked out from props or other state.
• Every copy of a component has its own, private state. To share a value, keep it in the parent and pass it down.
• React matches useState calls to their values by order, so hooks go at the top level of the component.

Coming next: Render and commit. It follows what happens after you call a set function: React renders your components, changes only what differs on the page, and the browser paints.