Add a note that useEffect is not guaranteed to run after paint

[thoughtspile]

useEffect docs suggest the effect always runs after paint, which is apparently not guaranteed. For example, when useLayoutEffect from the same render triggers an update, the effect must be flushed before that update, which is before paint (I wrote a post detailing this behavior). Folks in react/react#20863 discuss similar pitfalls.

Could we clarify the guarantees in the docs? I'd be glad to submit a PR if you confirm my understanding of the behavior.

[abacaj]

My question here to you would be in what case do you need both useEffect and useLayoutEffect in the same component?

From my experience, I've only ever needed one of those.

[thoughtspile]

in what case do you need both useEffect and useLayoutEffect in the same component?

All effects from an update are flushed globally, not broken up by components.

From my experience, I've only ever needed one of those.

Are you sure you've never had a custom hook, eg usePopper, that has useLayoutEffect inside?

[abacaj]

That is using useLayoutEffect and not mixing the two, my question is asking why do you use both in the same component i.e

useEffect(() => {}, []);
useLayoutEffect(() => {}, []);

Basically, what is the use case for you to mix the two? If you need to remove "flicker" you stick to useLayoutEffect since that is synchronous.

Otherwise the docs as I read them are correct https://reactjs.org/docs/hooks-reference.html#useeffect:

The function passed to useEffect will run after the render is committed to the screen. Think of effects as an escape hatch from React’s purely functional world into the imperative world.

I looked over your example in the blog post:

We’ve tried to delay addEventListener until after paint with useEffect, but the state update in useLayoutEffect forces it to happen before paint

This is actually correct behavior as far as I can tell:
https://kentcdodds.com/blog/useeffect-vs-uselayouteffect

Your code runs immediately after the DOM has been updated, but before the browser has had a chance to "paint" those changes (the user doesn't actually see the updates until after the browser has repainted).

If you want it to be after "paint", you need to remove the useLayoutEffect call and only use useEffect in that component.
If you want it to be before "paint", you need to use useLayoutEffect and remove useEffect in that component.

[thoughtspile]

Basically, what is the use case for you to mix the two?

Let me detail a bit:

1. Updating from useLayoutEffect flushes all effects from the same transaction, even the ones scheduled in other components (see sandbox).
2. There are other places where requesting an update forces the effects to flush early — requestAnimationFrame, microtasks, and possibly *Observer callbacks.
3. You can useEffect and usePopper (or any other custom hook) from the same component without knowing that usePopper calls useLayoutEffect under the hood.

Otherwise the docs as I read them are correct https://reactjs.org/docs/hooks-reference.html#useeffect:

Unlike componentDidMount and componentDidUpdate, the function passed to useEffect fires after layout and paint

This part is fine (it applies to uLE and cDM / cDU, too). The section on "Timing of effects" says that the function passed to useEffect fires after layout and paint and Although useEffect is deferred until after the browser has painted, suggesting it's a strong guarantee

We’ve tried to delay addEventListener until after paint with useEffect, but the state update in useLayoutEffect forces it to happen before paint

This is actually correct behavior:

Your code runs immediately after the DOM has been updated, but before the browser has had a chance to "paint" those changes (the user doesn't actually see the updates until after the browser has repainted).

Kent's passage refers to the layoutEffect callback, while useEffect should be delayed until after paint, see "Timing of effects" section in the official docs.

If you want it to be after "paint", you need to remove the useLayoutEffect call and only use useEffect in that component.
If you want it to be before "paint", you need to use useLayoutEffect and remove useEffect in that component.

Normally, useEffect and useLayoutEffect run independently. With custom hooks, you don't even know which kind of effect they use internally.

[abacaj]

1. Updating from useLayoutEffect flushes all effects from the same transaction, even the ones scheduled in other components (see sandbox).

What did you expect to happen in the example here? This is what I saw:

[thoughtspile]

What did you expect to happen in the example here?

If useLayoutEffect fires before paint, and useEffect fires after paint, the sequence should be layout effect > frame > effect. This is also what's logged if you remove the update({}).

[abacaj]

What did you expect to happen in the example here?

If useLayoutEffect fires before paint, and useEffect fires after paint, the sequence should be layout effect > frame > effect. This is also what's logged if you remove the update({}).

Makes sense, it seems the issue is tied to state updates in useLayoutEffect. I haven't had any weird performance/UI issues as of yet because of it. I assume many projects using react are running into this situation unknowingly.

[rickhanlonii]

The new docs include this info in the caveats: https://react.dev/reference/react/useEffect#caveats