Skip to content

[Suggestion]: use hook missing explanations of handling promises created on the client #8290

Description

@MaxwellCohen

Summary

The use Hook documentation lacks caveats, examples, or troubleshooting for using the use Hook with a promise created on the client.

Page

https://react.dev/reference/react/use

Details

The current documentation for the use hook does not show how to use the use for client-created promises. When using the use Hook promsies need to be needs to be cached. This is not explicitly stated in the documentation, but it is implied by the "stable" promises. When not using a stable or cached promise, an infinite loop occurs, preventing the component from loading.

Adding the following information could help:

  1. Adding to the caveats section a caveat like:

A Promise used in Client Components use hooks must be cached or stable between renders (e.g., not recreated each time the use hook is called); otherwise, each render will cause the component to use the new Promise, not the previous promise, and the component may suspend indefinitely.

  1. An example using cached promises, similar to be shown starting at 21:37 of
    Async React conf talk by @rickhanlonii

  2. Add to the Troubleshooting section about how to deal with use Hook not showing content and reloading content.

Activity

  1. blazevineet commented on Mar 11, 2026

    @blazevineet

    I'd like to work on this. I'll add caveats, a client-side example, and a troubleshooting entry for the use Hook with client-created promises.

  2. blazevineet commented on Mar 11, 2026

    @blazevineet

    I've submitted a PR addressing this issue. It adds a caveat about caching client-side Promises using useMemo to prevent indefinite suspension, and a troubleshooting section with 3 fix options. PR: #1

  3. MaxwellCohen commented on Mar 12, 2026

    @MaxwellCohen
    ContributorAuthor

    @blazevineet, this is being solved by @rickhanlonii in #8305 I

  4. MaxwellCohen commented on Jun 24, 2026

    @MaxwellCohen
    ContributorAuthor

    #8305 has been merged, and we now have this section https://react.dev/reference/react/use#caching-promises-for-client-components, so this issue is resolved!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions