React useImperativeHandle Hook Guide

The useImperativeHandle hook customizes the instance value exposed when using ref with forwardRef. Here's how to use it.

Basic Usage#

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

interface InputHandle {
  focus: () => void;
  clear: () => void;
}

const CustomInput = forwardRef<InputHandle, { placeholder?: string }>(
  (props, ref) => {
    const inputRef = useRef<HTMLInputElement>(null);

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

    return <input ref={inputRef} placeholder={props.placeholder} />;
  }
);

// Parent component
function Form() {
  const inputRef = useRef<InputHandle>(null);

  const handleSubmit = () => {
    // Use custom methods
    inputRef.current?.clear();
    inputRef.current?.focus();
  };

  return (
    <form onSubmit={handleSubmit}>
      <CustomInput ref={inputRef} placeholder="Enter text" />
      <button type="submit">Submit</button>
    </form>
  );
}

Video Player Control#

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

const VideoPlayer = forwardRef<VideoHandle, { src: string }>((props, 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;
    },
  }));

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

// Usage
function VideoPage() {
  const videoRef = useRef<VideoHandle>(null);

  return (
    <div>
      <VideoPlayer ref={videoRef} src="/video.mp4" />
      <button onClick={() => videoRef.current?.play()}>Play</button>
      <button onClick={() => videoRef.current?.pause()}>Pause</button>
      <button onClick={() => videoRef.current?.seek(0)}>Restart</button>
    </div>
  );
}

Form Component#

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

const ManagedForm = forwardRef<FormHandle, { children: React.ReactNode }>(
  (props, 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: () => {
        const form = formRef.current;
        if (!form) return false;

        const isValid = form.checkValidity();
        if (!isValid) {
          // Collect errors
          const newErrors: Record<string, string> = {};
          Array.from(form.elements).forEach((el) => {
            if (el instanceof HTMLInputElement && !el.validity.valid) {
              newErrors[el.name] = el.validationMessage;
            }
          });
          setErrors(newErrors);
        }
        return isValid;
      },
      getValues: () => {
        const form = formRef.current;
        if (!form) return {};

        const formData = new FormData(form);
        return Object.fromEntries(formData.entries()) as Record<string, string>;
      },
    }));

    return (
      <form ref={formRef} noValidate>
        {props.children}
      </form>
    );
  }
);

Scroll Container#

interface ScrollHandle {
  scrollToTop: () => void;
  scrollToBottom: () => void;
  scrollTo: (position: number) => void;
  getScrollPosition: () => number;
}

const ScrollContainer = forwardRef<ScrollHandle, { children: React.ReactNode }>(
  (props, ref) => {
    const containerRef = useRef<HTMLDivElement>(null);

    useImperativeHandle(ref, () => ({
      scrollToTop: () => {
        containerRef.current?.scrollTo({ top: 0, behavior: 'smooth' });
      },
      scrollToBottom: () => {
        const container = containerRef.current;
        if (container) {
          container.scrollTo({
            top: container.scrollHeight,
            behavior: 'smooth',
          });
        }
      },
      scrollTo: (position: number) => {
        containerRef.current?.scrollTo({ top: position, behavior: 'smooth' });
      },
      getScrollPosition: () => {
        return containerRef.current?.scrollTop ?? 0;
      },
    }));

    return (
      <div ref={containerRef} style={{ overflow: 'auto', height: '400px' }}>
        {props.children}
      </div>
    );
  }
);

interface ModalHandle {
  open: () => void;
  close: () => void;
  toggle: () => void;
}

