React Ref Forwarding Guide

Ref forwarding passes a ref through a component to a child element. Here's how to use it effectively.

Basic Ref Forwarding#

import { forwardRef, useRef } from 'react';

// Forward ref to input element
const TextInput = forwardRef(function TextInput(props, ref) {
  return (
    <input
      ref={ref}
      type="text"
      className="text-input"
      {...props}
    />
  );
});

// Usage
function Form() {
  const inputRef = useRef(null);

  const focusInput = () => {
    inputRef.current?.focus();
  };

  return (
    <div>
      <TextInput ref={inputRef} placeholder="Enter text" />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  );
}

With TypeScript#

import { forwardRef, useRef, InputHTMLAttributes } from 'react';

interface TextInputProps extends InputHTMLAttributes<HTMLInputElement> {
  label?: string;
}

const TextInput = forwardRef<HTMLInputElement, TextInputProps>(
  function TextInput({ label, ...props }, ref) {
    return (
      <div className="field">
        {label && <label>{label}</label>}
        <input ref={ref} {...props} />
      </div>
    );
  }
);

// Usage
function Form() {
  const inputRef = useRef<HTMLInputElement>(null);

  return <TextInput ref={inputRef} label="Email" type="email" />;
}

Button Component#

import { forwardRef } from 'react';

const Button = forwardRef(function Button(
  { children, variant = 'primary', ...props },
  ref
) {
  return (
    <button
      ref={ref}
      className={`btn btn-${variant}`}
      {...props}
    >
      {children}
    </button>
  );
});

// Usage
function App() {
  const buttonRef = useRef(null);

  useEffect(() => {
    // Access button's DOM methods
    console.log(buttonRef.current?.getBoundingClientRect());
  }, []);

  return (
    <Button ref={buttonRef} variant="secondary">
      Click Me
    </Button>
  );
}

Forwarding to Multiple Elements#

import { forwardRef, useImperativeHandle, useRef } from 'react';

// Expose multiple refs via useImperativeHandle
const FormGroup = forwardRef(function FormGroup(props, ref) {
  const inputRef = useRef(null);
  const labelRef = useRef(null);

  useImperativeHandle(ref, () => ({
    input: inputRef.current,
    label: labelRef.current,
    focus: () => inputRef.current?.focus(),
    clear: () => {
      if (inputRef.current) inputRef.current.value = '';
    },
  }));

  return (
    <div className="form-group">
      <label ref={labelRef}>{props.label}</label>
      <input ref={inputRef} {...props} />
    </div>
  );
});

// Usage
function Form() {
  const formGroupRef = useRef(null);

  const handleClear = () => {
    formGroupRef.current?.clear();
    formGroupRef.current?.focus();
  };

  return (
    <>
      <FormGroup ref={formGroupRef} label="Username" />
      <button onClick={handleClear}>Clear & Focus</button>
    </>
  );
}

import { forwardRef, useImperativeHandle, useState } from 'react';

const Modal = forwardRef(function Modal({ title, children }, ref) {
  const [isOpen, setIsOpen] = useState(false);

  useImperativeHandle(ref, () => ({
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    toggle: () => setIsOpen(prev => !prev),
    isOpen,
  }));

  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={() => setIsOpen(false)}>
      <div className="modal" onClick={e => e.stopPropagation()}>
        <header>
          <h2>{title}</h2>
          <button onClick={() => setIsOpen(false)}>×</button>
        </header>
        <div className="modal-content">{children}</div>
      </div>
    </div>
  );
});

// Usage
function App() {
  const modalRef = useRef(null);

  return (
    <>
      <button onClick={() => modalRef.current?.open()}>
        Open Modal
      </button>
      <Modal ref={modalRef} title="Settings">
        <p>Modal content here</p>
      </Modal>
    </>
  );
}

Scroll Container#

import { forwardRef, useImperativeHandle, useRef } from 'react';

const ScrollContainer = forwardRef(function ScrollContainer(
  { children, ...props },
  ref
) {
  const containerRef = useRef(null);

  useImperativeHandle(ref, () => ({
    scrollTo: (options) => containerRef.current?.scrollTo(options),
    scrollToTop: () => containerRef.current?.scrollTo({ top: 0, behavior: 'smooth' }),
    scrollToBottom: () => {
      const el = containerRef.current;
      if (el) {
        el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });
      }
    },
    getScrollPosition: () => ({
      top: containerRef.current?.scrollTop ?? 0,
      left: containerRef.current?.scrollLeft ?? 0,
    }),
  }));

  return (
    <div ref={containerRef} className="scroll-container" {...props}>
      {children}
    </div>
  );
});

