React Multi-Ref Utility

1.0.2 · active · verified Sun Apr 19

react-multi-ref is a lightweight utility library designed to simplify managing references to multiple, dynamically created React elements. It addresses a common challenge in React development where developers need to collect and interact with a collection of DOM nodes or component instances, especially when dealing with lists or forms. The current stable version is 1.0.2, indicating a mature and stable API. As a utility, its release cadence is likely slow, focusing on stability rather than frequent feature additions. Key differentiators include its simplicity, providing a `Map`-like interface to access refs by a custom key, and its explicit support for both functional components (via `useState`) and class components, with integrated TypeScript and Flow type definitions for enhanced developer experience. It avoids the complexities of managing arrays of refs manually or relying on less explicit methods.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'value') or TypeError: Cannot read properties of null (reading 'value')
```
cause Attempting to access properties (like `.value`) on a ref that has not yet been assigned by React, or refers to an unmounted component, or the `key` used in `multiRef.ref(key)` does not correspond to an actual mounted element.

fix Always check if the ref element exists before accessing its properties: `if (inputElement) { /* access inputElement.value */ }`. Ensure the component is mounted when accessing refs, e.g., in an `useEffect` or event handler, not during render.
```
React Hook 'useState' cannot be called inside a callback. React Hooks must be called in a React function component or a custom React Hook function.
```
cause Misuse of `useState` by calling it inside a non-component function or an event handler, instead of at the top level of a functional component.

fix Ensure `useState(() => new MultiRef())` is called directly within the body of your functional React component, not within any nested functions or event handlers.

Warnings

gotcha When using `react-multi-ref` in functional components, the `MultiRef` instance must be created and persisted using `useState` (e.g., `useState(() => new MultiRef())`). Do not use `useMemo` for this purpose, as React is allowed to reset memoized values at any time, which would lead to loss of ref tracking.
Fix: Always initialize `MultiRef` inside `useState`'s factory function: `const [myRefs] = useState(() => new MultiRef());`
gotcha Each call to `multiRef.ref(key)` requires a unique `key` parameter. This key is used to identify and retrieve the specific element from the internal `Map`. Reusing the same key for different elements or omitting the key will lead to incorrect ref mapping.
Fix: Ensure that the key passed to `multiRef.ref(key)` is unique for each element you want to track, typically derived from an array index or unique item ID.

Install

npm install react-multi-ref npm
yarn add react-multi-ref yarn
pnpm add react-multi-ref pnpm

Imports

MultiRef
wrong:
```
const MultiRef = require('react-multi-ref').MultiRef;
```
correct:
```
import MultiRef from 'react-multi-ref';
```
This package uses a default export for the MultiRef class. For CommonJS, `require('react-multi-ref')` directly returns the class.
MultiRef instance
wrong:
```
const itemRefs = useMemo(() => new MultiRef(), []);
```
correct:
```
const [itemRefs] = useState(() => new MultiRef());
```
When using in function components, create the MultiRef instance using `useState` with a factory function to ensure it persists across renders and avoids React's potential memory resets, unlike `useMemo`.
ref callback
wrong:
```
<input ref={itemRefs.ref} />
```
correct:
```
<input ref={itemRefs.ref(i)} />
```
The `ref` method requires a unique key parameter to associate the DOM element with that key in the internal map.

Quickstart

Demonstrates how to use MultiRef in a functional React component to manage references to multiple dynamically created input elements and retrieve their values.

import { useState } from 'react';
import MultiRef from 'react-multi-ref';

function MyDynamicForm() {
  // Initialize MultiRef using useState to persist the instance across renders
  const [inputRefs] = useState(() => new MultiRef());

  // Generate 5 input fields, assigning a ref to each using its index as a key
  const inputElements = new Array(5).fill(null).map((_, i) => (
    <div key={i} style={{ marginBottom: '10px' }}>
      <label>
        Input {i + 1}: 
        <input type="text" ref={inputRefs.ref(i)} placeholder={`Value for item ${i + 1}`} />
      </label>
    </div>
  ));

  // Event handler to collect all input values
  function handleSubmit() {
    const values = [];
    inputRefs.map.forEach((inputElement, key) => {
      if (inputElement) {
        values.push(`Key ${key}: ${inputElement.value}`);
      }
    });
    alert("Current input values:\n" + values.join('\n'));
  }

  return (
    <div>
      <h3>Dynamic Input Form</h3>
      {inputElements}
      <button onClick={handleSubmit} style={{ marginTop: '20px', padding: '10px 15px' }}>
        Get All Input Values
      </button>
    </div>
  );
}

// To run this example in a React application:
// export default MyDynamicForm;

view raw JSON →