useState in React: A complete guide

Editor’s note: This React useState Hook tutorial was last updated on 7 February 2023 to include more information on React useStateand to reflect updates to React. Check out our React Hooks reference guide and cheat sheet for more information about React Hooks.

The React useState Hook allows you to have state variables in functional components. You pass the initial state to this function, and it returns a variable with the current state value (not necessarily the initial state) and another function to update this value.

This tutorial serves as a complete guide to the useState Hook in React, the equivalent of this.state/this.setSate for functional components.

If you’re just getting started with React Hooks and looking for a visual guide, check out the video tutorial below:

Class and functional components in React

There are two types of components in React: class and functional components.

Class components are ES6 classes that extend the built-in Component class and can have state and lifecycle methods:

import { Component } from 'react';
class Message extends Component {
  constructor(props) {
    super(props);
    this.state = {
      message: ''    
    };
  }

  componentDidMount() {
    /* ... */
  }

  render() {
    return <div>{this.state.message}</div>;
  }
}

N.B., the React team recommends defining components as functions instead of classes. Here’s a migration guide.

Functional components are functions that accept arguments as the properties of the component and return valid JSX, as shown below:

function Message(props) {
  return <div>{props.message}</div>
}
// Or as an arrow function
const Message = (props) =>  <div>{props.message}</div>

As you can see, there are no state or lifecycle methods. However, as of React v16.8, we can use Hooks. React Hooks are functions that add state variables to functional components and instrument the lifecycle methods of classes. They tend to start with use.

What is the useState Hook?

useState is React Hook that allows you to add state to a functional component. It returns an array with two values: the current state and a function to update it. The Hook takes an initial state value as an argument and returns an updated state value whenever the setter function is called. It can be used like this:

const [state, setState] = useState(initialValue);

Here, the initialValue is the value you want to start with, and state is the current state value that can be used in your component. The setState function can be used to update the state, triggering a re-render of your component.

What can useState hold?

In React, useState can store any type of value, whereas the state in a class component is limited to being an object. This includes primitive data types like string, number, and Boolean, as well as complex data types such as array, object, and function. It can even cover custom data types like class instances.

Basically, anything that can be stored in a JavaScript variable can be stored in a state managed by useState.

Updating objects and arrays in useState

Never directly modify an object or array stored in useState. Instead, you should create a new updated version of the object or array and call setState with the new version. For example:

// Objects
const [state, setState] = useState({ name: 'John', age: 30 });

const updateName = () => {
  setState({ ...state, name: 'Jane' });
};

const updateAge = () => {
  setState({ ...state, age: state.age + 1 });
};

// Arrays
const [array, setArray] = useState([1, 2, 3, 4, 5]);

const addItem = () => {
  setArray([...array, 6]);
};

const removeItem = () => {
  setArray(array.slice(0, array.length - 1));
};

What does the React.useState Hook do?

As stated previously, useState enables you to add state to function components. Calling React.useState inside a function component generates a single piece of state associated with that component.

Whereas the state in a class is always an object, with Hooks, the state can be any type. Each piece of state holds a single value: an object, an array, a Boolean, or any other type you can imagine.

So, when should you use the useState Hook? Well, it’s beneficial for local component state, but larger projects can require additional state management solutions.

Declaring state in React

useState is a named export from react. To use it, you can write React.useState or import it by writing useState:

import React, { useState } from 'react';

The state object that can be declared in a class and allows you to declare more than one state variable, as shown below:

import React from 'react';

class Message extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      message: '',
      list: [],    
    };
  }
  /* ... */
}

However, unlike the state object, the useState Hook allows you to declare only one state variable (of any type) at a time, like this:

import React, { useState } from 'react';

const Message= () => {
   const messageState = useState( '' );
   const listState = useState( [] );
}

So, useState takes the initial value of the state variable as an argument, and you can pass it directly, as shown in the previous example. You can also use a function to lazily initialize the variable. This is useful when the initial state is the result of an expensive computation, as shown below:

