New in 18: useEffect fires synchronously when it's the result of a discrete input

[acdlite]

In React 18, useEffect fires synchronously when it's the result of a discrete input.

For example, if useEffect attaches an event listener, the listener is guaranteed to be added before the next input.

The same behavior applies to flushSync: the results of the effect are applied immediately, before the flushSync call exits.

The behavior for non-discrete events is unchanged: in most cases, React will defer the effect until after paint (though not always, if there's remaining time in the frame).

Note that this only affects the timing of when useEffect functions are called. It does not affect the priority of updates that are triggered inside a useEffect. They still get the default priority. (This is in contrast to useLayoutEffect, which not only calls the effect callback synchronously but also gives synchronous priority to its updates.)

Background

A discrete input is a type of event where the result of one event can affect the behavior of the next, like clicks or presses. Multiple discrete events cannot be batched or throttled without affecting program behavior.

A practical example where this matters is a counter. If the user increments a counter multiple times in quick succession, we must process each one individually so that the final count is correct.

In React 17 and below, the function passed to useEffect typically fires asynchronously after the browser has painted. The idea is to defer as much work as possible until paint so that the user experience is not delayed. This includes things like setting up subscriptions.

However, although passive effects do not block the browser from painting, they need to fire before the next discrete input event, so that the result can be observed by the event system.

For example, imagine you're building a form that disables "submit" after the first submission:

useEffect(() => {
  if (!disableSubmit) {
    const form = formRef.current;
    form.addEventListener('submit', onSubmit);
    return () => {
      form.removeEventListener('submit', onSubmit);
    };
  }
}, [disableSubmit, onSubmit]);

If the user attempts to submit the form multiple times in quick succession, we need to make sure the effects from the first event have completely finished before the next input is processed. So we synchronously flush them.

We don't need to do this for events that aren't discrete, because we assume they are not order-dependent and do not need to be observed by external systems.

[devknoll]

Dumb question. Could you argue that in any case where you need this guarantee:

the listener is guaranteed to be added before the next input

...you should just be using useLayoutEffect instead? With this change, does React guarantee that all pending useEffects will be called before handling a discrete event, or is there still a chance that you have a useEffect that sets up a DOM listener that won't be called by time the event you're trying to attach to fires?

Or in other words, what happens if you somehow manage to submit the form before this useEffect is first called?

[acdlite]

It kind of seems like interacting with the DOM in useEffect might generally have hidden footguns...

You shouldn't do anything that affects the visible UI, like applying DOM mutations. Those should go in useLayoutEffect or useInsertionEffect.

Attaching event listeners is fine, though.

It's true there are some footguns, the whole point of this change is to make those footguns less likely.

[acdlite]

Right, but is it that A.) updates triggered as a result of the discrete event will be synchronous or B.) all queued work will be completed synchronously before handling a discrete event?

Good call out — the effects fire synchronously in this case, but the priority of the updates scheduled by those effects is unchanged. That's one of the differences compared to if you scheduled the update with useLayoutEffect instead, and the reason useEffect is preferred.

[acdlite]

I added a note about that to the description

[devknoll]

What will happen if you trigger a discrete event on a dehydrated component? Normally, React would try to synchronously hydrate those components, right?

Does that include synchronously applying useEffects, or will those still be deferred?

[acdlite]

It's the same: any effect triggered by an update triggered by a discrete event will be called synchronously when the render commits.