Repository navigation
[Suggestion]: Documentation for useRef should tell us how to deal with multiple refs on a single element #7251
Description
Summary
Sometimes you need to add more than one ref to a single element. For example:
- When using
forwardRefyou need to pass the forwarded ref to whatever element, but you also need your own ref attached to the same element. - When using
useControllerofreact-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
currentproperty) 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>
);
}
);
Activity
ArshadAriff commentedon Oct 25, 2024
/assign
smg99 commentedon Aug 5, 2026
Opened PR #8578 to address this:
#8578
It adds a
useReftroubleshooting section for attaching multiple refs to a single element with a ref callback (object refs + callback refs).