Merge refs

Pro

One callback ref that hands the element to every ref it is given: an app's ref beside an item's own. Each may be an object (useRef), a callback (with or without React 19's cleanup) or undefined. When the element goes, each object is emptied, each callback's cleanup runs, and a callback without one is called with null.

A new callback each call, so React gives the element again on every render it is called in: in a component, use useMergedRefs, which keeps it while the refs stay the same.

const own = React.useRef<HTMLDivElement>(null)
return <div ref={mergeRefs(own, props.ref)} />

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

5.1.0

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.2.0, 4.3.0, 4.4.0, 4.5.0 and 5.0.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

It's types and helpers, listed below.

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/merge-refs

Brings in: tokens

Functions

mergeRefs(...refs: PossibleRef<T>[])

useMergedRefs(...refs: PossibleRef<T>[])

mergeRefs for a component: one callback ref for an app's ref and an item's own, the same function for the component's whole life, so React gives the element once. When a ref it is given changes from one render to the next (an inline callback is new each render), that ref alone is released and the new one given the element, after the render; the others aren't touched.

function Panel({ ref, ...props }: React.ComponentProps<"div">) {
  const own = React.useRef<HTMLDivElement>(null)
  return <div ref={useMergedRefs(own, ref)} {...props} />
}