From 4a6739aa1ca6914b734a2d149f13cc2564fa0828 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Sun, 27 Mar 2022 14:53:43 -0400
Subject: [PATCH] [18] Update docs for useEffect timing
---
content/docs/hooks-reference.md | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md
index f5825faf648..0244f99ce84 100644
--- a/content/docs/hooks-reference.md
+++ b/content/docs/hooks-reference.md
@@ -144,7 +144,13 @@ Unlike `componentDidMount` and `componentDidUpdate`, the function passed to `use
However, not all effects can be deferred. For example, a DOM mutation that is visible to the user must fire synchronously before the next paint so that the user does not perceive a visual inconsistency. (The distinction is conceptually similar to passive versus active event listeners.) For these types of effects, React provides one additional Hook called [`useLayoutEffect`](#uselayouteffect). It has the same signature as `useEffect`, and only differs in when it is fired.
-Although `useEffect` is deferred until after the browser has painted, it's guaranteed to fire before any new renders. React will always flush a previous render's effects before starting a new update.
+Additionally, starting in React 18, the function passed to `useEffect` will fire synchronously **before** layout and paint when it's the result of a discrete user input such as a click, or when it's the result of an update wrapped in [`flushSync`](/docs/react-dom.html#flushsync). This behavior allows the result of the effect to be observed by the event system, or by the caller of [`flushSync`](/docs/react-dom.html#flushsync).
+
+> Note
+>
+> This only affects the timing of when the function passed to `useEffect` is called - updates scheduled inside these effects are still deferred. This is different than [`useLayoutEffect`](#uselayouteffect), which fires the function and processes the updates inside of it immediately.
+
+Even in cases where `useEffect` is deferred until after the browser has painted, it's guaranteed to fire before any new renders. React will always flush a previous render's effects before starting a new update.
#### Conditionally firing an effect {#conditionally-firing-an-effect}