Unveiling React’s setState: How It Works Internally and Common Pitfalls

Introduction

Developers familiar with React know that setState is crucial for updating component data. This article walks from simple usage to the inner workings of setState, revealing its hidden complexities.

setState Usage Tips

setState(updater, callback)

notifies React that the component’s state has changed and may need to re‑render. Because React batches multiple updates for performance, the state change is asynchronous. Consequently, reading this.state immediately after calling setState often returns the old value.

Tip 1

If you need to act on the latest state, use componentDidUpdate or the setState callback (the official recommendation is the former).

// setState callback example
changeTitle: function(event) {
  this.setState({ title: event.target.value }, () => {
    this.APICallFunction();
  });
}

Tip 2

When a state update depends on the previous state, pass a function to setState instead of an object.

onClick = () => {
  this.setState(prevState => ({ quantity: prevState.quantity + 1 }));
}

Directly setting the state twice in the same event results in only the last change taking effect because the second update overwrites the first. Using a functional updater ensures each update receives the latest state.

How setState Works Internally

1. setState (ReactBaseClasses.js)

ReactComponent.prototype.setState = function(partialState, callback) {
  // enqueue the state update
  this.updater.enqueueSetState(this, partialState);
  if (callback) {
    this.updater.enqueueCallback(this, callback, 'setState');
  }
};

The partialState can be an object or a function. React merges it with the current state using Object.assign.

2. enqueueSetState (ReactUpdates.js)

function enqueueSetState(publicInstance, partialState) {
  var internalInstance = getInternalInstanceReadyForUpdate(publicInstance, 'setState');
  var queue = internalInstance._pendingStateQueue || (internalInstance._pendingStateQueue = []);
  queue.push(partialState);
  enqueueUpdate(internalInstance);
}

This function adds the new state to a pending queue and then calls enqueueUpdate to schedule the component for later processing.

3. enqueueUpdate (ReactUpdates.js)

function enqueueUpdate(component) {
  if (!batchingStrategy.isBatchingUpdates) {
    batchingStrategy.batchedUpdates(enqueueUpdate, component);
    return;
  }
  dirtyComponents.push(component);
}

If React is not currently batching updates, it immediately starts a batch; otherwise, the component is placed in dirtyComponents to be updated later.

4. Batching Strategy (ReactDefaultBatchingStrategy.js)

var ReactDefaultBatchingStrategy = {
  isBatchingUpdates: false,
  batchedUpdates: function(callback, a, b, c, d, e) {
    var alreadyBatchingUpdates = this.isBatchingUpdates;
    this.isBatchingUpdates = true;
    if (alreadyBatchingUpdates) {
      return callback(a, b, c, d, e);
    }
    transaction.perform(callback, null, a, b, c, d, e);
  }
};

When a batch is active, new updates are simply queued. When the batch finishes, a transaction runs all wrappers, flushing the queued updates.

5. Transaction (ReactUpdates.js)

A transaction provides a perform method that runs a callback surrounded by wrapper initialize and close steps. The two wrappers used by the default batching strategy are: FLUSH_BATCHED_UPDATES: calls ReactUpdates.flushBatchedUpdates after the callback. RESET_BATCHED_UPDATES: resets isBatchingUpdates to false.

During flushBatchedUpdates, React iterates over dirtyComponents and runs the full update lifecycle (e.g., componentWillReceiveProps, shouldComponentUpdate, render, componentDidUpdate).

Visual Summary

The diagram above illustrates the complete flow from calling setState to the final component re‑render.

References:

Original article (Chinese)