[Suggestion]: Documentation for `useRef` should tell us how to deal with multiple refs on a single element

Summary

Sometimes you need to add more than one ref to a single element. For example:

• When using forwardRef you need to pass the forwarded ref to whatever element, but you also need your own ref attached to the same element.
• When using useController of react-hook-form, you get a ref you need to pass to the input element for focus management, but you also need your own ref for doing other things with that same input element.

This is an issue that is not even mentioned on the current documentation of useRef. I've been using gregberge/react-merge-refs to deal with this, but after I added the recommended eslint-plugin-react-compiler, this method now generates a warning:

Ref values (the current property) may not be accessed during render.

If you're not allowed to access ref values during render to merge them, then how are you supposed to attach multiple refs to a single element now?

The documentation needs to tell us how to do this properly, and in a way that doesn't break the compiler or generate warnings in your eslint plugins.

Page

https://react.dev/reference/react/useRef

Details

Example component needing this:

export default forwardRef(
  function BaseCheckbox(
    { label, indeterminate = false, onChange, onCheckedChange, ...props },
    ref
  ) {
    const inputId = useId();
    const inputRef = useRef(null);

    useLayoutEffect(() => {
      if (inputRef.current)
        inputRef.current.indeterminate = indeterminate;
    }, [indeterminate]);

    return (
      <div className="checkbox">
        <input
          type="checkbox"
          id={inputId}
          /**
           * Here we have two refs we need to attach to this input, but there's no
           * documented way to do that and the undocumented way is not allowed
           * according to the new rules from `eslint-plugin-react-compiler`.
           */ 
          ref={mergeRefs(inputRef, ref)}
          onChange={(e) => {
            onChange?.(e);
            onCheckedChange?.(e.currentTarget.checked);
          }}
          aria-checked={
            indeterminate ? 'mixed' : props.checked ? 'true' : 'false'
          }
          {...props}
        />
        <label htmlFor={inputId}>
          {label}
        </label>
      </div>
    );
  }
);

https://react.dev/reference/react/useRef の現在の useRef リファレンスページから始め、レンダー中の refs についてどのように説明しているかを確認してください。Issue で説明されている multiple-ref と eslint-plugin-react-compiler に関する懸念を調査し、そのうえで、サポートされているアプローチと期待されるコンパイラの動作が明確になるようドキュメントを更新してください。