React forwardRef Patterns Guide

forwardRef allows components to receive a ref and forward it to a child element. Here's how to use it effectively.

Basic Usage#

import { forwardRef, useRef } from 'react';

// Forward ref to input element
const Input = forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    return <input ref={ref} {...props} />;
  }
);

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

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

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

With Additional Props#

import { forwardRef } from 'react';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', isLoading, children, ...props }, ref) => {
    const className = `btn btn-${variant} btn-${size}`;

    return (
      <button ref={ref} className={className} disabled={isLoading} {...props}>
        {isLoading ? 'Loading...' : children}
      </button>
    );
  }
);

Button.displayName = 'Button';

Composing Components#

import { forwardRef } from 'react';

// Base input component
const BaseInput = forwardRef<HTMLInputElement, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    return <input ref={ref} className="base-input" {...props} />;
  }
);

// Extended input with label
interface LabeledInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  label: string;
  error?: string;
}

const LabeledInput = forwardRef<HTMLInputElement, LabeledInputProps>(
  ({ label, error, id, ...props }, ref) => {
    const inputId = id || label.toLowerCase().replace(/\s+/g, '-');

    return (
      <div className="form-field">
        <label htmlFor={inputId}>{label}</label>
        <BaseInput ref={ref} id={inputId} {...props} />
        {error && <span className="error">{error}</span>}
      </div>
    );
  }
);

With useImperativeHandle#

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

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);

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

  if (!isOpen) return null;

  return (
    <div className="modal-overlay">
      <div className="modal">
        <h2>{title}</h2>
        {children}
        <button onClick={() => setIsOpen(false)}>Close</button>
      </div>
    </div>
  );
});

// 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>
  );
}

Multiple Refs#

import { forwardRef, useRef } from 'react';

interface FormHandle {
  focus: () => void;
  reset: () => void;
  submit: () => void;
}

interface FormProps {
  onSubmit: (data: FormData) => void;
}

const Form = forwardRef<FormHandle, FormProps>(({ onSubmit }, ref) => {
  const formRef = useRef<HTMLFormElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    reset: () => formRef.current?.reset(),
    submit: () => formRef.current?.requestSubmit(),
  }));

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (formRef.current) {
      onSubmit(new FormData(formRef.current));
    }
  };

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      <input ref={inputRef} name="email" type="email" />
      <button type="submit">Submit</button>
    </form>
  );
});

Generic forwardRef#

import { forwardRef, Ref } from 'react';

// Generic list component
interface ListProps<T> {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  className?: string;
}

function ListInner<T>(
  { items, renderItem, className }: ListProps<T>,
  ref: Ref<HTMLUListElement>
) {
  return (
    <ul ref={ref} className={className}>
      {items.map((item, index) => (
        <li key={index}>{renderItem(item, index)}</li>
      ))}
    </ul>
  );
}

// Type assertion needed for generic forwardRef
const List = forwardRef(ListInner) as <T>(
  props: ListProps<T> & { ref?: Ref<HTMLUListElement> }
) => React.ReactElement;

// Usage
function App() {
  const listRef = useRef<HTMLUListElement>(null);
  const items = [{ name: 'Item 1' }, { name: 'Item 2' }];

  return (
    <List
      ref={listRef}
      items={items}
      renderItem={(item) => <span>{item.name}</span>}
    />
  );
}

With Higher-Order Components#

import { forwardRef, ComponentType, Ref } from 'react';

// HOC that adds logging
function withLogging<P extends object>(
  WrappedComponent: ComponentType<P>
) {
  const WithLogging = forwardRef<unknown, P>((props, ref) => {
    console.log('Props:', props);
    return <WrappedComponent {...props} ref={ref} />;
  });

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

  return WithLogging;
}

// HOC that adds styling
function withClassName<P extends { className?: string }>(
  WrappedComponent: ComponentType<P>,
  additionalClassName: string
) {
  return forwardRef<unknown, P>((props, ref) => {
    const className = [props.className, additionalClassName]
      .filter(Boolean)
      .join(' ');

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

Ref Callback Pattern#

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

interface MeasuredBoxProps {
  children: React.ReactNode;
}

const MeasuredBox = forwardRef<HTMLDivElement, MeasuredBoxProps>(
  ({ children }, ref) => {
    const [dimensions, setDimensions] = useState({ width: 0, height: 0 });

    // Combine external ref with measurement
    const measureRef = useCallback(
      (node: HTMLDivElement | null) => {
        if (node) {
          setDimensions({
            width: node.offsetWidth,
            height: node.offsetHeight,
          });
        }

        // Forward to external ref
        if (typeof ref === 'function') {
          ref(node);
        } else if (ref) {
          ref.current = node;
        }
      },
      [ref]
    );

    return (
      <div ref={measureRef}>
        <div>
          Size: {dimensions.width} x {dimensions.height}
        </div>
        {children}
      </div>
    );
  }
);

Input Group Component#

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

interface InputGroupContextValue {
  inputId: string;
  hasError: boolean;
}

const InputGroupContext = createContext<InputGroupContextValue | null>(null);

interface InputGroupProps {
  children: React.ReactNode;
  error?: string;
}

function InputGroup({ children, error }: InputGroupProps) {
  const inputId = useId();

  return (
    <InputGroupContext.Provider value={{ inputId, hasError: !!error }}>
      <div className="input-group">
        {children}
        {error && <span className="error">{error}</span>}
      </div>
    </InputGroupContext.Provider>
  );
}

const InputGroupLabel = ({ children }: { children: React.ReactNode }) => {
  const context = useContext(InputGroupContext);
  return <label htmlFor={context?.inputId}>{children}</label>;
};

const InputGroupInput = forwardRef<
  HTMLInputElement,
  React.InputHTMLAttributes<HTMLInputElement>
>((props, ref) => {
  const context = useContext(InputGroupContext);

  return (
    <input
      ref={ref}
      id={context?.inputId}
      aria-invalid={context?.hasError}
      {...props}
    />
  );
});

// Compound component
InputGroup.Label = InputGroupLabel;
InputGroup.Input = InputGroupInput;

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

  return (
    <InputGroup error="Required field">
      <InputGroup.Label>Email</InputGroup.Label>
      <InputGroup.Input ref={inputRef} type="email" />
    </InputGroup>
  );
}

Best Practices#

Typing:
✓ Use proper generic types
✓ Set displayName for debugging
✓ Type both ref and props
✓ Export prop types

Patterns:
✓ useImperativeHandle for custom APIs
✓ Combine refs when needed
✓ Support ref callbacks
✓ Forward to correct element

Component Design:
✓ Keep ref forwarding simple
✓ Document ref behavior
✓ Consider if ref is needed
✓ Use composition

Avoid:
✗ Forwarding to wrong element
✗ Forgetting displayName
✗ Complex ref logic
✗ Breaking ref contract

forwardRef enables passing refs through components to access DOM elements or expose imperative APIs. Use it with useImperativeHandle for custom ref interfaces, combine with useCallback for measurement patterns, and properly type both the ref and props. Always set displayName for easier debugging in React DevTools. Consider whether a ref is necessary, as declarative patterns often work better.