const Message= () => {
   const messageState = useState( () => expensiveComputation() );
   /* ... */
}

The initial value will be assigned only on the initial render. If it’s a function, it will be executed only on the initial render. In subsequent renders (due to a change of state in the component or a parent component), the argument of the useState Hook will be ignored, and the current value will be retrieved.

It is important to keep this in mind because, for example, if you want to update the state based on the new properties the component receives, using useState alone won’t work. This is because its argument is used the first time only — not every time the property changes (look here for the right way to do this). This is shown here:

const Message= (props) => {
   const messageState = useState( props.message );
   /* ... */
}

But, useState doesn’t return just a variable, as the previous examples imply. It returns an array, where the first element is the state variable and the second element is a function to update the value of the variable:

const Message= () => {
   const messageState = useState( '' );
   const message = messageState[0]; // Contains ''
   const setMessage = messageState[1]; // It's a function
}

Usually, you’ll use array destructuring to simplify the code shown above like this:

const Message= () => {
   const [message, setMessage]= useState( '' );
}

This way, you can use the state variable in the functional component like any other variable:

const Message = () => {
  const [message, setMessage] = useState( '' );

  return (
    <p>
      <strong>{message}</strong>
    </p>
  );
};

But, why does useState return an array? This is because, compared to an object, an array is more flexible and easy to use. If the method returned an object with a fixed set of properties, you wouldn’t be able to assign custom names easily.

Instead, you’d have to do something like this (assuming the properties of the object are state and setState):

// Without using object destructuring
const messageState = useState( '' );
const message = messageState.state;
const setMessage = messageState

// Using object destructuring
const { state: message, setState: setMessage } = useState( '' );
const { state: list, setState: setList } = useState( [] );

Using React Hooks to update the state

The second element returned by useState is a function that takes a new value to update the state variable. Here’s an example that uses a text box to update the state variable on every change:

const Message = () => {
  const [message, setMessage] = useState( '' );

  return (
    <div>
      <input
         type="text"
         value={message}
         placeholder="Enter a message"
         onChange={e => setMessage(e.target.value)}
       />
      <p>
        <strong>{message}</strong>
      </p>
    </div>
  );
};

You can try that here:

However, this update function doesn’t update the value right away. Instead, it enqueues the update operation. Then, after re-rendering the component, the argument of useState will be ignored, and this function will return the most recent value.

When updating state based on its previous value, you need to pass a function to the setter function that updates the state. This function receives the previous state value as an argument and returns the new state value, as shown below:

const Message = () => {
  const [message, setMessage] = useState( '' );

  return (
    <div>
      <input
        type="text"
        value={message}
        placeholder="Enter some letters"
        onChange={e => {
          const val = e.target.value;
          setMessage(prev => prev + val)
        } }
      />
      <p>
        <strong>{message}</strong>
      </p>
    </div>
  );
};

You can try that here:

Implementing an object as a state variable with useState Hook

There are two things you need to keep in mind about updates when using objects:

• The importance of immutability
• And the fact that the setter returned by useState doesn’t merge objects like setState() does in class components

About the first point, if you use the same value as the current state to update the state (React uses Object.is() for comparing), React won’t trigger a re-render.

When working with objects, it’s easy to make the following mistake:

const Message = () => {
  const [messageObj, setMessage] = useState({ message: '' });

  return (
    <div>
      <input
        type="text"
        value={messageObj.message}
        placeholder="Enter a message"
        onChange={e => {
          messageObj.message = e.target.value;
          setMessage(messageObj); // Doesn't work
        }}
      />
      <p>
        <strong>{messageObj.message}</strong>
      </p>
  </div>
  );
};

Here’s the Code Sandbox:

Instead of creating a new object, the above example mutates the existing state object. To React, that’s the same object. To make it work, we must create a new object, just like we discussed earlier:

onChange={e => {
  const newMessageObj = { message: e.target.value };
  setMessage(newMessageObj); // Now it works
}}

