The useState Hook

Let's start by looking at a common example, a minimal “counter” demo.

Click the button, and watch the count increase:

Code Playground

import React from 'react';

function Counter() {

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

return (

<button onClick={() => setCount(count + 1)}>

Value: {count}

</button>

);

}

export default Counter;

There's a lot going on here, so let's break it down.

Our goal is to keep track of the number of times the user has clicked the button. Whenever we have “dynamic” values like this, we need to use React state. State is used for values that change over time.

To create a state variable, we use the useState function. This function takes a single argument: the initial value. In this case, that value initializes to 0. This value is chosen because when the page first loads, we've clicked the button 0 times.

useState is a hook. A hook is a special type of function that allows us to "hook into" React internals. We'll learn much more about hooks later in this course.

The useState hook returns an array containing two items:

The current value of the state variable. We've decided to call it count.
A function we can use to update the state variable. We named it setCount.

Destructuring Assignment (info)

If you're not familiar with array destructuring, this syntax might look a little wild to you!

To help you understand what's going on, here's the same logic, but expressed without using destructuring assignment:

const countArray = React.useState(0);

const count = countArray[0];
const setCount = countArray[1];

You can learn more in the “Array Destructuring” lesson 👀 from the JavaScript Primer reference module.

Naming conventions

When we create a state variable, we can name the two variables whatever we want. For example, this is equally valid:

const [hello, world] = React.useState(0);

That said, it's customary to follow the “x, setX” convention:

const [user, setUser] = React.useState();
const [errorMessage, setErrorMessage] = React.useState();
const [flowerBouquet, setFlowerBouquet] = React.useState();

The first destructured variable is the name of the thing we're tracking. The second variable prefixes that name with set, signifying that it's a function that can be called to change the thing. This is sometimes referred to as a “setter function”, since it sets the new value of the state variable.

Importing the hook? (info)

Some React tutorials write this sort of code in a slightly different way:

import React, { useState } from 'react';

function App() {
  const [num, setNum] = useState(0);

  return (
    <div>{num}</div>
  );
}

Instead of writing React.useState, we're importing the useState function at the top of the file and using it on its own, useState.

Here's the bottom line: these methods are completely equivalent, and either one works just fine.

Personally, I don't want to have to fuss with imports. It's a tiny distraction to me, and I'd rather write a few extra characters every time. But this is 100% personal preference, you can manage this however you wish.

Initial value

React state variables can be given an initial value:

const [count, setCount] = React.useState(1);
console.log(count); // 1

We can also supply a function. React will call this function on the very first render to calculate the initial value:

const [count, setCount] = React.useState(() => {
  return 1 + 1;
});

console.log(count); // 2

This is sometimes called an initializer function. It can occasionally be useful if we need to do an expensive operation to calculate the initial value. For example, reading from Local Storage:

const [count, setCount] = React.useState(() => {
  return window.localStorage.getItem('saved-count');
});

If you're not familiar with the Local Storage API, it's a way for us to save values on the user's device, so that it persists even after the browser tab is closed, and can be accessed on their next visit.

The benefit here is that we're only doing the expensive work (reading from Local Storage) once, on the initial render, rather than doing it on every single render.

We'll see a full example of how to persist React state to Local Storage later in the course.

Hang on a sec… what? (info)

Several students have wondered why this "secondary form" makes a difference. Aren't we only calculating it once, in either case?

What exactly is the difference between these two forms?

// Form 1:
const [count, setCount] = React.useState(
  window.localStorage.getItem('saved-count')
);

// Form 2:
const [count, setCount] = React.useState(() => {
  return window.localStorage.getItem('saved-count');
});

I think this is one of those cases where it's helpful to forget all about React, and to think of this as plain ol’ JavaScript.

Let's say we have this function:

function run() {
  console.log('Hello');
}

Whenever I call the run function, we'll log the word "Hello". If I call the function 5 times, I'd get 5 "Hello"s in the console.

Now, suppose we tweak it:

function run() {
  const sayHi = () => {
    console.log('Hello');
  };
}

Now, when I call the run function, nothing is logged to the console. That's because the console.log is packaged up in an inner function, sayHi. Every time we call the run function, we're creating a brand new sayHi function, but we're never calling it.

Alright, now let's look at the React code again:

function Counter() {
  const [count, setCount] = React.useState(
    window.localStorage.getItem('saved-count')
  );
}

Whenever we render the Counter component, this function will be called, and all of the code inside will run. We'll call window.localStorage on every single render, and pass the value into React.useState.

Now, let's consider the secondary form:

function Counter() {
  const [count, setCount] = React.useState(() => {
    return window.localStorage.getItem('saved-count');
  });
}

In this case, we're creating a function:

() => {
  return window.localStorage.getItem('saved-count');
}

This function is being passed into React.useState(). And so it's up to React to decide what to do with it.

On the very first render, React will call this function to calculate the initial value. On subsequent renders, however, React ignores the function. The initial value has already been calculated, and so there's no reason to call the function again.

I recognize that this stuff is complicated, especially if you're not already super comfortable with JavaScript 😅. Fortunately, this isn't something you need to understand right now. I suspect it'll click for you as you get more experience working with functions in JavaScript.