New in 18: useDeferredValue

[acdlite]

New in 18: useDeferredValue

const deferredValue = useDeferredValue(value);

When the value passed to useDeferredValue changes, it will either return the previous value or the new value depending on the priority of the current render.

You can think of "deferring" a value as similar to throttling or debouncing it.

If the current render is the result of an urgent update, like a user input, React will return the previous value. Then, it will switch to the new value after the current render has completed.

The deferred value has the same priority as updates scheduled by startTransition. Like startTransition updates, deferred values can suspend without triggering an unexpected fallback.

useDeferredValue and startTransition have broadly the same behavior. The difference lies mostly in where the API is applied:

• startTransition is used when triggering an update (i.e. setState) in an event handler.
• useDeferredValue is used when receiving new data from a parent component (or an earlier hook in the same component).

To illustrate, take this example of a typeahead component:

function Typeahead() {
  // The current query is controlled by some state that we don't control. It 
  // may even be managed by an external store.
  const query = useSearchQuery('');

  // We don't need the suggestions to update immediately. We should keep showing
  // the previous results until the new ones load.
  const deferredQuery = useDeferredValue(query);

  return (
    <>
      {/* The search input updates immediately */}
      <SearchInput query={query} />
      {/* The suggestions update in a later frame */}
      <Suspense fallback="Loading results...">
        <SearchSuggestions query={deferredQuery} />
      </Suspense>
    </>
  );
}

In this example, query is a prop that's passed down from a parent component. We can't wrap the query update in startTransition, since we don't control the event that changes it. There may even be multiple events — maybe the app listens both for input events and or a change to the URL. Or maybe the state is controlled by an external store.

Memoize children to prevent re-renders during urgent updates

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 memo or useMemo:

function Typeahead() {
  const query = useSearchQuery('');
  const deferredQuery = useDeferredValue(query);

  // Memoizing tells React to only re-render when deferredQuery changes — not
  // when query changes.
  const suggestions = useMemo(() =>
    <SearchSuggestions query={deferredQuery} />,
    [deferredQuery]
  );

  return (
    <>
      <SearchInput query={query} />
      <Suspense fallback="Loading results...">
        {suggestions}
      </Suspense>
    </>
  );
}

Memoizing the children tells React that it only needs to re-render them when deferredQuery changes. They do not need to re-render when query changes.

This is caveat is not unique to useDeferredValue, and it's the same pattern you would use with similar hooks like useThrottleValue or useDebouncedValue.

[Andarist]

deferred values can suspend without triggering an unexpected fallback.

Could you expand on this? Does it mean that in a future render SearchSuggestions could suspend somehow without displaying the fallback component? What would be the trigger for suspending here (I assume that this would be about SearchSuggestions finally seeing a new value of the prop)? And how Suspense would know that it can skip the fallback UI and continue displaying the old one here?

[gaearon]

You can think of useDeferredValue as scheduling two renders:

• Urgent render with the previous value
• Non-urgent render with next value (similar to what startTransition does)
  • Since this one isn't urgent, React prevents fallbacks from showing for "existing" Suspense boundaries. This is similar to how startTransition prevents fallbacks from showing.

Does this help?

What would be the trigger for suspending here (I assume that this would be about SearchSuggestions finally seeing a new value of the prop)?

Yes.

[Andarist]

Yeah! If the logic for suspending is already backed into useDeferredValue then it makes sense. I didn't realize this and I've thought that this stuff is only handled within the Suspense boundary, but here it seems that we can "affect" the mechanism somewhat from the outside of it.

[gaearon]

@Andarist I don't think I understand what "the logic for suspending is already backed into useDeferredValue" means. This might mean we have different mental models of what's happening, or how features are related. It doesn't necessarily mean yours is wrong but it might be interesting to revisit the assumptions and see if it diverges somewhere! Let me try to illustrate with an example and maybe this helps finds the divergence. I'm using an example based on @diegohaz React Conf talk.

Here, the example does not do useDeferredValue:
https://codesandbox.io/s/priceless-cannon-yhbqce?file=/src/App.js
As you can see, when you type into the input, the combobox results constantly turn into "Loading..." and then back into results.

This version does useDeferredValue:
https://codesandbox.io/s/romantic-tharp-wedx58?file=/src/App.js
When you type into the input, the previous combobox results are dimmed out while we're refetching.

From the user perspective, the difference is less flicker. From the developer perspective, the difference is that one line.

---

Now how does this work? My mental model goes like this:

Say initially combobox.value is "darth", and we've changed it to "obi".

• The user types, so a state variable inside the useCombobox Hook updates.
  • This triggers an urgent re-render where combobox.value is "obi".
  • In that urgent render, useDeferredValue(combobox.value) will return the already committed value. Similar to how Hooks like useDebouncedValue() do. So it still returns "darth" even though combobox.value is "obi".
    • React remembers that this deferred value will need to transition to "obi" in a later render.
  • React renders <Results query="darth" />. The container has 0.5 opacity because we set opacity based on whether deferredValue === value, which is false.
  • This urgent render is committed.
• Now React has nothing better to do, so it works on the deferred update.
  • In this non-urgent render, useDeferredValue(combobox.value) will return the new value. So it returns "obi".
  • React renders <Results query="obi" />.
    • Too bad! We don't have results for that yet. This suspends.
    • Suspending an already shown <Suspense> boundary in an urgent render would have caused us to commit a fallback. But that would be a poor user experience. (It's annoying when existing content disappears before your eyes.) Luckily, we're in a non-urgent render, which means React has the freedom to simply discard it.
    • React discards this render completely.
• Finally, the Promise pings, so React is ready to retry.
  • In this non-urgent render, useDeferredValue(combobox.value) will return the new value. So it returns "obi".
  • We have that data now!
  • React renders <Results query="obi" />.
  • React commits the result.

Does this match your intuition?

[Andarist]

Does this match your intuition?

Yes, although perhaps the wording that I've used was inaccurate and confusing. It's like that deferred render is being marked internally differently (at least for that part of the tree) and thus it allows React to handle Suspense magic differently.

Thanks for backing this with a detailed example - it's top-notch and yet another example of how well you can break down concepts for people. ❤️

[gaearon]

Yeah, you can think of the deferred render as being marked as a transition. They’re not technically exactly the same (we might introduce some differences in semantics) but in the today’s implementation, useDV is just a useState + a transition setState inside an effect that syncs it to the latest received value. Again, this is just a current implementation detail, but it helped me gain the mental model for it initially.