Skip to content

Commit 7d261d4

Browse files
authored
[18] Add docs for useDeferredValue (#4497)
1 parent b0ea4a8 commit 7d261d4

File tree

1 file changed

+31
-1
lines changed

1 file changed

+31
-1
lines changed

content/docs/hooks-reference.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -527,7 +527,37 @@ useDebugValue(date, date => date.toDateString());
527527
const [deferredValue] = useDeferredValue(value);
528528
```
529529

530-
TODO: description
530+
`useDeferredValue` accepts a value and returns a new copy of the value that will defer to more urgent updates. If the current render is the result of an urgent update, like user input, React will return the previous value and then render the new value after the urgent render has completed.
531+
532+
This hook is similar to user-space hooks which use debouncing or throttling to defer updates. The benefits to using `useDeferredValue` is that React will work on the update as soon as other work finishes (instead of waiting for an arbitrary amount of time), and like [`startTransition`](/docs/react-api.html#starttransition), deferred values can suspend without triggering an unexpected fallback for existing content.
533+
534+
#### Memoizing deferred children
535+
`useDeferredValue` only defers the value that you pass to it. If you want to prevent a child component from re-rendering during an urgent update, you must also memoize that component with [`React.memo`](/docs/react-api.html#reactmemo) or [`React.useMemo`](/docs/hooks-reference.html#usememo):
536+
537+
```js
538+
function Typeahead() {
539+
const query = useSearchQuery('');
540+
const deferredQuery = useDeferredValue(query);
541+
542+
// Memoizing tells React to only re-render when deferredQuery changes,
543+
// not when query changes.
544+
const suggestions = useMemo(() =>
545+
<SearchSuggestions query={deferredQuery} />,
546+
[deferredQuery]
547+
);
548+
549+
return (
550+
<>
551+
<SearchInput query={query} />
552+
<Suspense fallback="Loading results...">
553+
{suggestions}
554+
</Suspense>
555+
</>
556+
);
557+
}
558+
```
559+
560+
Memoizing the children tells React that it only needs to re-render them when `deferredQuery` changes and not when `query` changes. This caveat is not unique to `useDeferredValue`, and it's the same pattern you would use with similar hooks that use debouncing or throttling.
531561

532562
### `useTransition` {#usetransition}
533563

0 commit comments

Comments
 (0)