Why useImperativeHandle is needed in React

React~5 min read

useImperativeHandle is a React hook that lets you define exactly what a parent component can access through a ref on a child component, instead of exposing the entire DOM node.

Theory

TL;DR

Think of it as a controlled escape hatch: React data normally flows down via props, but this lets a parent call child methods directly
Without it, a ref on a child gives the parent access to everything on the DOM node. With it, you define a public API
Always pair with forwardRef; the ref parameter is undefined without it
Use it when the parent needs to trigger actions (focus(), reset(), scrollToTop()), not read state
Decision rule: if you're reaching for ref.current.internalState, you probably need useImperativeHandle instead

Quick example

jsx

// Child exposes only what the parent needs
const Input = forwardRef((props, ref) => {
  const inputRef = useRef();

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

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

// Parent can only call focus() and clear()
const Parent = () => {
  const inputRef = useRef();
  return (
    <>
      <Input ref={inputRef} />
      <button onClick={() => inputRef.current.focus()}>Focus</button>
      <button onClick={() => inputRef.current.clear()}>Clear</button>
    </>
  );
};

The parent can call focus() and clear(), and nothing else. It can't accidentally call inputRef.current.removeChild() or read internal DOM properties.

Why this matters: encapsulation

Without useImperativeHandle, attaching a ref to a child gives the parent direct access to the DOM node. Every property, every method, every internal detail is exposed. That's fine for a plain <input> tag, but not for a component with its own state and logic.

useImperativeHandle puts you back in control. You decide what gets exposed. The parent gets a clean API. You can refactor the internals later without breaking anything the parent depends on.

How it works internally

useImperativeHandle(ref, createHandle, deps) stores the object returned by createHandle() on ref.current. When the dependency array changes, React calls createHandle() again and replaces the stored value. The ref itself is just { current: someValue }. No magic, just controlled assignment to a mutable container.

When to use

Parent needs to call imperative methods on a child (focus(), reset(), play(), validate())
Child manages complex internal state the parent shouldn't touch directly
Wrapping third-party libraries (video players, date pickers, rich text editors) where the library's own API is imperative by design
Building reusable components that need a controlled, stable external interface

Skip it when you just need to pass data down. Props handle that. Skip it for toggling visibility or triggering animations too; state and CSS transitions are cleaner there.

Common mistakes

Mistake 1: Exposing too much

jsx

// Wrong - parent can now mutate internals directly
useImperativeHandle(ref, () => ({
  inputRef,       // raw DOM access leaks out
  internalState,  // parent can break your component's logic
  _privateMethod
}));

// Right - expose only the public API
useImperativeHandle(ref, () => ({
  focus: () => inputRef.current.focus(),
  getValue: () => inputRef.current.value
}));

If you expose inputRef directly, the parent can call inputRef.current.removeChild(). If you refactor the component later, any parent code touching those internals breaks.

Mistake 2: Missing dependencies, causing stale closures

jsx

const [count, setCount] = useState(0);

// Wrong - getCount() always returns 0
useImperativeHandle(ref, () => ({
  getCount: () => count
})); // no dependency array

// Right
useImperativeHandle(ref, () => ({
  getCount: () => count
}), [count]);

The method runs fine, returns a value, and throws no error. But it's a stale closure. Debugging takes time because there's no signal that anything is wrong, just wrong data.

Mistake 3: Using it for state that belongs in props

jsx

// Wrong - imperative modal control
const Modal = forwardRef((props, ref) => {
  const [isOpen, setIsOpen] = useState(false);
  useImperativeHandle(ref, () => ({
    open: () => setIsOpen(true),
    close: () => setIsOpen(false)
  }));
  return isOpen ? <div>Modal</div> : null;
});

// Right - controlled component
const Modal = ({ isOpen, onClose }) => (
  isOpen ? <div>Modal <button onClick={onClose}>X</button></div> : null
);

The imperative version makes the parent harder to reason about. State is scattered across imperative calls. Time-travel debugging breaks. If the parent should control visibility, it should be a prop.

Mistake 4: Not wrapping with forwardRef

jsx

// Wrong - ref parameter is undefined
const Input = (props, ref) => {
  useImperativeHandle(ref, () => ({ focus: () => {} }));
  return <input />;
};

// Right
const Input = forwardRef((props, ref) => {
  useImperativeHandle(ref, () => ({ focus: () => {} }));
  return <input />;
});

Without forwardRef, functional components don't receive ref as a second parameter. It's undefined, and useImperativeHandle has nothing to attach to.

Mistake 5: Calling it conditionally

jsx

// Wrong - breaks rules of hooks
const Input = forwardRef((props, ref) => {
  if (props.disabled) {
    useImperativeHandle(ref, () => ({}));
  }
  return <input />;
});

// Right - always call, adjust what you expose
const Input = forwardRef((props, ref) => {
  useImperativeHandle(ref, () => ({
    focus: props.disabled ? undefined : () => inputRef.current.focus()
  }));
  return <input />;
});

React tracks hooks by call order. A conditional call causes a "Hooks called in different order" error.

Real-world usage

React Hook Form - exposes focus(), setValue() on field refs for imperative validation
Material-UI - TextField and Dialog expose imperative methods via refs
Framer Motion - animation controls exposed via refs for play/pause/seek
Monaco Editor - getValue(), setValue(), layout() on the editor ref
Video and audio players - play(), pause(), seek() are inherently imperative
Rich text editors - focus(), getContent(), setContent() via refs

I've seen teams reach for useImperativeHandle when a simpler callback prop would solve the problem. Before using it, check whether the parent could just pass an onValidate callback down instead.

Follow-up questions

Q: Why not just use a ref directly on the DOM element?

A: You can, but then the parent accesses everything on the DOM node. useImperativeHandle lets you add custom logic to the exposed methods, like triggering analytics or validating before focusing, and hides internals the parent shouldn't touch.

Q: Can you use useImperativeHandle without forwardRef?

A: No. Without forwardRef, the ref parameter is undefined in functional components. The hook has nothing to attach to.

Q: If an exposed method updates state in the child, does the parent re-render?

A: No. The parent doesn't re-render unless its own state changes. The child re-renders because the state update is inside it. The parent only sees updated data if it calls another method to read it afterward.

Q (senior-level): You have a form with 10 fields, each using useImperativeHandle to expose validate(). The parent calls all 10 in a loop on submit. What performance problem can this cause, and how do you fix it?

A: Each validate() call may trigger a state update in the field, causing up to 10 separate re-renders. Fix it by batching updates with flushSync, or collect validation results without touching state (store in a ref, then update state once after all checks). The better fix: use React Hook Form or Formik, which handle this without imperative refs.

Examples

Custom input with focus and clear

jsx

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

const CustomInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

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

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

export default function App() {
  const ref = useRef(null);

  return (
    <div>
      <CustomInput ref={ref} placeholder="Type here" />
      <button onClick={() => ref.current.focus()}>Focus</button>
      <button onClick={() => ref.current.clear()}>Clear</button>
    </div>
  );
}

ref.current has only focus and clear. The parent can't reach the DOM node directly, can't call .remove(), can't read .offsetHeight. The API surface is exactly what you chose.

Form validation with multiple fields

jsx

const FormField = forwardRef(({ name, validate }, ref) => {
  const [value, setValue] = useState('');
  const [error, setError] = useState('');

  useImperativeHandle(ref, () => ({
    getValue: () => value,
    validate: () => {
      const err = validate(value);
      setError(err);
      return !err; // returns true if valid
    },
    reset: () => {
      setValue('');
      setError('');
    }
  }), [value, validate]); // deps keep methods fresh

  return (
    <div>
      <input value={value} onChange={(e) => setValue(e.target.value)} />
      {error && <span className="error">{error}</span>}
    </div>
  );
});

const Form = () => {
  const emailRef = useRef();
  const passwordRef = useRef();

  const handleSubmit = () => {
    const emailOk = emailRef.current.validate();
    const passwordOk = passwordRef.current.validate();
    if (emailOk && passwordOk) {
      console.log('Submitting...');
    }
  };

  return (
    <>
      <FormField
        ref={emailRef}
        name="email"
        validate={(v) => v.includes('@') ? '' : 'Invalid email'}
      />
      <FormField
        ref={passwordRef}
        name="password"
        validate={(v) => v.length >= 8 ? '' : 'Min 8 chars'}
      />
      <button onClick={handleSubmit}>Submit</button>
    </>
  );
};

Each field manages its own state and validation logic. The parent calls validate() and gets a boolean. No internal state leaks out. The dependency array [value, validate] keeps the exposed methods in sync with current values.

Stale closure edge case

jsx

const VideoPlayer = forwardRef((props, ref) => {
  const [isPlaying, setIsPlaying] = useState(false);
  const videoRef = useRef();

  // Wrong: no deps, getStatus() always returns false
  useImperativeHandle(ref, () => ({
    play: () => {
      videoRef.current.play();
      setIsPlaying(true);
    },
    getStatus: () => isPlaying // captured stale value
  }));

  // Right: include isPlaying so the method always reads current value
  useImperativeHandle(ref, () => ({
    play: () => {
      videoRef.current.play();
      setIsPlaying(true);
    },
    getStatus: () => isPlaying
  }), [isPlaying]);

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

With the wrong version, player.current.getStatus() returns false even after calling play(). The method runs, returns a value, no error is thrown. That's exactly what makes stale closures hard to catch in code review.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.

Finished reading?