[18] Add docs for flushSync #4474
Conversation
content/docs/reference-react-dom.md
Outdated
| flushSync(callback) | ||
| ``` | ||
|
|
||
| Force React to flush updates synchronously. This method is useful for being able to read the value of `state` immediately. |
There was a problem hiding this comment.
This a bit misleading since the easiest way to read the value of state immediately is just read what you set it to. I don't think we should encourage this as a workaround for that.
It's more about reading the outcomes. Almost always from the DOM.
It could use an explanation what the purpose of the callback is since callbacks are typically associated with async operation completing, which this by definition is not.
It's meant to form a grouping of any setStates that you need to flush synchronously.
There was a problem hiding this comment.
Makes sense, I was being a little value about the callback because it's not necessarily only the updates passed in that are flushed, correct? I.e. just calling flushSync() without a callback will flush work?
There was a problem hiding this comment.
Yea, if you happen to know that they're also scheduled in the sync lane. You can force any pending discrete ones to flush.
However, it's a little sketchy to assume that the context you're executing within is already discrete so adding more setStates before it might not be a good idea. Since you could've been wrapped in a startTransition.
// Reasonable if that's your use case
flushSync();// Bad
setState(true);
flushSync();// Good
flushSync(() => setState(true));There was a problem hiding this comment.
I'm trying to avoid explaining discrete updates since we haven't really explained it elsewhere, how about a note like:
flushSyncmay also flush updates outside of the callback when necessary to flush the updates provided. For example, if there are pending updates from aclick, React may flush those before flushing the updates inside thecallback.
There was a problem hiding this comment.
Sounds good but that part might even need explanation.
The important part is that you put the updates you want to do inside the function.
content/docs/reference-react-dom.md
Outdated
| > | ||
| > `flushSync` can have a significant impact on performance. Use sparingly. | ||
| > | ||
| > `flushSync` will force Suspense boundaries to show their `fallback` state. |
There was a problem hiding this comment.
*can ... if they're still loading.
* [18] Add flushSync to ReactDOM docs * Seb feedback * More Seb feedback
* [18] ReactDOM reference to createRoot/hydrateRoot (#4340) * [18] ReactDOM reference to createRoot/hydrateRoot * Update note about render and hydrate * Match the warning text * s/Render/render * [18] Update ReactDOMClient docs (#4468) * [18] Update ReactDOMClient docs * Remove ReactDOMClient where it's obvious * Update browser message * Update browser message note * Update based on feedback * Add react-dom/client docs * [18] Upgrade homepage examples (#4469) * [18] Switch code samples to createRoot (#4470) * [18] Switch code samples to createRoot * Feedback fixes * Feedback updates * [18] Use hydrateRoot and root.unmount. (#4473) * [18] Add docs for flushSync (#4474) * [18] Add flushSync to ReactDOM docs * Seb feedback * More Seb feedback * [18] Bump version to 18 (#4478) * [18] Update browser requirements (#4476) * [18] Update browser requirements * Update based on feedback * [18] Add stubs for new API references (#4477) * [18] Add stubs for new API references * Change order/grouping * [18] Redirect outdated Concurrent Mode docs (#4481) * [18] Redirect outdated Concurrent Mode docs * Use Vercel redirects instead * [18] Update versions page (#4482) * [18] Update version page * Fix prettier * [18] Update React.lazy docs (#4483) * [18] Add docs for useSyncExternalStore (#4487) * [18] Add docs for useSyncExternalStore * rm "optional" * [18] Add docs for useInsertionEffect (#4486) * [18] Add docs for useId (#4488) * [18] Add docs for useId * Update based on feedback * Add Strict Effects to Strict Mode (#4362) * Add Strict Effects to Strict Mode * Update with new thinking * [18] Update docs for useEffect timing (#4498) * [18] Add docs for useDeferredValue (#4497) * [18] Update suspense docs for unexpected fallbacks (#4500) * [18] Update suspense docs for unexpected fallbacks * Add inline code block * Feedback fixes * [18] Updated Suspense doc with behavior during SSR and Hydration (#4484) * update wording * wording * update events * Update content/docs/reference-react.md Co-authored-by: Sebastian Silbermann <silbermann.sebastian@gmail.com> * add link to selective hydration * remove some of the implementation details Co-authored-by: Sebastian Silbermann <silbermann.sebastian@gmail.com> * [18] renderToPipeableStream doc (#4485) * new streaming ssr api * add readable stream * code snippets * Rename strict effects / unsafe effects to use the reusable state terminology (#4505) * Add draft of 18 release post * Add links to speaker Twitter profiles * [18] Update upgrade guide * Fix typo in blog title * [18] Blog - add note for react native * [18] Add changelog info to blog posts * Edit Suspense for data fetching section * Update date * [18] Add links * Consistent title case * Update link to merged RFC * [18] Update APIs and links * [18] Add start/useTransition docs (#4479) * [18] Add start/useTransition docs * Updates based on feedback * [18] Generate heading IDs * Add note about Strict Mode * Just frameworks * Reorder, fix content * Typos * Clarify Suspense frameworks section * Revert lost changes that happened when I undo-ed in my editor Co-authored-by: salazarm <salazarm@users.noreply.github.com> Co-authored-by: Sebastian Silbermann <silbermann.sebastian@gmail.com> Co-authored-by: Sebastian Markbåge <sebastian@calyptus.eu> Co-authored-by: Andrew Clark <git@andrewclark.io> Co-authored-by: dan <dan.abramov@gmail.com>
Overview
I'm sure there's a lot more to say here. Opening as an MVP, feel free to suggest more content.