This leads us to the second important thing you need to remember. When you update a state variable, unlike this.setState in a class component, the function returned by useState does not automatically merge update objects, it replaces them.

Following the previous example, if we add another property to the message object (id) as shown below:

const Message = () => {
  const [messageObj, setMessage] = useState({ message: '', id: 1 });

  return (
    <div>
      <input
        type="text"
        value={messageObj.message}
        placeholder="Enter a message"
        onChange={e => {
          const newMessageObj = { message: e.target.value };
          setMessage(newMessageObj); 
        }}
      />
      <p>
        <strong>{messageObj.id} : {messageObj.message}</strong>
      </p>
  </div>
  );
};

And we only update the message property like in the above example, React will replace the original { message: '', id: 1 } state object with the object used in the onChange event, which only contains the message property:

{ message: ‘message entered’ } // id property is lost

You can see how the id property is lost here:

You can replicate the behavior of setState() by using the function argument that contains the object to be replaced and the object spread syntax:

onChange={e => {
  const val = e.target.value;
  setMessage(prevState => {
    return { ...prevState, message: val }
  });
}}

The ...prevState part will get all of the properties of the object, and the message: val part will overwrite the message property. This will have the same result as using Object.assign() (just remember to create a new object):

onChange={e => {
  const val = e.target.value;
  setMessage(prevState => {
    return Object.assign({}, prevState, { message: val });
  });
}}

Try it here:

However, the spread syntax simplifies this operation, and it also works with arrays. Basically, when applied to an array, the spread syntax removes the brackets so you can create another one with the values of the original array:

[
  ...['a', 'b', 'c'],
  'd'
]
// Is equivalent to
[
  'a', 'b', 'c',
  'd'
]

Here’s an example that shows how to use useState with arrays:

const MessageList = () => {
  const [message, setMessage] = useState("");
  const [messageList, setMessageList] = useState([]);

  return (
    <div>
      <input
        type="text"
        value={message}
        placeholder="Enter a message"
        onChange={e => {
          setMessage(e.target.value);
        }}
      />
      <input
        type="button"
        value="Add"
        onClick={e => {
          setMessageList([
            ...messageList,
            {
              // Use the current size as ID (needed to iterate the list later)
              id: messageList.length + 1,
              message: message
            }
          ]);
          setMessage(""); // Clear the text box
        }}
      />
      <ul>
        {messageList.map(m => (
          <li key={m.id}>{m.message}</li>
        ))}
      </ul>
    </div>
  );
};

You have to be careful when applying the spread syntax to multi-dimensional arrays because it won’t work as you might expect. This leads us to another thing to consider when working with objects as the state.

How to update state in a nested object in React with Hooks

In JavaScript, multi-dimensional arrays are arrays within arrays, as shown below:

[
  ['value1','value2'],
  ['value3','value4']
]

You could use them to group all your state variables in one place. However, for that purpose, it would be better to use nested objects like this:

{
  'row1' : {
    'key1' : 'value1',
    'key2' : 'value2'
  },
  'row2' : {
    'key3' : 'value3',
    'key4' : 'value4'
  }
}

But, the problem when working with multi-dimensional arrays and nested objects is that Object.assign and the spread syntax will create a shallow copy instead of a deep copy.

From the spread syntax documentation:

Spread syntax effectively goes one level deep while copying an array. Therefore, it may be unsuitable for copying multi-dimensional arrays, as the following example shows. (The same is true with Object.assign() and spread syntax.)

let a = [[1], [2], [3]];
let b = [...a];

b.shift().shift(); //  1
//  Array 'a' is affected as well: [[], [2], [3]]

This Stack Overflow query offers good explanations for the above example, but the important point is that when using nested objects, we can’t just use the spread syntax to update the state object. For example, consider the following state object:

const [messageObj, setMessage] = useState({
  author: '',
  message: {
    id: 1,
    text: ''
  }
});

The following code snippets show some incorrect ways to update the text field:

