From 07cbd001f936c22f731e5741e9853ffcdfb3fedd Mon Sep 17 00:00:00 2001 From: Andrew Clark Date: Mon, 22 Apr 2024 10:45:08 -0400 Subject: [PATCH] API docs for useDeferredValue's initialValue (#6747) * API docs for useDeferredValue's initialValue Updates the API docs for `useDeferredValue` to include the `initialValue` option, added in https://github.com/facebook/react/pull/27500. This feature is slated for release in React 19. * Add docs for onCaughtError and onUncaughtError (#6742) * Add docs for onCaughtError and onUncaughtError * Updates from feedback * Add canary info, simplify a bit --------- Co-authored-by: Ricky --- src/content/reference/react/useDeferredValue.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/content/reference/react/useDeferredValue.md b/src/content/reference/react/useDeferredValue.md index f97bf0a281a..6d055f1f984 100644 --- a/src/content/reference/react/useDeferredValue.md +++ b/src/content/reference/react/useDeferredValue.md @@ -18,7 +18,7 @@ const deferredValue = useDeferredValue(value) ## Reference {/*reference*/} -### `useDeferredValue(value)` {/*usedeferredvalue*/} +### `useDeferredValue(value, initialValue?)` {/*usedeferredvalue*/} Call `useDeferredValue` at the top level of your component to get a deferred version of that value. @@ -37,13 +37,23 @@ function SearchPage() { #### Parameters {/*parameters*/} * `value`: The value you want to defer. It can have any type. +* **optional** `initialValue`: A value to use during the initial render of a component. If this option is omitted, `useDeferredValue` will not defer during the initial render, because there's no previous version of `value` that it can render instead. + #### Returns {/*returns*/} -During the initial render, the returned deferred value will be the same as the value you provided. During updates, React will first attempt a re-render with the old value (so it will return the old value), and then try another re-render in the background with the new value (so it will return the updated value). +- `currentValue`: During the initial render, the returned deferred value will be the same as the value you provided. During updates, React will first attempt a re-render with the old value (so it will return the old value), and then try another re-render in the background with the new value (so it will return the updated value). + + + +In the latest React Canary versions, `useDeferredValue` returns the `initialValue` on initial render, and schedules a re-render in the background with the `value` returned. + + #### Caveats {/*caveats*/} +- When an update is inside a Transition, `useDeferredValue` always returns the new `value` and does not spawn a deferred render, since the update is already deferred. + - The values you pass to `useDeferredValue` should either be primitive values (like strings and numbers) or objects created outside of rendering. If you create a new object during rendering and immediately pass it to `useDeferredValue`, it will be different on every render, causing unnecessary background re-renders. - When `useDeferredValue` receives a different value (compared with [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)), in addition to the current render (when it still uses the previous value), it schedules a re-render in the background with the new value. The background re-render is interruptible: if there's another update to the `value`, React will restart the background re-render from scratch. For example, if the user is typing into an input faster than a chart receiving its deferred value can re-render, the chart will only re-render after the user stops typing.