Mastering useImperativeHandle in React 19

If you have worked with React, you have likely used the useRef hook to manipulate the DOM directly—things like focusing an input, scrolling an element into view, or measuring a div’s dimensions.

The Basics of Refs

To use useRef, we typically define a ref, attach it to a JSX tag, and access the underlying DOM node via the .current property:

const inputRef = useRef(null);

const handleClick = () => {
  // Direct DOM manipulation
  inputRef.current.focus();
};

return <input ref={inputRef} name="username" />;

The Problem: Controlling Custom Components

Directly controlling a standard HTML element is straightforward. But what happens when you create a custom component and want to trigger internal methods from its parent?

Many developers try to solve this by:

1. Lifting state up: Moving the logic to the parent.
2. Context API: Sharing state globally.
3. State Management Libraries: Using Redux or Zustand.

While these work, lifting state up often makes components less reusable. You end up rewriting the same logic in every parent component that uses your custom child.

Enter: useImperativeHandle

This is where useImperativeHandle comes into play. It allows a child component to expose specific “handle” methods to a parent component.

Note for React 19: Previously, we had to wrap our components in forwardRef to pass refs down. In React 19, ref is now passed as a standard prop, making the implementation much cleaner.

Real-World Example: A Custom Modal

Imagine you’ve already built a complex VideoPlayer or Modal component. Later, you realize the parent needs to “Reset” or “Play” that component remotely. Instead of refactoring the entire state structure, you can use useImperativeHandle.

The Child Component

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

const FancyInput = ({ ref }) => {
  const inputRef = useRef();

  // We define exactly what the parent is allowed to see/do
  useImperativeHandle(ref, () => {
    return {
      focusAndClear: () => {
        inputRef.current.focus();
        inputRef.current.value = "";
      },
      shake: () => {
        console.log("Shaking the input for attention!");
      }
    };
  }, []);

  return <input ref={inputRef} type="text" placeholder="Type here..." />;
};

export default FancyInput;

The Parent Component

import React, { useRef } from 'react';
import FancyInput from './FancyInput';

const Parent = () => {
  const customRef = useRef(null);

  return (
    <div>
      <FancyInput ref={customRef} />

      <button onClick={() => customRef.current.focusAndClear()}>
        Focus and Clear Child
      </button>

      <button onClick={() => customRef.current.shake()}>
        Shake Child
      </button>
    </div>
  );
};

Why Use This Instead of Refactoring?

useImperativeHandle is a “clutch” tool for a few reasons:

1. Reusability: The logic for “how to shake” or “how to reset” stays inside the component that owns the UI.
2. Time-Saving: If you realize late in the development cycle that a method should be triggered by the parent, you don’t have to lift every single state variable and method. You can simply “export” the necessary methods via the handle.
3. Encapsulation: You don’t expose the entire DOM node to the parent—only the specific functions you want the parent to use.

Conclusion

While you should still prefer props and state for most data flows in React, useImperativeHandle is a powerful escape hatch for imperative logic. It keeps your components clean, encapsulated, and easy to control from the outside without the headache of massive refactors.