// Wrong
setMessage(prevState => ({
  ...prevState,
  text: 'My message'
}));

// Wrong
setMessage(prevState => ({
  ...prevState.message,
  text: 'My message'
}));

// Wrong
setMessage(prevState => ({
  ...prevState,
  message: {
    text: 'My message'
  }
}));

To properly update the text field, we have to copy to a new object the entire set of fields/nested objects of the original object:

// Correct
setMessage(prevState => ({
  ...prevState,           // copy all other field/objects
  message: {              // recreate the object that contains the field to update
    ...prevState.message, // copy all the fields of the object
    text: 'My message'    // overwrite the value of the field to update
  }
}));

In the same way, here’s how you’d update the author field of the state object:

// Correct
setMessage(prevState => ({
  author: 'Joe',          // overwrite the value of the field to update
  ...prevState.message    // copy all other field/objects
}));

However, this is assuming the message object doesn’t change. If it does change, you’d have to update the object this way:

// Correct
setMessage(prevState => ({
  author: 'Joe',          // update the value of the field
  message: {              // recreate the object that contains the field to update
    ...prevState.message, // copy all the fields of the object
    text: 'My message'    // overwrite the value of the field to update
  }
}));

Working with multiple state variables or one state object

When working with multiple fields or values as the state of your application, you have the option of organizing the state using multiple state variables:

const [id, setId] = useState(-1);
const [message, setMessage] = useState('');
const [author, setAuthor] = useState('');
Or an object state variable:
const [messageObj, setMessage] = useState({ 
  id: 1, 
  message: '', 
  author: '' 
});

However, you have to be careful when using state objects with a complex structure (nested objects). Consider this example:

const [messageObj, setMessage] = useState({
  input: {
    author: {
      id: -1,
      author: {
        fName:'',
        lName: ''
      }
    },
    message: {
      id: -1,
      text: '',
      date: now()
    }
  }
});

If you have to update a specific field nested deep in the object, you’ll have to copy all the other objects along with the key-value pairs of the object that contains that specific field:

setMessage(prevState => ({
  input: {
    ...prevState.input,
    message: {
      ...prevState.input.message, 
      text: 'My message'
    }
  }
}));

In some cases, cloning deeply nested objects can be expensive because React may re-render parts of your applications that depend on fields that haven’t even changed.

For this reason, the first thing you need to consider is trying to flatten your state object(s). In particular, the React documentation recommends splitting the state into multiple state variables based on which values tend to change together.

If this is not possible, the recommendation is to use libraries that help you work with immutable objects, such as immutable.js or immer.

Rules for using useState

useState abides by the same rules that all Hooks follow:

• Only call Hooks at the top level
• Only call Hooks from React functions

The second rule is easy to follow. Don’t use useState in a class component:

class App extends React.Component {
  render() {
    const [message, setMessage] = useState( '' );

    return (
      <p>
        <strong>{message}</strong>
      </p>
    );
  }
}

Or regular JavaScript functions (not called inside a functional component):

function getState() {
  const messageState = useState( '' );
  return messageState;
}
const [message, setMessage] = getState();
const Message = () => {
 /* ... */
}

You’ll get an error. The first rule means that even inside functional components, you shouldn’t call useState in loops, conditions, or nested functions because React relies on the order in which useState functions are called to get the correct value for a particular state variable.

In that regard, the most common mistake is to wrap useState calls in a conditional statement (they won’t be executed all the time):

if (condition) { // Sometimes it will be executed, making the order of the useState calls change
  const [message, setMessage] = useState( '' );
  setMessage( aMessage );  
}
const [list, setList] = useState( [] );
setList( [1, 2, 3] );

A functional component can have many calls to useState or other Hooks. Each Hook is stored in a list, and there’s a variable that keeps track of the currently executed Hook.

When useState is executed, the state of the current Hook is read (or initialized during the first render), and then, the variable is changed to point to the next Hook. That’s why it is important to always maintain the Hook calls in the same order. Otherwise, a value belonging to another state variable could be returned.

