The Latest Ref Pattern

In one minute

Each render’s functions see that render’s props and state. Usually that’s a feature: an async handler can’t suddenly see values from a later render. But some functions are created once and called much later: a debounced save, a timer callback, a subscription. They need the latest values when they run. The latest ref pattern keeps the newest callback in a ref (callbackRef.current = callback after every render), and the long-lived function calls callbackRef.current(...) at call time. Its identity stays stable, but it always runs the newest code. Inside effects, React 19.2’s useEffectEvent does the same job for you.

You’ll be able to: write a useDebounce hook that neither fires too often nor saves stale values, and know when to use useEffectEvent instead.

1function GiftNote() {2  const [product, setProduct] = useState('Ceramic Mug')3  const saveNote = text => log(`saved "${text}" for ${product}`)4  const debouncedSave = useDebounce(saveNote, 300)5  return <input onChange={e => debouncedSave(e.target.value)} />6}78function useDebounce(callback, delay) {9  return useMemo(10    () => debounce(callback, delay),11    [callback, delay],12  )13}

1function GiftNote() {2  const [product, setProduct] = useState('Ceramic Mug')3  const saveNote = text => log(`saved "${text}" for ${product}`)4  const debouncedSave = useDebounce(saveNote, 300)5  return <input onChange={e => debouncedSave(e.target.value)} />6}78function useDebounce(callback, delay) {9  return useMemo(10    () => debounce(callback, delay),11    [delay], // callback left out12  )13}

1function GiftNote() {2  const [product, setProduct] = useState('Ceramic Mug')3  const saveNote = text => log(`saved "${text}" for ${product}`)4  const debouncedSave = useDebounce(saveNote, 300)5  return <input onChange={e => debouncedSave(e.target.value)} />6}78function useDebounce(callback, delay) {9  const callbackRef = useRef(callback)10  useEffect(() => { callbackRef.current = callback })11  return useMemo(12    () => debounce((...args) => callbackRef.current(...args), delay),13    [delay],14  )15}

The example: a debounced gift note

The cart has a gift note field that saves itself 300 ms after you stop typing. The save also needs to know which product the note is for. The shopper picks “Desk Lamp”, then types “Gift” quickly.

function debounce<A extends unknown[]>(fn: Fn<A>, ms: number): Fn<A> {
	let timer: ReturnType<typeof setTimeout> | undefined
	return (...args) => {
		clearTimeout(timer)
		timer = setTimeout(() => fn(...args), ms)
	}
}

function GiftNote({ useDebounceHook }: { useDebounceHook: typeof useDebounce }) {
	const [product, setProduct] = useState('Ceramic Mug')
	const [note, setNote] = useState('')
	const saveNote = (text: string) => log(`saved "${text}" for ${product}`)
	const debouncedSave = useDebounceHook(saveNote, 300)

	return (
		<>
			<select id="product" value={product} onChange={(e) => setProduct(e.target.value)}>
				<option>Ceramic Mug</option>
				<option>Desk Lamp</option>
			</select>
			<input
				id="note"
				value={note}
				onChange={(e) => {
					setNote(e.target.value)
					debouncedSave(e.target.value)
				}}
			/>
		</>
	)
}

1. Rebuild when the callback changes

function useDebounceRebuild<A extends unknown[]>(callback: Fn<A>, delay: number) {
	return useMemo(() => debounce(callback, delay), [callback, delay])
}

saved "G" for Desk Lamp
saved "Gi" for Desk Lamp
saved "Gif" for Desk Lamp
saved "Gift" for Desk Lamp

Four saves instead of one. saveNote is a new function on every render, so useMemo builds a new debounced function each time, and a new one can’t cancel the timer an old one started. Wrapping saveNote in useCallback doesn’t help: it depends on product, so it changes too, just less often.

2. Build it once

function useDebounceOnce<A extends unknown[]>(callback: Fn<A>, delay: number) {
	// eslint-disable-next-line react-hooks/exhaustive-deps
	return useMemo(() => debounce(callback, delay), [delay])
}

saved "Gift" for Ceramic Mug

One save now, but for the wrong product. The debounced function wraps the saveNote from the first render, when the product was still Ceramic Mug. That’s a stale closure.

3. The latest ref

function useDebounce<A extends unknown[]>(callback: Fn<A>, delay: number) {
	const callbackRef = useRef(callback)
	useEffect(() => {
		callbackRef.current = callback // after every render: the latest callback
	})
	return useMemo(() => debounce((...args: A) => callbackRef.current(...args), delay), [delay])
}

saved "Gift" for Desk Lamp

One save, right product. The debounced function is built once (deps [delay]), so its timer survives re-renders. It doesn’t hold callback: it holds the ref, and reads callbackRef.current when the timer fires.

Don’t write debounce(callbackRef.current, delay). That reads .current once, when useMemo runs, which is the same bug as version 2. The extra arrow function is what delays the read.

Inside effects: useEffectEvent

A stock watcher checks the product’s stock every 200 ms. Clicking “Watch Desk Lamp” changes the product prop.

function StockWatchStale({ product }: { product: string }) {
	useEffect(() => {
		log('watch started')
		const id = setInterval(() => log(`checking stock: ${product}`), 200)
		return () => (log('watch stopped'), clearInterval(id))
		// eslint-disable-next-line react-hooks/exhaustive-deps
	}, [])
	return null
}

Before and after the click:

watch started
checking stock: Ceramic Mug   (repeats)

checking stock: Ceramic Mug   (repeats)

Stale: still checking the mug. Adding product to the dependencies fixes the value, but restarts the interval on every change:

function StockWatchRestart({ product }: { product: string }) {
	useEffect(() => {
		log('watch started')
		const id = setInterval(() => log(`checking stock: ${product}`), 200)
		return () => (log('watch stopped'), clearInterval(id))
	}, [product])
	return null
}

watch stopped
watch started
checking stock: Desk Lamp   (repeats)

useEffectEvent separates the two. The effect sets up the interval once; the event function always sees the latest product:

function StockWatch({ product }: { product: string }) {
	const onTick = useEffectEvent(() => log(`checking stock: ${product}`))
	useEffect(() => {
		log('watch started')
		const id = setInterval(() => onTick(), 200)
		return () => (log('watch stopped'), clearInterval(id))
	}, [])
	return null
}

checking stock: Desk Lamp   (repeats)

No restart, and the new product. useEffectEvent is meant to be called only from effects (and things they set up, like this interval). It’s not a general stable-callback tool for event handlers or props, which is where the hand-written ref is still the answer.

How it works

• Closures capture a render. A function created during render reads the variables of that render forever. That’s why hooks avoid a whole class of async bugs that class components had: there, this.props and this.state could change in the middle of an await.
• A ref is one box for the component’s whole life. Writing .current doesn’t re-render, and every closure that holds the ref sees the newest value.
• Write the ref in an effect, not during render. Render must stay pure: React may render a component and throw the result away. An effect runs only for renders that were committed. (useLayoutEffect updates it a bit earlier, before paint, if a callback could fire in between.)
• No dependency array on that effect. It should run after every render, to always copy the newest callback.

Common mistakes

• Using the pattern to silence the dependency lint rule. It opts out of the “this render’s values” guarantee on purpose. Use it only for functions that genuinely run later.
• Reading ref.current during render. Render would depend on something React doesn’t track.
• Passing callbackRef.current instead of a wrapper function (see above).
• Calling a useEffectEvent function from an event handler or passing it to a child. It’s for effects only.

Interview Q&A

Related

• Side Effects and DOM Refs and Effect Dependencies: effects, refs and dependencies.
• React Re-rendering: stale closures and useCallback.
• useLayoutEffect: an earlier place to update the ref.

Sources

• Kent C. Dodds: The latest ref pattern in React, How React uses closures to avoid bugs
• react.dev: useEffectEvent, Separating events from effects, useRef
• Topic order inspired by Kent C. Dodds’ EpicReact Advanced React Patterns workshop; the example app and code here are this handbook’s own.

Primary source: epicreact.dev/the-latest-ref-pattern-in-react