React Refs and Forwarding

Refs provide direct access to DOM elements and component instances. Here's how to use them effectively.

Basic useRef#

import { useRef, useEffect } from 'react';

function TextInput() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    // Focus on mount
    inputRef.current?.focus();
  }, []);

  const handleClick = () => {
    // Access DOM directly
    inputRef.current?.select();
  };

  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={handleClick}>Select All</button>
    </div>
  );
}

// Store mutable values without re-renders
function Timer() {
  const intervalRef = useRef<NodeJS.Timeout | null>(null);
  const countRef = useRef(0);

  const startTimer = () => {
    intervalRef.current = setInterval(() => {
      countRef.current += 1;
      console.log(countRef.current);
    }, 1000);
  };

  const stopTimer = () => {
    if (intervalRef.current) {
      clearInterval(intervalRef.current);
    }
  };

  return (
    <div>
      <button onClick={startTimer}>Start</button>
      <button onClick={stopTimer}>Stop</button>
    </div>
  );
}

Callback Refs#

import { useCallback, useState } from 'react';

function MeasuredComponent() {
  const [height, setHeight] = useState(0);

  // Callback ref - called when element mounts/unmounts
  const measuredRef = useCallback((node: HTMLDivElement | null) => {
    if (node !== null) {
      setHeight(node.getBoundingClientRect().height);
    }
  }, []);

  return (
    <div>
      <div ref={measuredRef}>
        Content that we want to measure
      </div>
      <p>Height: {height}px</p>
    </div>
  );
}

// Handling multiple refs
function MultipleRefs() {
  const refsMap = useRef(new Map<string, HTMLDivElement>());

  const setRef = (id: string) => (node: HTMLDivElement | null) => {
    if (node) {
      refsMap.current.set(id, node);
    } else {
      refsMap.current.delete(id);
    }
  };

  const scrollToItem = (id: string) => {
    const node = refsMap.current.get(id);
    node?.scrollIntoView({ behavior: 'smooth' });
  };

  return (
    <div>
      {['a', 'b', 'c'].map((id) => (
        <div key={id} ref={setRef(id)}>
          Item {id}
        </div>
      ))}
      <button onClick={() => scrollToItem('c')}>Go to C</button>
    </div>
  );
}

forwardRef#

import { forwardRef, useRef } from 'react';

// Forward ref to child component
interface InputProps {
  label: string;
  placeholder?: string;
}

const FancyInput = forwardRef<HTMLInputElement, InputProps>(
  ({ label, placeholder }, ref) => {
    return (
      <div className="fancy-input">
        <label>{label}</label>
        <input ref={ref} placeholder={placeholder} />
      </div>
    );
  }
);

FancyInput.displayName = 'FancyInput';

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

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

  return (
    <div>
      <FancyInput
        ref={inputRef}
        label="Username"
        placeholder="Enter username"
      />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  );
}

useImperativeHandle#

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

// Define handle type
interface ModalHandle {
  open: () => void;
  close: () => void;
  toggle: () => void;
}

interface ModalProps {
  title: string;
  children: React.ReactNode;
}

const Modal = forwardRef<ModalHandle, ModalProps>(
  ({ title, children }, ref) => {
    const [isOpen, setIsOpen] = useState(false);
    const dialogRef = useRef<HTMLDialogElement>(null);

    // Expose custom methods via ref
    useImperativeHandle(ref, () => ({
      open: () => {
        setIsOpen(true);
        dialogRef.current?.showModal();
      },
      close: () => {
        setIsOpen(false);
        dialogRef.current?.close();
      },
      toggle: () => {
        if (isOpen) {
          dialogRef.current?.close();
        } else {
          dialogRef.current?.showModal();
        }
        setIsOpen(!isOpen);
      },
    }), [isOpen]);

    return (
      <dialog ref={dialogRef}>
        <h2>{title}</h2>
        {children}
        <button onClick={() => dialogRef.current?.close()}>
          Close
        </button>
      </dialog>
    );
  }
);

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

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

Video Player Example#

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

interface VideoPlayerHandle {
  play: () => void;
  pause: () => void;
  seek: (time: number) => void;
  getCurrentTime: () => number;
  getDuration: () => number;
}

interface VideoPlayerProps {
  src: string;
  poster?: string;
}

const VideoPlayer = forwardRef<VideoPlayerHandle, VideoPlayerProps>(
  ({ src, poster }, ref) => {
    const videoRef = useRef<HTMLVideoElement>(null);

    useImperativeHandle(ref, () => ({
      play: () => {
        videoRef.current?.play();
      },
      pause: () => {
        videoRef.current?.pause();
      },
      seek: (time: number) => {
        if (videoRef.current) {
          videoRef.current.currentTime = time;
        }
      },
      getCurrentTime: () => {
        return videoRef.current?.currentTime ?? 0;
      },
      getDuration: () => {
        return videoRef.current?.duration ?? 0;
      },
    }), []);

    return (
      <video
        ref={videoRef}
        src={src}
        poster={poster}
        controls
      />
    );
  }
);

