feat: react 19 support

BREAKING CHANGE: Add support for React 19

Author: mrlika

package-lock.json

@@ -34,31 +34,35 @@
     "test": "jest"
   },
   "devDependencies": {
-    "@babel/core": "^7.21.8",
-    "@babel/eslint-parser": "^7.21.8",
-    "@babel/preset-env": "^7.21.5",
-    "@babel/preset-react": "^7.18.6",
-    "@babel/preset-typescript": "^7.21.5",
-    "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^14.0.0",
-    "@types/jest": "^29.5.1",
+    "@babel/core": "^7.26.10",
+    "@babel/eslint-parser": "^7.27.0",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-react": "^7.26.3",
+    "@babel/preset-typescript": "^7.27.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.2",
     "babel-eslint": "^10.1.0",
-    "babel-jest": "^29.5.0",
+    "babel-jest": "^29.7.0",
     "codecov": "^3.8.3",
     "conventional-github-releaser": "^3.1.5",
-    "esbuild": "^0.17.19",
+    "esbuild": "^0.25.3",
     "eslint": "^8.40.0",
-    "eslint-plugin-react": "^7.32.2",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "jest": "^29.5.0",
-    "jest-environment-jsdom": "^29.5.0",
-    "prettier": "^2.8.8",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "rollup": "^3.21.7",
-    "rollup-plugin-dts": "^5.3.0",
-    "rollup-plugin-esbuild": "^5.0.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.5.3",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "rollup": "^4.40.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-esbuild": "^6.2.1",
     "standard-version": "^9.5.0",
-    "typescript": "^5.0.4"
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   }
 }

package.json

@@ -3,7 +3,7 @@ import esbuild from "rollup-plugin-esbuild";
 
 const bundle = (config) => ({
   ...config,
-  input: "src/index.tsx",
+  input: "src/index.ts",
   external: (id) => !/^[./]/.test(id),
 });
 

rollup.config.js

@@ -1,16 +1,19 @@
 import * as React from "react";
 import { render } from "@testing-library/react";
 import { mergeRefs } from ".";
+import { mergeRefsReact16 } from "./mergeRefsReact16";
 
-test("mergeRefs", () => {
+test("mergeRefs React 16+", () => {
   const Dummy = React.forwardRef(function Dummy(_, ref) {
     React.useImperativeHandle(ref, () => "refValue");
     return null;
   });
   const refAsFunc = jest.fn();
   const refAsObj = { current: undefined };
   const Example: React.FC<{ visible: boolean }> = ({ visible }) => {
-    return visible ? <Dummy ref={mergeRefs([refAsObj, refAsFunc])} /> : null;
+    return visible ? (
+      <Dummy ref={mergeRefsReact16([refAsObj, refAsFunc])} />
+    ) : null;
   };
   const { rerender } = render(<Example visible />);
   expect(refAsFunc).toHaveBeenCalledTimes(1);
@@ -22,6 +25,46 @@ test("mergeRefs", () => {
   expect(refAsObj.current).toBe(null);
 });
 
+test("mergeRefs React 19+", () => {
+  const Dummy = React.forwardRef(function Dummy(_, ref) {
+    React.useImperativeHandle(ref, () => "refValue");
+    return null;
+  });
+
+  const refAsFunc = jest.fn();
+
+  const refAsObj = { current: undefined };
+
+  const refCleanup = jest.fn();
+  const refAsFuncWithCleanup = jest.fn(() => refCleanup);
+
+  const Example: React.FC<{ visible: boolean }> = ({ visible }) => {
+    return visible ? (
+      <Dummy ref={mergeRefs([refAsObj, refAsFunc, refAsFuncWithCleanup])} />
+    ) : null;
+  };
+  const { rerender } = render(<Example visible />);
+
+  expect(refAsFunc).toHaveBeenCalledTimes(1);
+  expect(refAsFunc).toHaveBeenCalledWith("refValue");
+
+  expect(refAsObj.current).toBe("refValue");
+
+  expect(refAsFuncWithCleanup).toHaveBeenCalledTimes(1);
+  expect(refAsFuncWithCleanup).toHaveBeenCalledWith("refValue");
+  expect(refCleanup).toHaveBeenCalledTimes(0);
+
+  rerender(<Example visible={false} />);
+
+  expect(refAsFunc).toHaveBeenCalledTimes(2);
+  expect(refAsFunc).toHaveBeenCalledWith(null);
+
+  expect(refAsObj.current).toBe(null);
+
+  expect(refAsFuncWithCleanup).toHaveBeenCalledTimes(1);
+  expect(refCleanup).toHaveBeenCalledTimes(1);
+});
+
 test("mergeRefs with undefined and null refs", () => {
   const Dummy = React.forwardRef(function Dummy(_, ref) {
     React.useImperativeHandle(ref, () => "refValue");

src/index.test.tsx

@@ -0,0 +1,39 @@
+import { Ref, RefCallback, useMemo, version } from "react";
+import { mergeRefsReact16 } from "./mergeRefsReact16";
+import { mergeRefsReact19 } from "./mergeRefsReact19";
+
+/**
+ * Assigns a value to a ref.
+ * @param ref The ref to assign the value to.
+ * @param value The value to assign to the ref.
+ * @returns The ref cleanup callback, if any.
+ */
+export function assignRef<T>(
+  ref: Ref<T> | undefined | null,
+  value: T | null,
+): ReturnType<RefCallback<T>> {
+  if (typeof ref === "function") {
+    return ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}
+
+/**
+ * Merges multiple refs into a single one.
+ * @param refs List of refs to merge.
+ * @returns Merged ref.
+ */
+export const mergeRefs =
+  parseInt(version.split(".")[0], 10) >= 19
+    ? mergeRefsReact19
+    : mergeRefsReact16;
+
+/**
+ * Merges multiple refs into a single one and memoizes the result to avoid refs execution on each render.
+ * @param refs List of refs to merge.
+ * @returns Merged ref.
+ */
+export function useMergeRefs<T>(refs: (Ref<T> | undefined)[]): Ref<T> {
+  return useMemo(() => mergeRefs(refs), refs);
+}

src/index.ts

@@ -0,0 +1,8 @@
+import { Ref } from "react";
+import { assignRef } from ".";
+
+export function mergeRefsReact16<T>(refs: (Ref<T> | undefined)[]): Ref<T> {
+  return (value: T | null) => {
+    for (const ref of refs) assignRef(ref, value);
+  };
+}

src/index.tsx

@@ -0,0 +1,18 @@
+import { Ref } from "react";
+import { assignRef } from ".";
+
+export function mergeRefsReact19<T>(refs: (Ref<T> | undefined)[]): Ref<T> {
+  return (value: T | null) => {
+    const cleanups: (() => void)[] = [];
+
+    for (const ref of refs) {
+      const cleanup = assignRef(ref, value);
+      const isCleanup = typeof cleanup === "function";
+      cleanups.push(isCleanup ? cleanup : () => assignRef(ref, null));
+    }
+
+    return () => {
+      for (const cleanup of cleanups) cleanup();
+    };
+  };
+}