[smg99]

Fixes #7811

Summary

• Clarify the ref callback behavior when callbacks change between renders
• Explicitly describe the cleanup-function path as the primary behavior
• Clarify that passing null to the old callback is legacy fallback behavior when no cleanup is returned

Why

Issue #7811 points out ambiguity in the current wording, especially around when React calls a previous callback with null. This change aligns wording with current React 19 cleanup semantics while preserving backwards-compatibility notes.

Validation

• Ran yarn lint
• Ran yarn lint-heading-ids

[smg99]

Requesting review for this wording clarification.

This updates the ref callback section to emphasize the cleanup-function path first, and clarifies that null is the legacy fallback when no cleanup function is returned.

Happy to refine wording further if maintainers prefer a different phrasing.

[github-actions]

Size changes

Details

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

This PR introduced no changes to the JavaScript bundle! 🙌

[aurorascharff]

Could we preserve the existing wording and emphasis while clarifying the cleanup behavior?

Suggested change

React will also call your `ref` callback whenever you pass a *different* `ref` callback. In the above example, `(node) => { ... }` is a different function on every render. When your component re-renders, React calls the previous callback's cleanup function (if provided). If no cleanup function is returned, React calls the previous callback with `null`. Then React calls the next callback with the DOM node.

React will also call your `ref` callback whenever you pass a *different* `ref` callback. In the above example, `(node) => { ... }` is a different function on every render. When your component re-renders, the cleanup function returned by the *previous* function will be called, and the *next* function will be called with the DOM node. If no cleanup function is returned, the *previous* function will be called with `null` as the argument instead.

[aurorascharff]

Also here try to preserve whats already written as it doesnt seem important for the intended clarification, meaning keeping "the callback"

[smg99]

Thanks for the review, @aurorascharff! I've addressed both suggestions in commit 4928162: preserved the existing wording and emphasis while clarifying the cleanup behavior, and kept "the callback" in the preceding paragraph. Could you please take another look when you have a chance?