// Usage
function VideoPage() {
  const playerRef = useRef<VideoPlayerHandle>(null);

  const skipForward = () => {
    const current = playerRef.current?.getCurrentTime() ?? 0;
    playerRef.current?.seek(current + 10);
  };

  return (
    <div>
      <VideoPlayer
        ref={playerRef}
        src="/video.mp4"
      />
      <button onClick={() => playerRef.current?.play()}>Play</button>
      <button onClick={() => playerRef.current?.pause()}>Pause</button>
      <button onClick={skipForward}>+10s</button>
    </div>
  );
}

Form Control Example#

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

interface FormHandle {
  submit: () => void;
  reset: () => void;
  validate: () => boolean;
  getValues: () => Record<string, string>;
}

interface FormProps {
  onSubmit: (data: Record<string, string>) => void;
  children: React.ReactNode;
}

const Form = forwardRef<FormHandle, FormProps>(
  ({ onSubmit, children }, ref) => {
    const formRef = useRef<HTMLFormElement>(null);
    const [errors, setErrors] = useState<Record<string, string>>({});

    useImperativeHandle(ref, () => ({
      submit: () => {
        formRef.current?.requestSubmit();
      },
      reset: () => {
        formRef.current?.reset();
        setErrors({});
      },
      validate: () => {
        if (!formRef.current) return false;
        return formRef.current.checkValidity();
      },
      getValues: () => {
        if (!formRef.current) return {};
        const formData = new FormData(formRef.current);
        return Object.fromEntries(formData.entries()) as Record<string, string>;
      },
    }), []);

    const handleSubmit = (e: React.FormEvent) => {
      e.preventDefault();
      if (!formRef.current) return;

      const formData = new FormData(formRef.current);
      const data = Object.fromEntries(formData.entries()) as Record<string, string>;
      onSubmit(data);
    };

    return (
      <form ref={formRef} onSubmit={handleSubmit}>
        {children}
      </form>
    );
  }
);

// Usage
function App() {
  const formRef = useRef<FormHandle>(null);

  const handleSave = () => {
    if (formRef.current?.validate()) {
      formRef.current.submit();
    } else {
      alert('Please fix validation errors');
    }
  };

  return (
    <div>
      <Form ref={formRef} onSubmit={(data) => console.log(data)}>
        <input name="email" type="email" required />
        <input name="password" type="password" required />
      </Form>
      <button onClick={handleSave}>Save</button>
      <button onClick={() => formRef.current?.reset()}>Reset</button>
    </div>
  );
}

Merging Refs#

import { useRef, useCallback, RefCallback, MutableRefObject } from 'react';

// Utility to merge multiple refs
function mergeRefs<T>(
  ...refs: (RefCallback<T> | MutableRefObject<T> | null)[]
): RefCallback<T> {
  return (instance: T) => {
    refs.forEach((ref) => {
      if (typeof ref === 'function') {
        ref(instance);
      } else if (ref != null) {
        ref.current = instance;
      }
    });
  };
}

// Usage with forwardRef
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}

const Button = forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
  const internalRef = useRef<HTMLButtonElement>(null);

  // Use both refs
  const mergedRef = mergeRefs(ref, internalRef);

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

// Hook version
function useMergedRef<T>(...refs: (RefCallback<T> | MutableRefObject<T> | null)[]) {
  return useCallback(
    (instance: T) => {
      refs.forEach((ref) => {
        if (typeof ref === 'function') {
          ref(instance);
        } else if (ref != null) {
          ref.current = instance;
        }
      });
    },
    // eslint-disable-next-line react-hooks/exhaustive-deps
    refs
  );
}

Avoiding Common Pitfalls#

// DON'T: Access ref in render
function Bad() {
  const ref = useRef<HTMLInputElement>(null);

  // ref.current is null during render!
  console.log(ref.current?.value); // undefined

  return <input ref={ref} />;
}

// DO: Access ref in effects or handlers
function Good() {
  const ref = useRef<HTMLInputElement>(null);

  useEffect(() => {
    console.log(ref.current?.value); // Works
  }, []);

  const handleClick = () => {
    console.log(ref.current?.value); // Works
  };

  return <input ref={ref} />;
}

// DON'T: Use refs for reactive data
function BadReactive() {
  const countRef = useRef(0);

  // This won't update the UI!
  const increment = () => {
    countRef.current += 1;
  };

  return <p>{countRef.current}</p>;
}

// DO: Use state for reactive data
function GoodReactive() {
  const [count, setCount] = useState(0);

  const increment = () => {
    setCount(c => c + 1);
  };

  return <p>{count}</p>;
}

Best Practices#

When to Use Refs:
✓ DOM element access (focus, scroll, measure)
✓ Storing timeout/interval IDs
✓ Storing previous values
✓ Imperative animations
✓ Third-party library integration

When NOT to Use Refs:
✗ Data that affects rendering (use state)
✗ Avoiding re-renders (consider memo)
✗ Storing component state
✗ Communication between components

forwardRef:
✓ Use for reusable components
✓ Add displayName for debugging
✓ Document exposed ref API
✓ Consider useImperativeHandle

useImperativeHandle:
✓ Expose minimal API
✓ Hide implementation details
✓ Type the handle interface
✓ Include cleanup in return

Refs provide escape hatches for DOM access and imperative operations. Use useRef for direct element access, forwardRef to pass refs through components, and useImperativeHandle to expose custom APIs. Remember that refs don't trigger re-renders and should be accessed in effects or event handlers.