Skip to content

[Suggestion]: clarify behaviour of ref callbacks #7811

Open

Description

@OliverJAsh

Summary

The described behaviour for ref callbacks with null as an argument is ambiguous.

Page

https://react.dev/reference/react-dom/components/common#ref-callback

Details

From https://react.dev/reference/react-dom/components/common#ref-callback:

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 previous function will be called with null as the argument, and the next function will be called with the DOM node.

If I understand correctly, the emphasised sentenced is not correct when the ref callback returns a clean up function, as is the case in the referenced example. This needs to be clarified.

There is a note later on which helps a bit, but I still think this sentence could be made clearer so it makes sense in isolation.

Reduced test case to confirm this behaviour: https://stackblitz.com/edit/vitejs-vite-2r9rn6m2?file=src%2FApp.tsx&terminal=dev

Activity

  1. rickhanlonii commented on May 16, 2025

    @rickhanlonii
    Member

    Yeah this could be cleaned up, want to submit a PR to improve it? It should probably flip so it emphasizes the ref callback pattern and has a note about legacy support with passing null when there's no cleanup.

  2. smg99 commented on Aug 5, 2026

    @smg99

    Opened PR #8579 to address this clarification:
    #8579

    It updates the ref callback wording to prioritize cleanup semantics and clarifies when null is used as fallback.

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