amirho/react.dev
1
0
Fork 0
mirror of https://github.com/reactjs/react.dev.git synced 2026-02-23 20:23:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

API docs for useDeferredValue's initialValue (#6747)

Browse Source 
* 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 <rickhanlonii@fb.com>
This commit is contained in:
Andrew Clark
2024-04-22 10:45:08 -04:00
committed by GitHub
parent 37a8d646bf
commit 07cbd001f9
1 changed files with 12 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
src/content/reference/react/useDeferredValue.md
View File

@@ -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.
* <CanaryBadge title="This feature is only available in the Canary channel" /> **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).
<Canary>
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.
</Canary>
#### 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.