React: useImperativeHandle

Data in React flows strictly downwards via props. If a parent component needs to trigger an action inside a child component, the standard approach is to pass down a boolean prop (e.g., isOpen={true}).

But what if you are building a complex <Modal /> component, and you want the parent to explicitly call a modalRef.current.open() function, rather than managing boolean state?

How can a child component expose specific, custom methods directly to a parent component?

The answer is combining forwardRef with the useImperativeHandle hook.

1. The Danger of Exposing Raw DOM Nodes

As discussed in the forwardRef documentation, wrapping a component in React.forwardRef allows you to pass a ref down to a child's raw DOM element.

const CustomInput = forwardRef((props, ref) => {
  return <input ref={ref} className="beautiful-input" />;
});

The problem is that the parent component now has total control over the raw <input /> node. The parent could easily reach in and do inputRef.current.style.display = 'none', completely breaking the child component's encapsulation and design system.

2. Taking Control with useImperativeHandle

Instead of handing the parent the raw DOM node, we can intercept the ref using useImperativeHandle and return a custom object instead. This object will only contain the specific methods we want the parent to have access to.

Example: A Controllable Modal

Let's build a Modal that manages its own isOpen state internally, but allows the parent to trigger the open/close actions.

import { useState, useImperativeHandle, forwardRef, useRef } from 'react';
 
// 1. Wrap the child in forwardRef
const Modal = forwardRef((props, ref) => {
  // Modal manages its own state!
  const [isOpen, setIsOpen] = useState(false);
 
  // 2. Define the custom API exposed to the parent
  useImperativeHandle(ref, () => {
    return {
      // The parent can call these methods via the ref!
      open: () => setIsOpen(true),
      close: () => setIsOpen(false),
      
      // We can even return internal data
      isCurrentlyOpen: isOpen 
    };
  }, [isOpen]); // Optional dependency array, similar to useEffect
 
  if (!isOpen) return null;
 
  return (
    <div className="modal">
      <h2>{props.title}</h2>
      <button onClick={() => setIsOpen(false)}>Close Inside</button>
    </div>
  );
});

Using the Custom Ref in the Parent

Now, look at how clean the Parent component is. It doesn't need to track the isOpen state at all!

function App() {
  // 3. Create the ref in the parent
  const modalRef = useRef(null);
 
  const handleOpenClick = () => {
    // 4. Call the custom methods exposed by useImperativeHandle!
    modalRef.current.open();
  };
 
  return (
    <div>
      <button onClick={handleOpenClick}>Open Modal From Parent</button>
      
      <Modal ref={modalRef} title="Terms of Service" />
    </div>
  );
}

3. When to use this pattern

Generally, you should stick to standard unidirectional data flow (passing state down as props). However, useImperativeHandle is highly recommended in Library Design.

If you are authoring a UI library for other developers, you want your components (like Modals, Carousels, or Video Players) to be deeply encapsulated. Forcing developers to manage complex state just to pause a <VideoPlayer /> is bad developer experience (DX). Exposing a clean playerRef.current.pause() API using useImperativeHandle creates a robust, foolproof interface.

Senior-Level Interview Answer

While React favors declarative, state-driven, unidirectional data flow, there are architectural scenarios—particularly when authoring generic UI libraries or wrapping imperative APIs like HTML5 Video—where a parent component needs imperative control over a child. By default, React.forwardRef exposes a child's raw underlying DOM node, which violates encapsulation and allows the parent to unsafely mutate styles or attributes. The useImperativeHandle hook resolves this by allowing the child component to intercept the forwarded ref and substitute the DOM node with a custom object. This pattern strictly restricts the parent's access to a predefined API contract (e.g., exposing only a .focus() or .play() method), preserving the child's internal state encapsulation while still affording the parent necessary imperative triggers.