React - What does the callback in forceUpdate do?

Question

In React docs, forceUpdate has a parameter callback.

Is that like setState's second parameter which is called after setting a state? Or what is that for?

I can't find any articles about that.

Answer 1

Is it like setState's second parameter which is called after setting a state?

Yes it is. The answer is on react source code. If you look at react/src/ReactBaseClasses you will see that setState and forceUpdate are defined like:

Component.prototype.setState = function(partialState, callback) {
  // ...
  this.updater.enqueueSetState(this, partialState, callback, 'setState');
};

Component.prototype.forceUpdate = function(callback) {
  this.updater.enqueueForceUpdate(this, callback, 'forceUpdate');
};

And if we go on enqueueSetState and enqueueForceUpdate implementation, we will see that:

const classComponentUpdater = {
  isMounted,
  enqueueSetState(inst, payload, callback) {
    const fiber = getInstance(inst);
    const currentTime = requestCurrentTimeForUpdate();
    const suspenseConfig = requestCurrentSuspenseConfig();
    const expirationTime = computeExpirationForFiber(
      currentTime,
      fiber,
      suspenseConfig,
    );

    const update = createUpdate(expirationTime, suspenseConfig);
    update.payload = payload;
    if (callback !== undefined && callback !== null) {
      // ...
      update.callback = callback;
    }

    enqueueUpdate(fiber, update);
    scheduleWork(fiber, expirationTime);
  },
  enqueueReplaceState(inst, payload, callback) {
    ...
  },
  enqueueForceUpdate(inst, callback) {
    const fiber = getInstance(inst);
    const currentTime = requestCurrentTimeForUpdate();
    const suspenseConfig = requestCurrentSuspenseConfig();
    const expirationTime = computeExpirationForFiber(
      currentTime,
      fiber,
      suspenseConfig,
    );

    const update = createUpdate(expirationTime, suspenseConfig);
    update.tag = ForceUpdate;

    if (callback !== undefined && callback !== null) {
      // ...
      update.callback = callback;
    }

    enqueueUpdate(fiber, update);
    scheduleWork(fiber, expirationTime);
  },
};

The differences between enqueueSetState and enqueueForceUpdate are in update.payload and update.tag.

So yes, the forceUpdate callBack has the same behaviour of setState's second parameter.

Answer 2

Is it like setState's second parameter which is called after setting a state?

The short answer here is: Yes, the forceUpdate() method takes the same optional argument callback, which is of type Function, as the setState() method (see ReactBaseClasses implementation).

In the case of forceUpdate() the callback will be called after the update, whereas for the setState() method the callback is called after the state is updated. The notable difference here is that the forceUpdate() method calls the enqueueForceUpdate() method, whereas setState() uses the enqueueSetState() method.

As Giovanni outlined in his answer, the update.tag is set to ForceUpdate inside the enqueueForceUpdate() method. However, the update.tag value is set to UpdateState by default in the createUpdate() method. As the ForceUpdate tag has a higher value (i.e. 2), it has a higher priority than UpdateState (i.e. 0).

Here are the implementation details for createUpdate(), UpdateState as well as ForceUpdate (see ReactUpdateQueue.new):

...
export const UpdateState = 0;
export const ReplaceState = 1;
export const ForceUpdate = 2;
export const CaptureUpdate = 3;
...
export function createUpdate(eventTime: number, lane: Lane): Update<*> {
    const update: Update<*> = {
            eventTime,
            lane,

            tag: UpdateState,
            payload: null,
            callback: null,

            next: null,
    };
    return update;
}