In general terms, here’s an example of how this works step by step:

1. React initializes the list of Hooks and the variable that keeps track of the current Hook
2. React calls your component for the first time
3. React finds a call to useState, creates a new Hook object (with the initial state), changes the current Hook variable to point to this object, adds the object to the Hooks list, and returns the array with the initial state and the function to update it
4. React finds another call to useState and repeats the actions of the previous step, storing a new Hook object and changing the current Hook variable
5. The component state changes
6. React sends the state update operation (performed by the function returned by useState) to a queue to be processed
7. React determines it needs to re-render the component
8. React resets the current Hook variable and calls your component
9. React finds a call to useState, but this time, since there’s already a Hook at the first position of the list of Hooks, it just changes the current Hook variable and returns the array with the current state, and the function to update it
10. React finds another call to useState and because a Hook exists in the second position, once again, it just changes the current Hook variable and returns the array with the current state and the function to update it

If you like to read code, refer to the ReactFiberHooks class to learn how Hooks work under the hood.

useState vs. useEffect

useState and useEffect are two of the most important Hooks in React. They allow you to manage state and side effects in your functional components. However, they serve different purposes and should be used in different ways.

As we discussed earlier, the useState is a Hook that allows you to add state to your functional component. It returns an array with two values: the current state and a setter function for updating the state.

useEffect is a Hook that is used to manage side effects in functional components. A side-effect is any operation that impacts the component outside of its render, such as making an API call or setting up a timer. For example, consider a component that fetches data from an API and displays it in a list:

const [data, setData] = useState([]);

useEffect(() => {
  fetch('https://api.example.com/data')
    .then(res => res.json())
    .then(data => setData(data));
}, []);

return (
  <ul>
    {data.map(item => (
      <li key={item.id}>{item.name}</li>
    ))}
  </ul>
);

In this example, the useEffect Hook is used to make an API call and update the data state whenever the component is rendered. The Hook takes a callback function as an argument, which will be executed after every render of the component. The second argument to useEffect is an array of dependencies, which determines when the effect should run. In this case, the empty array means that the effect will only run once when the component is mounted.

useState is used for managing state that needs to be updated and re-rendered based on user interactions or other events in the component. On the other hand, useEffect is used to manage side effects that need to run after every render of the component or perform any cleanup when the component unmounts. Understanding the differences between these Hooks allows you to make informed decisions about when to use each Hook and build robust and scalable React applications.

Understanding the useReducer Hook

For advanced use cases, you can use the useReducer Hook as an alternative to useState. This is especially useful when you have complex state logic that uses multiple sub-values or when a state depends on the previous one.

Here’s how to use the useReducer Hook:

const [state, dispatch] = useReducer(reducer, initialArgument, init)

useReducer returns an array that holds the current state value and a dispatch method. This should be familiar territory if you have experience using Redux. Whereas with useState, you invoke the state updater function to update state, with useReducer, you invoke the dispatch function and pass it an action. For example, an object with at least a type property, like this one:

dispatch({type: 'increase'})

Conventionally, an action object may also have a payload, for example, {action: 'increase', payload: 10}. While it’s not absolutely necessary to pass an action object that follows this pattern, it’s a very common pattern popularized by Redux.

Conclusion

useState is a Hook that allows you to have state variables in functional components. You pass the initial state to this function, and it returns a variable with the current state value (not necessarily the initial state) and another function to update this value.

Here are some important key points to remember:

• The update function doesn’t update the value right away
• If you use the previous value to update state, you must pass a function that receives the previous value and returns an updated value, for example, setMessage(previousVal => previousVal + currentVal)
• If you use the same value as the current state to update the state, React won’t trigger a re-render
• Unlike this.setState in class components, useState doesn’t merge objects when the state is updated. It replaces them
• useState follows the same rules that all Hooks do. In particular, pay attention to the order in which these functions are called (there’s an ESLint plugin that will help you enforce these rules)