[Compiler]: Detect use of callback refs for layout synchronization

[yuta0801]

What kind of issue is this?

• React Compiler core (the JS output is incorrect, or your app works incorrectly after optimization)
• babel-plugin-react-compiler (build issue installing or using the Babel plugin)
• eslint-plugin-react-compiler (build issue installing or using the eslint plugin)
• react-compiler-healthcheck (build issue installing or using the healthcheck script)

Link to repro

https://stackblitz.com/edit/react-2u9hf3xf?file=src%2FApp.tsx,src%2FClippedText.tsx&terminal=dev

Repro steps

There are two tabs, and each panel contains the same <ClippedText> component. This component measures the content height and conditionally renders a "Read more" button if the content overflows.

Steps to reproduce:

1. At Tab 1, click the "Read more" button, and confirm that it expands as expected.

2. Switch to Tab 2 and observe that the "Read more" button does not appear, even if the content overflows.

The issue originates from tab switching being implemented using display: none, which prevents the ref callback in <ClippedText> from accessing layout information when the component is hidden. As a result, the content height cannot be measured correctly.

Notably, this behavior can be reproduced without the React Compiler by manually wrapping <ClippedText> in memo(). When using the React Compiler, disabling memoization requires adding "use no memo" in all relevant components.

While this may not strictly be considered a React Compiler bug, it highlights a class of issues where components rely on rerenders to synchronize layout-dependent side effects --- a pattern that is difficult to detect through conventional rules such as the Rules of Hooks. In such cases, automatic memoization introduced by the compiler can lead to subtle and hard-to-diagnose behavior changes.

For use cases involving visibility toggled via display: none, using <Activity> is likely a more reliable approach, as it is designed to manage component lifecycle transitions more accurately.

This issue was opened at the request of @josephsavona.

How often does this bug happen?

Every time

What version of React are you using?

19.1.0

What version of React Compiler are you using?

19.1.0-rc.1

[josephsavona]

Thanks for the detailed repro! What's happening here is that the callback ref is not a pure function — it's looking at external mutable state, namely the scrollHeight and offsetHeight. When those values change (due to display none being set/unset elsewhere), React does not know to re-run the function. You're basically relying on lack of memoization causing the component to happen to run again, thus re-recreating the ref callback and re-executing it, in order to check the latest layout value. As you noted this also doesn't work with React.memo() and it also wouldn't work if you wrapped the measureRef callback in a useCallback(), either of which should be fine to do.

Instead, our recommended pattern for this type of scenario is to use an effect and explicitly synchronize with the external system. In this case you can do that with useEffect and a ResizeObserver.

Again, we appreciate you flagging this. It's not a compiler bug, but it is a place where the compiler broke code that happened to work before. We'll have a think about whether we can detect problematic patterns like this. The firsts thing that comes to mind is that setState in the body of a callback ref is a strong signal that you're doing synchronization which should probably be in an effect.