const Modal = forwardRef<ModalHandle, { title: string; children: React.ReactNode }>(
  (props, ref) => {
    const [isOpen, setIsOpen] = useState(false);
    const dialogRef = useRef<HTMLDialogElement>(null);

    useImperativeHandle(ref, () => ({
      open: () => {
        dialogRef.current?.showModal();
        setIsOpen(true);
      },
      close: () => {
        dialogRef.current?.close();
        setIsOpen(false);
      },
      toggle: () => {
        if (isOpen) {
          dialogRef.current?.close();
        } else {
          dialogRef.current?.showModal();
        }
        setIsOpen(!isOpen);
      },
    }));

    return (
      <dialog ref={dialogRef}>
        <h2>{props.title}</h2>
        {props.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>
  );
}

With Dependencies#

const Counter = forwardRef<{ increment: () => void; getCount: () => number }, {}>(
  (props, ref) => {
    const [count, setCount] = useState(0);

    // Include count in dependencies to keep getCount accurate
    useImperativeHandle(
      ref,
      () => ({
        increment: () => setCount((c) => c + 1),
        getCount: () => count,
      }),
      [count] // Dependency array
    );

    return <div>Count: {count}</div>;
  }
);

Carousel Component#

interface CarouselHandle {
  next: () => void;
  prev: () => void;
  goTo: (index: number) => void;
  getCurrentIndex: () => number;
}

const Carousel = forwardRef<CarouselHandle, { items: React.ReactNode[] }>(
  (props, ref) => {
    const [currentIndex, setCurrentIndex] = useState(0);
    const { items } = props;

    useImperativeHandle(
      ref,
      () => ({
        next: () => {
          setCurrentIndex((i) => (i + 1) % items.length);
        },
        prev: () => {
          setCurrentIndex((i) => (i - 1 + items.length) % items.length);
        },
        goTo: (index: number) => {
          if (index >= 0 && index < items.length) {
            setCurrentIndex(index);
          }
        },
        getCurrentIndex: () => currentIndex,
      }),
      [currentIndex, items.length]
    );

    return (
      <div className="carousel">
        <div className="carousel-item">{items[currentIndex]}</div>
        <div className="carousel-dots">
          {items.map((_, i) => (
            <span
              key={i}
              className={i === currentIndex ? 'active' : ''}
              onClick={() => setCurrentIndex(i)}
            />
          ))}
        </div>
      </div>
    );
  }
);

Accordion Component#

interface AccordionHandle {
  expandAll: () => void;
  collapseAll: () => void;
  toggle: (index: number) => void;
}

const Accordion = forwardRef<AccordionHandle, { items: { title: string; content: React.ReactNode }[] }>(
  (props, ref) => {
    const [expanded, setExpanded] = useState<Set<number>>(new Set());

    useImperativeHandle(ref, () => ({
      expandAll: () => {
        setExpanded(new Set(props.items.map((_, i) => i)));
      },
      collapseAll: () => {
        setExpanded(new Set());
      },
      toggle: (index: number) => {
        setExpanded((prev) => {
          const next = new Set(prev);
          if (next.has(index)) {
            next.delete(index);
          } else {
            next.add(index);
          }
          return next;
        });
      },
    }));

    return (
      <div className="accordion">
        {props.items.map((item, index) => (
          <div key={index} className="accordion-item">
            <button
              onClick={() => {
                setExpanded((prev) => {
                  const next = new Set(prev);
                  next.has(index) ? next.delete(index) : next.add(index);
                  return next;
                });
              }}
            >
              {item.title}
            </button>
            {expanded.has(index) && (
              <div className="accordion-content">{item.content}</div>
            )}
          </div>
        ))}
      </div>
    );
  }
);

Best Practices#

Usage:
✓ Expose minimal API
✓ Use with forwardRef
✓ Include dependencies
✓ Type the handle interface

Patterns:
✓ Media controls (play/pause)
✓ Form methods (submit/reset)
✓ Scroll management
✓ Modal open/close

When to Use:
✓ Imperative actions needed
✓ Hiding internal implementation
✓ Library component APIs
✓ Animation triggers

Avoid:
✗ Exposing entire DOM element
✗ Using for data flow
✗ Complex state management
✗ Replacing props/callbacks

The useImperativeHandle hook creates a clean imperative API for components. Use it with forwardRef to expose specific methods like focus, scroll, or play/pause controls. Keep the exposed interface minimal and prefer declarative patterns when possible. Always include dependencies in the array when the handle methods reference state or props.