How it works
On mount, React 19.3.1's useRef creates { current: initialValue }, stores it in the component's list of hooks, and returns it. On every update it returns the stored object and ignores its argument. That's an implementation detail of ReactFiberHooks.js, but it explains the behaviour: every closure from every render holds the same object, so all of them see the latest current. There is no per-render snapshot, which is what makes a ref useful in a timeout callback and unreliable as render input.
React itself never reads current. It writes it in one case: when the ref is passed as ref to an element, React stores the DOM node during the commit and resets it to null when the node goes away. How and when that happens, and what ref callbacks change, is the next question.
Because the argument is ignored after mount, useRef(new Player()) still constructs a Player on every render and throws it away. Lazy initialisation avoids that, and it's the one render-time access the docs allow:
function Video() {
const playerRef = useRef(null);
if (playerRef.current === null) {
playerRef.current = new Player(); // once per mounted instance
}
return <button onClick={() => playerRef.current.play()}>Play</button>;
}
eslint-plugin-react-hooks 7.1.1 accepts this, and reports renders.current += 1 in a component body as "Cannot access refs during render".
Edge cases
Writes during render run more often than you think. A render counter kept in a ref:
function Renders() {
const renders = useRef(0);
renders.current += 1; // 🚩 write during render
return <p>{renders.current}</p>; // 🚩 read during render
}
After mounting inside <StrictMode>, a development build showed 2, and each update added 2; a production build showed 1 and added 1 (React 19.3.1, Chrome 156 and Firefox 159). In 19.3.1 both Strict Mode calls received the same ref object; the useRef reference still says each ref is created twice and one discarded. Either way the write ran twice. Production can also call a component without committing: a transition interrupted by a more urgent update, or a render that suspends. A write made in such a render stays in the ref even though no user ever saw that render.
Objects in a ref that also feed rendering. You may mutate current freely, but if it holds an object that state or props also use for rendering, mutating that object is still mutating render data. Copy it, or keep it in state.
Remounts reset refs. The object belongs to the mounted instance. Changing a component's key or moving it to another place in the tree creates a new instance and a new ref.
Real-world scenario
"Show whether the price went up" is often solved with a usePrevious hook built on a ref. It has two problems: it reads the ref during render, and it returns the value from the previous render, not the previous different value. The state-based pattern from the useState reference stores what it needs to compare:
function usePrevious(value) {
const ref = useRef(undefined);
useEffect(() => {
ref.current = value;
});
return ref.current; // 🚩 read during render
}
function Price({ price, theme }) {
const prevFromRef = usePrevious(price);
const [prevPrice, setPrevPrice] = useState(price);
const [trend, setTrend] = useState(null);
if (price !== prevPrice) {
setPrevPrice(price);
setTrend(price > prevPrice ? 'up' : 'down');
}
useEffect(() => console.log(price, theme, prevFromRef, trend));
return null;
}
root.render(<Price price={10} theme="light" />); // → 10 light undefined null
root.render(<Price price={12} theme="light" />); // → 12 light 10 up
root.render(<Price price={12} theme="dark" />); // → 12 dark 12 up
Production build of React 19.3.1, each render flushed with flushSync, Firefox 159 output (Chrome 156's console shows the same values). The theme change re-rendered the component, so the ref-based "previous" price became 12 and a trend computed from it would read "unchanged". The state version still says "up", because it updates only when the price actually changes. The lint flags return ref.current in usePrevious.
Trade-offs
- State for anything the user sees. It costs a render per change, which is the point.
- A ref for values only handlers and effects use. It's invisible to React: no re-render, no snapshot, not allowed in render, and the lint is the only guard.
- A module variable is shared by every instance and outlives them. Fine for a true singleton, wrong for per-component data.
- Derived values need neither: compute them during render from props and state.
- The latest props inside an effect used to be a ref written in an effect.
useEffectEvent now covers that without the ref.