Nowhere in the docs does it say that `this.refs` is a reserved property name

Open Beginner friendly
#4,681 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
65/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
javascript, react
Domain
documentation

Research direction

Start with the Refs page and its “Legacy API: String Refs” section, which currently mentions this.refs without explicitly describing the reserved-name constraint. Update the documentation near the top and in that section so readers know that this.refs is reserved and should not be overwritten.

Written by the indexing model from the issue text.

Description

When creating multiple refs for a component class, it isn't unlikely that an unaware developer, wanting to add an array of refs to their component, would choose to use the property name this.refs.

It seems however that React uses this property name internally and so assigning to this.refs in the constructor will be irreversibly overwritten by an empty object {}. Other (not-obviously-reserved) names are fine, including singular this.ref.

I assume that this isn't a bug with react (although maybe?), but this constraint isn't mentioned explicitly in the Reactjs.org docs. The only mention of this.refs is a small section on the Refs page of the docs titled "Legacy API: String Refs", which does explain that this.refs was used in a deprecated API, but doesn't explicitly say that the name .refs is still reserved and can't be used.

It should probably be mentioned explicitly somewhere on that page, preferably both near the top and in that particular section. It took me quite a while of debugging to incidentally try a different name and stumble upon this issue. There are also several StackOverflow questions from other people asking why their refs aren't working when they are using this.refs but none of the people answering seem to be aware of this constraint.

Dominant language
JavaScript
Stars
11.8k
Forks
7.9k
Avg merge
16h 6m
Merged PRs (30d)
7

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.

More from reactjs/react.dev

All issues in reactjs/react.dev

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.