React Merge Refs: A Simple Guide to Working With Multiple Refs

When I first encountered the challenge of handling multiple refs in a React component, I was torn between the simplicity of single refs and the complexity of managing several. It turns out that merging refs isn’t just a matter of syntax—it’s about crafting an elegant and resilient solution.

Let’s dive into the journey of mastering React merge refs, exploring why you might need it, how to implement it, and some of the common pitfalls along the way.

Why Merge Refs?

In React, refs provide direct access to DOM nodes or React elements. Typically, a single ref is sufficient. However, things can get tangled when multiple layers or higher-order components need access to the same element. Imagine trying to coordinate two remote-controlled drones without a common command center—that’s what it feels like without merging refs.

Developers often need merged refs to:

• Forward refs in higher-order components.

• Coordinate stateful logic across different parts of an app.

• Simplify complex component hierarchies by keeping the reference management centralized.

This isn’t just academic; it directly impacts performance and code clarity, especially in larger applications.

Understanding the Problem

Before merging refs, it's crucial to grasp what makes them tricky:

• Imperative vs. Declarative: Refs operate outside the usual React data flow, making them inherently imperative.

• Consistency Issues: Without merging, different parts of your code might try to manipulate the same DOM node in conflicting ways.

• Component Boundaries: When passing refs through components, you must ensure that both parent and child maintain a consistent reference.

For instance, a common scenario arises when a component must expose its DOM node to an internal handler and an external consumer. Without a unified ref, you risk losing control over the element or encountering unexpected bugs.

Implementing a Merge Refs Utility

Let’s look at a straightforward implementation of a mergeRefs function. This utility takes multiple refs and combines them into one. Here’s a code snippet that’s been my go-to solution:

1import React, { forwardRef } from 'react';
2
3function mergeRefs(...refs) {
4  return (node) => {
5    refs.forEach((ref) => {
6      if (typeof ref === 'function') {
7        ref(node);
8      } else if (ref != null) {
9        ref.current = node;
10      }
11    });
12  };
13}
14
15// Usage example in a functional component:
16const Input = forwardRef((props, ref) => {
17  const localRef = React.useRef(null);
18  const mergedRef = mergeRefs(ref, localRef);
19
20  return <input {...props} ref={mergedRef} />;
21});
22
23export default Input;

​

In this snippet, the mergeRefs function iterates over each ref and assigns the node accordingly, handling callback and object refs. This utility encapsulates the complexity, making your components cleaner and more maintainable.

Practical Use Cases

Forwarding Refs in Higher-Order Components

One of the most common scenarios is when a component wraps another component but still needs to provide access to the inner DOM node:

1const withFocus = (Component) => {
2  return forwardRef((props, ref) => {
3    const innerRef = React.useRef(null);
4    const mergedRef = mergeRefs(ref, innerRef);
5
6    React.useEffect(() => {
7      if (innerRef.current) {
8        innerRef.current.focus();
9      }
10    }, []);
11
12    return <Component {...props} ref={mergedRef} />;
13  });
14};

​

Managing Component Libraries

When building reusable component libraries, merging refs ensures that library consumers can attach their own refs without losing internal control. This approach improves flexibility and enhances debugging and performance.

Pitfalls and Gotchas

Even with a robust solution, merging refs isn’t entirely plug-and-play. Here are some issues to watch out for:

• Timing Issues: Be mindful of when refs are updated. React’s lifecycle can sometimes result in transient states where refs are null.

• Function vs. Object Refs: Always account for both types to avoid runtime errors. The merge function should gracefully handle these cases.

• Over-Merging: Avoid merging refs unnecessarily. Sometimes a simpler solution—like lifting state—might be more appropriate.

Developer Insight: “It’s tempting to merge refs everywhere, but remember: not every component needs this level of complexity. Use it judiciously.”

— A senior developer I once worked with

A Developer’s War Story

I recall a project where our team built a complex form with numerous custom inputs, each requiring internal validation and external focus management. Initially, we attempted to use separate refs for every input. As the project evolved, our codebase became a tangled web of ref assignments and callback functions. One late night, while debugging a focus issue that only occurred during specific user interactions, I decided to refactor using a merged refs approach. The improvement was immediate—code clarity increased, and the elusive focus bugs vanished. That night, I learned that sometimes the simplest utility can resolve the most stubborn issues.

TL;DR

• Merging refs in React helps manage multiple ref assignments in a clean, unified way.

• Use the mergeRefs utility to handle both callback and object refs.

• Be cautious of timing issues and only merge when necessary.

• The technique is particularly valuable in HOCs and component libraries.

The Bottom Line!

Merging refs might seem like a niche problem, but it’s one that many developers will face as their applications scale. The solution is simple and profound, offering a glimpse into the nuanced balance between React’s declarative nature and the occasional need for imperative control. Implementing a robust mergeRefs function can streamline your code, improve component reusability, and dodge many potential pitfalls.

Whether you’re refactoring an existing project or starting fresh, I hope this guide provides practical insights and a few war stories that resonate. Happy coding, and remember: sometimes the simplest solution is the most elegant.

Short on time? Speed things up with DhiWise!

Tired of manually designing screens, coding on weekends, and technical debt? Let DhiWise handle it for you!

You can build an e-commerce store, healthcare app, portfolio, blogging website, social media or admin panel right away. Use our library of 40+ pre-built free templates to create your first application using DhiWise.