Skip to content

Commit d14cbdc

Browse files
authored
Add more details on batching (#4559)
* Add more details on batching * Use a generic example
1 parent 1015a73 commit d14cbdc

File tree

3 files changed

+19
-3
lines changed

3 files changed

+19
-3
lines changed

content/docs/hooks-reference.md

+8
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,14 @@ If you update a State Hook to the same value as the current state, React will ba
108108

109109
Note that React may still need to render that specific component again before bailing out. That shouldn't be a concern because React won't unnecessarily go "deeper" into the tree. If you're doing expensive calculations while rendering, you can optimize them with `useMemo`.
110110

111+
#### Batching of state updates {#batching-of-state-updates}
112+
113+
React may group several state updates into a single re-render to improve performance. Normally, this improves performance and shouldn't affect your application's behavior.
114+
115+
Before React 18, only updates inside React event handlers were batched. Starting with React 18, [batching is enabled for all updates by default](/blog/2022/03/08/react-18-upgrade-guide.html#automatic-batching). Note that React makes sure that updates from several *different* user-initiated events -- for example, clicking a button twice -- are always processed separately and do not get batched. This prevents logical mistakes.
116+
117+
In the rare case that you need to force the DOM update to be applied synchronously, you may wrap it in [`flushSync`](/docs/react-dom.html#flushsync). However, this can hurt performance so do this only where needed.
118+
111119
### `useEffect` {#useeffect}
112120

113121
```js

content/docs/reference-react-component.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -512,7 +512,7 @@ setState(updater, [callback])
512512

513513
`setState()` enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state. This is the primary method you use to update the user interface in response to event handlers and server responses.
514514

515-
Think of `setState()` as a *request* rather than an immediate command to update the component. For better perceived performance, React may delay it, and then update several components in a single pass. React does not guarantee that the state changes are applied immediately.
515+
Think of `setState()` as a *request* rather than an immediate command to update the component. For better perceived performance, React may delay it, and then update several components in a single pass. In the rare case that you need to force the DOM update to be applied synchronously, you may wrap it in [`flushSync`](/docs/react-dom.html#flushsync), but this may hurt performance.
516516

517517
`setState()` does not always immediately update the component. It may batch or defer the update until later. This makes reading `this.state` right after calling `setState()` a potential pitfall. Instead, use `componentDidUpdate` or a `setState` callback (`setState(updater, callback)`), either of which are guaranteed to fire after the update has been applied. If you need to set the state based on the previous state, read about the `updater` argument below.
518518

content/docs/reference-react-dom.md

+10-2
Original file line numberDiff line numberDiff line change
@@ -62,11 +62,19 @@ Creates a portal. Portals provide a way to [render children into a DOM node that
6262
flushSync(callback)
6363
```
6464

65-
Force React to flush any updates inside the provided callback synchronously. This method is useful for being able to read the result of those updates immediately.
65+
Force React to flush any updates inside the provided callback synchronously. This ensures that the DOM is updated immediately.
66+
67+
```javascript
68+
// Force this state update to be synchronous.
69+
flushSync(() => {
70+
setCount(count + 1);
71+
});
72+
// By this point, DOM is updated.
73+
```
6674

6775
> Note:
6876
>
69-
> `flushSync` can have a significant impact on performance. Use sparingly.
77+
> `flushSync` can significantly hurt performance. Use sparingly.
7078
>
7179
> `flushSync` may force pending Suspense boundaries to show their `fallback` state.
7280
>

0 commit comments

Comments
 (0)