{"id":11751,"library":"react-merge-refs","title":"React Ref Merging Utility","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/gregberge/react-merge-refs","tags":["javascript","react","utility","ref","typescript"],"install":[{"cmd":"npm install react-merge-refs","lang":"bash","label":"npm"},{"cmd":"yarn add react-merge-refs","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-merge-refs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications. Became optional in v3.0.2, but required for functionality.","package":"react","optional":true}],"imports":[{"note":"Since v2.0.0, `react-merge-refs` is ESM-only and exports `mergeRefs` as a named export. Older versions used a default export.","wrong":"import mergeRefs from 'react-merge-refs'; /* (before v2.0.0 or incorrect CJS interop) */","symbol":"mergeRefs","correct":"import { mergeRefs } from 'react-merge-refs';"},{"note":"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`.","wrong":"const mergeRefs = require('react-merge-refs'); /* (before v2.0.0 or incorrect CJS interop) */","symbol":"mergeRefs","correct":"const { mergeRefs } = require('react-merge-refs');"},{"note":"The library ships with TypeScript types, allowing for type-safe usage of the `mergeRefs` function.","symbol":"MergeRefs","correct":"import type { MergeRefs } from 'react-merge-refs';"}],"quickstart":{"code":"import React from 'react';\nimport { mergeRefs } from 'react-merge-refs';\n\ninterface ExampleProps {\n  // Other props\n}\n\nconst Example = React.forwardRef<HTMLDivElement, ExampleProps>(function Example(props, ref) {\n  const localRef = React.useRef<HTMLDivElement>(null);\n\n  // When merging refs, ensure all refs are handled.\n  // It's common to have a local ref and a forwarded ref.\n  return (\n    <div\n      ref={mergeRefs([localRef, ref])}\n      style={{ border: '1px solid blue', padding: '10px' }}\n    >\n      This is an example component.\n      <button onClick={() => {\n        if (localRef.current) {\n          localRef.current.style.backgroundColor = 'yellow';\n          console.log('Local ref current:', localRef.current);\n        }\n      }}>Highlight Local Ref</button>\n    </div>\n  );\n});\n\n// Usage in another component:\nconst App = () => {\n  const appRef = React.useRef<HTMLDivElement>(null);\n\n  React.useEffect(() => {\n    if (appRef.current) {\n      console.log('App ref current:', appRef.current);\n      appRef.current.style.border = '2px dashed red';\n    }\n  }, []);\n\n  return <Example ref={appRef} />;\n};\n\nexport default App;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to use a named import: `import { mergeRefs } from 'react-merge-refs';`","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.","error":"TypeError: (0 , react_merge_refs__WEBPACK_IMPORTED_MODULE_2__.default) is not a function"},{"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.","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.","error":"SyntaxError: Named export 'mergeRefs' not found. The requested module 'react-merge-refs' does not provide an export named 'mergeRefs'"},{"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.","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.","error":"ReferenceError: require is not defined (for ESM-only package in CJS context)"}],"ecosystem":"npm"}