React Ref Merging Utility

Common errors

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

  cause 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'

  cause 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)

  cause 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.

Warnings

• breaking Version 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.
• breaking Version 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.
• gotcha The `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.
• gotcha Misunderstanding 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.

Install

• npm install react-merge-refs npm
• yarn add react-merge-refs yarn
• pnpm add react-merge-refs pnpm

Imports

• mergeRefs
  wrong:

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

  correct:

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

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

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

  correct:

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

  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.

Quickstart

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;