reactjs
Docs: Clarify the behavior of useEffect with non-primitive dependencies in the Hooks documentation
Issue Body (Example): đź—Ł Area of Concern: The documentation section for the useEffect hook currently explains the dependency array primarily using primitive values (e.g., numbers, strings). However, the common pitfall of including non-primitive values (objects or arrays) directly in the dependency array (which causes the effect to run on every render due to reference change) is not explicitly highlighted or given a clear warning/solution.
đź“ť Proposed Solution/Enhancement:
Add a small section or a highlighted "Note on Non-Primitives" to the useEffect page.
Provide a code example demonstrating the infinite loop/excessive-rerender issue when using an object literal ({}) or array literal ([]) inside the dependency array.
From the current docs it looks like this pitfall is already covered, but maybe not under the “non-primitive” wording. useEffect compares each dependency with its previous value using Object.is, so any dependency whose identity changes on every render will cause the Effect to re-run on every render. This most often happens with objects/arrays that are created during render (e.g. {} / [] literals or an options object), because they get a new reference each time. The “Removing unnecessary object dependencies” section on the useEffect page shows exactly this problem with an options object defined in the component body and used as a dependency, and explains how to fix it by moving object creation into the Effect or making the object non-reactive. Arrays are just objects in JavaScript, so the same reasoning applies to array literals in the dependency array. It might still be helpful to call this out more explicitly in the docs (for example, by mentioning “objects/arrays created during render” or “non-primitive values with unstable identity” near the first explanation of the dependency array, and linking to the “Removing unnecessary object dependencies” section), but the underlying behavior described in this issue is already how useEffect works today.
@hasan4adnan Thank you for the detailed feedback and clarification! That makes perfect sense. I will be revising my Pull Request
Thanks for following up and for revising the PR — much appreciated. I agree that the underlying behavior is already correctly described in the current docs (via Object.is comparisons and the “Removing unnecessary object dependencies” section). That said, making this pitfall more explicit earlier — especially by calling out objects/arrays created during render with unstable identity — would significantly improve clarity for readers who commonly run into this issue. Linking the explanation near the first introduction of the dependency array, with a short example and a pointer to the existing section, sounds like a solid improvement without duplicating content. Looking forward to the updated version.
@hasan4adnan Glad to hear that approach works well!
Just confirming—I pushed the updated commit containing those changes (the concise <Note> with the link and example) right before your reply came in. It should now be visible on the PR for review!