// Usage
function ChatWindow() {
  const scrollRef = useRef(null);

  const handleNewMessage = () => {
    scrollRef.current?.scrollToBottom();
  };

  return (
    <ScrollContainer ref={scrollRef}>
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
    </ScrollContainer>
  );
}

Video Player#

import { forwardRef, useImperativeHandle, useRef } from 'react';

const VideoPlayer = forwardRef(function VideoPlayer({ src, ...props }, ref) {
  const videoRef = useRef(null);

  useImperativeHandle(ref, () => ({
    play: () => videoRef.current?.play(),
    pause: () => videoRef.current?.pause(),
    stop: () => {
      const video = videoRef.current;
      if (video) {
        video.pause();
        video.currentTime = 0;
      }
    },
    seek: (time) => {
      if (videoRef.current) {
        videoRef.current.currentTime = time;
      }
    },
    getCurrentTime: () => videoRef.current?.currentTime ?? 0,
    getDuration: () => videoRef.current?.duration ?? 0,
    setVolume: (volume) => {
      if (videoRef.current) {
        videoRef.current.volume = Math.max(0, Math.min(1, volume));
      }
    },
  }));

  return <video ref={videoRef} src={src} {...props} />;
});

// Usage
function Player() {
  const videoRef = useRef(null);

  return (
    <div>
      <VideoPlayer ref={videoRef} src="/video.mp4" />
      <div className="controls">
        <button onClick={() => videoRef.current?.play()}>Play</button>
        <button onClick={() => videoRef.current?.pause()}>Pause</button>
        <button onClick={() => videoRef.current?.stop()}>Stop</button>
      </div>
    </div>
  );
}

Higher-Order Component#

import { forwardRef } from 'react';

// HOC that forwards refs
function withLogging(WrappedComponent) {
  const WithLogging = forwardRef(function WithLogging(props, ref) {
    useEffect(() => {
      console.log(`${WrappedComponent.name} mounted`);
      return () => console.log(`${WrappedComponent.name} unmounted`);
    }, []);

    return <WrappedComponent ref={ref} {...props} />;
  });

  WithLogging.displayName = `WithLogging(${WrappedComponent.name})`;
  return WithLogging;
}

// Base component with forwardRef
const Input = forwardRef(function Input(props, ref) {
  return <input ref={ref} {...props} />;
});

// Enhanced component
const LoggedInput = withLogging(Input);

// Usage
function Form() {
  const inputRef = useRef(null);
  return <LoggedInput ref={inputRef} />;
}

Compound Components#

import { forwardRef, createContext, useContext, useRef } from 'react';

const TabsContext = createContext(null);

const Tabs = forwardRef(function Tabs({ children, defaultValue }, ref) {
  const [value, setValue] = useState(defaultValue);

  return (
    <TabsContext.Provider value={{ value, setValue }}>
      <div ref={ref} className="tabs">
        {children}
      </div>
    </TabsContext.Provider>
  );
});

const TabList = forwardRef(function TabList({ children }, ref) {
  return (
    <div ref={ref} className="tab-list" role="tablist">
      {children}
    </div>
  );
});

const Tab = forwardRef(function Tab({ value, children }, ref) {
  const { value: selected, setValue } = useContext(TabsContext);

  return (
    <button
      ref={ref}
      role="tab"
      aria-selected={selected === value}
      onClick={() => setValue(value)}
    >
      {children}
    </button>
  );
});

Tabs.List = TabList;
Tabs.Tab = Tab;

Best Practices#

When to Use:
✓ Wrapping DOM elements
✓ Building component libraries
✓ HOC that wrap components
✓ Compound components

useImperativeHandle:
✓ Expose limited API
✓ Custom methods
✓ Multiple element refs
✓ Complex interactions

TypeScript:
✓ Specify element type
✓ Define custom handle type
✓ Extend HTML attributes
✓ Document exposed methods

Avoid:
✗ Exposing entire DOM node
✗ Overusing imperative APIs
✗ Forgetting displayName
✗ Complex ref hierarchies

Ref forwarding enables passing refs through components to DOM elements. Use forwardRef for simple cases, combine with useImperativeHandle to expose custom APIs. This pattern is essential for component libraries, accessibility, and integrating with third-party libraries that need DOM access. Keep exposed APIs minimal and well-documented.