Registry / web-framework / react-merge-refs

react-merge-refs

library3.0.2jsnpmunverified

react-merge-refs is a concise utility designed for React developers to combine multiple ref objects or functions into a single ref callback. This is particularly useful in component development where a local ref (e.g., from `useRef`) needs to be managed alongside an external ref passed via `React.forwardRef`. The library currently stands at version 3.0.2, actively maintained with releases addressing bug fixes and support for new React versions, including React 19. It aims to simplify the complexities of React's ref system, abstracting away the differences between various ref types (object refs, function refs) and ensuring compatibility across React versions, thereby preventing common pitfalls when trying to assign multiple refs to a single DOM element or component.

web-framework

npm install react-merge-refs

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-MERGE-REFS

react-merge-refs

web-frameworkjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mergeRefs

✓ import { mergeRefs } from 'react-merge-refs';

✗ import mergeRefs from 'react-merge-refs'; /* (before v2.0.0 or incorrect CJS interop) */

Since v2.0.0, `react-merge-refs` is ESM-only and exports `mergeRefs` as a named export. Older versions used a default export.

mergeRefs

✓ const { mergeRefs } = require('react-merge-refs');

✗ const mergeRefs = require('react-merge-refs'); /* (before v2.0.0 or incorrect CJS interop) */

While primarily ESM-only since v2.0.0, modern CommonJS environments might resolve this via interop. Prefer ESM imports where possible. Before v2.0.0, it was a default export via `require`.

MergeRefs

✓ import type { MergeRefs } from 'react-merge-refs';

The library ships with TypeScript types, allowing for type-safe usage of the `mergeRefs` function.

This quickstart demonstrates how to use `mergeRefs` with `React.forwardRef` and `React.useRef` to combine both a local component ref and an externally forwarded ref onto a single DOM element.

import React from 'react'; import { mergeRefs } from 'react-merge-refs'; interface ExampleProps { // Other props } const Example = React.forwardRef<HTMLDivElement, ExampleProps>(function Example(props, ref) { const localRef = React.useRef<HTMLDivElement>(null); // When merging refs, ensure all refs are handled. // It's common to have a local ref and a forwarded ref. return ( <div ref={mergeRefs([localRef, ref])} style={{ border: '1px solid blue', padding: '10px' }} > This is an example component. <button onClick={() => { if (localRef.current) { localRef.current.style.backgroundColor = 'yellow'; console.log('Local ref current:', localRef.current); } }}>Highlight Local Ref</button> </div> ); }); // Usage in another component: const App = () => { const appRef = React.useRef<HTMLDivElement>(null); React.useEffect(() => { if (appRef.current) { console.log('App ref current:', appRef.current); appRef.current.style.border = '2px dashed red'; } }, []); return <Example ref={appRef} />; }; export default App;

Debug

Known issues

breakingVersion 3.0.0 introduced support for React 19. While it primarily involved dependency updates, always test your application when upgrading across major React versions.

fix

Ensure your project's React version is compatible with `react-merge-refs@3.x`. Upgrade React to 19 if necessary, or use a `react-merge-refs@2.x` version for older React installations.

affects: >=3.0.0

breakingVersion 2.0.0 made the package ESM-only and changed its export style from a default export to a named export (`mergeRefs`). This is a significant breaking change for projects using CommonJS or relying on the previous default import syntax.

fix

Update your import statements from `import mergeRefs from 'react-merge-refs'` to `import { mergeRefs } from 'react-merge-refs'`. For CommonJS environments, ensure your build setup correctly handles ESM or use `const { mergeRefs } = require('react-merge-refs');` for interop if supported.

affects: >=2.0.0

gotchaThe `react` package became an optional peer dependency starting with v3.0.2. While this allows for more flexible installation scenarios, `react-merge-refs` fundamentally requires React to function correctly. Installing `react` is still necessary.

fix

Always ensure `react` and `react-dom` are installed as direct dependencies in your project, even though `react-merge-refs` might list `react` as an optional peer dependency.

affects: >=3.0.2

gotchaMisunderstanding how refs work, especially with `React.forwardRef` and functional components, can lead to incorrect usage. `react-merge-refs` solves combining multiple refs but doesn't substitute for a basic understanding of React's ref system.

fix

Familiarize yourself with React's documentation on refs, especially `React.forwardRef`, `useRef`, and `useImperativeHandle`, to ensure correct application and expected behavior in your components.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , react_merge_refs__WEBPACK_IMPORTED_MODULE_2__.default) is not a function

Attempting to use `react-merge-refs` with a default import syntax (e.g., `import mergeRefs from '...'`) in a version 2.0.0 or later environment, where it changed to a named export.

fix

Change your import statement to use a named import: `import { mergeRefs } from 'react-merge-refs';`

SyntaxError: Named export 'mergeRefs' not found. The requested module 'react-merge-refs' does not provide an export named 'mergeRefs'

Attempting to use a named import (`import { mergeRefs } from '...'`) with a version of `react-merge-refs` *prior* to 2.0.0, which used a default export.

fix

Change your import statement to use a default import: `import mergeRefs from 'react-merge-refs';` or upgrade your `react-merge-refs` package to version 2.0.0 or newer.

ReferenceError: require is not defined (for ESM-only package in CJS context)

Using `require('react-merge-refs')` in a pure ESM context without proper transpilation or configuration, or vice versa, trying to `require` the ESM-only v2+ package in a CJS environment that doesn't handle ESM interop.

fix

If in an ESM project, use `import { mergeRefs } from 'react-merge-refs';`. If in a CJS project, ensure your environment supports ESM interop for `require` or update your build configuration. For older CJS-only environments, consider using `react-merge-refs@^1.x.x` if available and compatible.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

reactoptionalPeer dependency for React applications. Became optional in v3.0.2, but required for functionality.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gregberge/react-merge-refs ↗

packagehttps://www.npmjs.com/package/react-merge-refs ↗