reactjs / reactjs/react.dev

[Suggestion]: remove the caveat for writing ref in render path

Open
#6,925 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: documentation
Dominant language
JavaScript
Stars
11.8k
Forks
7.9k
Avg merge
1d 11h
Merged PRs (30d)
11

Description

Summary

In the doc for ref https://react.dev/reference/react/useRef#caveats, it calls out to not read/write ref in rendering phase without a very clear "bad example"

Page

No response

Details

However, there is use case where the caller just needs a static ref at component level to wrap a dynamic value: for example, I need to read/write a static ref in rendering path (keep it in-sync with the current render context value)

In another word, the argument could be "a need to read/sync a "render context" value into a static variable attached to the functional component", + the "ref" value is not use in the "return" of the functional component

const { componentId, renderId } = useContext(componentContext);
const context = { componentId, renderId } <--- dynamic

const contextRef  =  useRef(context); <--- static
contextRef.current = context;

useQuery({
  context: contextRef  <--- static ref to avoid equal check, the ref value is only used for logging
})

e.g. https://github.com/apollographql/apollo-client/issues/11835

and there are popular library like useLatest implemented by writing ref in render path

Can we remove or update the caveat to make it more clear? E.g. adding

If you don't attempt to use the "mutable" ref in determining the function return, it is fine to use it to sync rendering context

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the useRef caveats section at https://react.dev/reference/react/useRef#caveats and compare its guidance with the Apollo Client issue and useLatest implementation linked in the report. Clarify whether the caveat should be removed or revised for refs synchronized during rendering without affecting the component return, then update the documentation and verify the resulting wording is unambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, react
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.