React useImperativeHandle Hook – Complete Notes

The useImperativeHandle Hook is a built-in React Hook that allows a child component to customize the methods and values it exposes to its parent component through a ref. It is useful when a parent needs to trigger a specific action inside a child component, such as focusing an input field, scrolling to an element, selecting text, or controlling an animation.

Official Documentation: React useImperativeHandle Documentation

1. What Is useImperativeHandle?

useImperativeHandle is a React Hook used to customize the handle exposed by a component through a ref. Instead of giving the parent component access to the entire DOM element or internal implementation, the child can expose only selected methods.

For example, a custom input component can expose a focus() method so that the parent can focus the input without directly accessing the underlying DOM element.

Simple Definition

useImperativeHandle lets a child component decide which methods or values a parent component can access through a ref.

Why Is It Used?

• To expose selected methods from a child component.
• To allow a parent component to trigger specific child actions.
• To limit direct access to a child component's internal DOM elements.
• To build reusable components with a controlled public API.
• To support imperative actions such as focusing, scrolling, and selecting text.

2. Syntax of useImperativeHandle

useImperativeHandle(ref, createHandle, dependencies);

Parameters

Return Value

The useImperativeHandle Hook itself returns undefined. React assigns the value returned by createHandle to the provided ref.

3. How useImperativeHandle Works

1. The parent component creates a ref using useRef().
2. The parent passes the ref to the child component.
3. The child uses useImperativeHandle() to define which methods should be exposed.
4. The parent calls the exposed methods using ref.current.
5. The child performs the requested action.

Basic Flow

Parent Component
       |
       | Creates a ref
       v
Passes ref to Child Component
       |
       v
Child uses useImperativeHandle()
       |
       v
Exposes selected methods
       |
       v
Parent calls ref.current.method()
       |
       v
Child performs the action

4. Basic Example: Exposing a Focus Method

This example demonstrates how a parent component can focus an input field inside a child component by calling a method exposed through useImperativeHandle.

Child Component: CustomInput.jsx

import { useRef, useImperativeHandle } from "react";

export default function CustomInput({ ref }) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus() {
      inputRef.current?.focus();
    }
  }), []);

  return (
    <input
      ref={inputRef}
      type="text"
      placeholder="Enter your name"
    />
  );
}

Parent Component: App.jsx

import { useRef } from "react";
import CustomInput from "./CustomInput";

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

  function handleFocus() {
    inputRef.current?.focus();
  }

  return (
    <div>
      <h2>useImperativeHandle Example</h2>
      <CustomInput ref={inputRef} />
      <button onClick={handleFocus}>
        Focus Input
      </button>
    </div>
  );
}

Explanation

• useRef(null) creates a ref in the parent and another ref for the actual input element.
• inputRef inside the child points to the real HTML input element.
• useImperativeHandle() exposes only the focus() method to the parent.
• When the button is clicked, inputRef.current.focus() is invoked through the exposed handle.
• The parent does not receive direct access to the input DOM node; it receives an object containing the selected method.

Important: This example uses React 19 syntax, where a function component can receive ref as a prop.

5. Using useImperativeHandle with React 18 and Earlier

In React 18 and earlier, function components generally use forwardRef() to receive a ref from their parent. The following example is compatible with the traditional React 18 approach.

Child Component: CustomInput.jsx

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

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

  useImperativeHandle(ref, () => ({
    focus() {
      inputRef.current?.focus();
    },
    clear() {
      if (inputRef.current) {
        inputRef.current.value = "";
      }
    }
  }), []);

  return (
    <input
      ref={inputRef}
      type="text"
      placeholder="Enter text"
    />
  );
});

export default CustomInput;

Parent Component: App.jsx

import { useRef } from "react";
import CustomInput from "./CustomInput";

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

  return (
    <div>
      <CustomInput ref={inputRef} />
      <button onClick={() => inputRef.current?.focus()}>
        Focus
      </button>
      <button onClick={() => inputRef.current?.clear()}>
        Clear
      </button>
    </div>
  );
}

Note: In React 19, forwardRef is no longer necessary for this particular purpose because function components can receive ref as a prop. Existing React 18 code can continue using forwardRef.

6. Understanding the Dependencies Array

The third argument of useImperativeHandle is an optional dependencies array. It determines when React recreates the exposed handle.

Example

useImperativeHandle(ref, () => ({
  showMessage() {
    console.log(message);
  }
}), [message]);

Here, message is a reactive value used by the exposed method. Including it in the dependencies array allows React to update the handle when the value changes.

Always include the reactive values used by the handle creation function. React compares dependencies using Object.is.

7. Example: Exposing Multiple Methods

A child component can expose more than one method through a single imperative handle.

Child Component

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

const TextBox = forwardRef(function TextBox(props, ref) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus() {
      inputRef.current?.focus();
    },
    clear() {
      if (inputRef.current) {
        inputRef.current.value = "";
      }
    },
    selectText() {
      inputRef.current?.select();
    }
  }), []);

  return <input ref={inputRef} placeholder="Type something" />;
});

export default TextBox;

Parent Component

import { useRef } from "react";
import TextBox from "./TextBox";

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

  return (
    <div>
      <TextBox ref={textBoxRef} />
      <button onClick={() => textBoxRef.current?.focus()}>
        Focus
      </button>
      <button onClick={() => textBoxRef.current?.clear()}>
        Clear
      </button>
      <button onClick={() => textBoxRef.current?.selectText()}>
        Select Text
      </button>
    </div>
  );
}

Methods Exposed

• focus() places the cursor in the input.
• clear() clears the input's current DOM value.
• selectText() selects the text inside the input.

For a controlled input whose value comes from React state, update that state to clear the field rather than changing only the DOM value. Otherwise, React may restore the state-controlled value on a later render.

8. Practical Example: Scroll to a Section

useImperativeHandle can expose a custom method that scrolls a child component into view.

Child Component

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

const DetailsSection = forwardRef(function DetailsSection(props, ref) {
  const sectionRef = useRef(null);

  useImperativeHandle(ref, () => ({
    scrollToSection() {
      sectionRef.current?.scrollIntoView({
        behavior: "smooth",
        block: "start"
      });
    }
  }), []);

  return (
    <section ref={sectionRef} style={{ marginTop: "600px" }}>
      <h2>Details Section</h2>
      <p>You have reached the details section.</p>
    </section>
  );
});

export default DetailsSection;

Parent Component

import { useRef } from "react";
import DetailsSection from "./DetailsSection";

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

  return (
    <div>
      <button onClick={() => detailsRef.current?.scrollToSection()}>
        View Details
      </button>
      <DetailsSection ref={detailsRef} />
    </div>
  );
}

When the parent clicks the button, it calls the child's exposed scrollToSection() method, which scrolls the section into view smoothly.

9. useImperativeHandle vs useRef

10. useImperativeHandle vs useEffect

11. Rules of useImperativeHandle

• Call the Hook at the top level of a function component or another custom Hook, not inside loops, conditions, or nested functions.
• Pass the ref that should receive the custom handle.
• Return the methods or values you want the parent to access.
• Provide all required reactive dependencies in the dependencies array.
• Use optional chaining, such as ref.current?.focus(), when the ref may not yet be available.
• In React 18 and earlier, use forwardRef to receive the parent's ref in a function component.
• In React 19, a function component can receive ref as a prop.
• Avoid exposing internal DOM elements or methods that the parent does not need.

12. Advantages of useImperativeHandle

• Controlled access: Exposes only selected methods instead of the entire DOM node.
• Encapsulation: Keeps implementation details inside the child component.
• Reusability: Makes reusable input fields, dialogs, and custom widgets easier to control.
• Convenience: Allows a parent to trigger imperative actions without duplicating child logic.
• Custom API: Lets components expose meaningful methods such as focus(), clear(), or scrollToSection().

13. Limitations and Common Mistakes

• Overusing refs: Do not use imperative methods when props and state can express the behavior clearly.
• Incorrect dependencies: Missing reactive dependencies can cause exposed methods to use outdated values.
• Accessing null refs: Calling a method before a ref is assigned can cause an error. Check that the ref is available.
• Incorrect React version syntax: Passing ref directly as a prop to a function component is supported in React 19; React 18 and earlier generally require forwardRef.
• Changing controlled DOM values: Updating an input's DOM value directly may conflict with React state.
• Exposing too much: Return only the methods the parent genuinely needs.

Best practice: Prefer declarative props for ordinary UI behavior. Use useImperativeHandle for specific imperative operations such as focusing, scrolling, selecting text, or triggering an animation.

14. Real-World Use Cases

15. Interview Questions and Answers

Q1. What is useImperativeHandle in React?

Answer: It is a React Hook that customizes the value exposed through a ref, allowing a child component to expose selected methods or values to its parent.

Q2. Why do we use useImperativeHandle?

Answer: It is used when a parent needs to trigger a specific imperative action inside a child component, such as focusing an input or scrolling to a section.

Q3. What are the parameters of useImperativeHandle?

Answer: It accepts a ref, a function that returns the custom handle, and an optional dependencies array.

Q4. Does useImperativeHandle return a value?

Answer: The Hook returns undefined. React assigns the value returned by the handle creation function to the supplied ref.

Q5. What is the role of forwardRef?

Answer: In React 18 and earlier, forwardRef lets a function component receive a ref from its parent. React 19 allows a function component to receive ref as a prop, so forwardRef is no longer necessary for that purpose.

Q6. Can useImperativeHandle expose multiple methods?

Answer: Yes. The handle creation function can return an object containing multiple methods, such as focus(), clear(), and selectText().

Q7. Is useImperativeHandle needed for every component?

Answer: No. It is intended for specific imperative use cases. Prefer props and state whenever they can describe the required behavior declaratively.

Q8. What happens when the dependencies change?

Answer: React recreates the handle when a dependency changes according to Object.is comparison and assigns the new handle to the ref.

Q9. What is the difference between useRef and useImperativeHandle?

Answer: useRef creates a ref object for storing a value or referencing a DOM node, whereas useImperativeHandle customizes the handle exposed through a ref.

Q10. What should you avoid when using useImperativeHandle?

Answer: Avoid exposing unnecessary internal details, omitting reactive dependencies, calling methods when the ref is unavailable, and using imperative refs for behavior that can be expressed through props.

16. Practice Exercises

1. Create a custom input component that exposes a focus() method.
2. Add a clear() method to a reusable text field.
3. Create a child component that exposes a scrollToSection() method.
4. Build a custom text box that exposes focus(), clear(), and selectText().
5. Implement the same custom input using React 19 ref-as-prop syntax and React 18 forwardRef syntax.

17. Quick Revision Checklist

• Understand what useImperativeHandle does.
• Know the syntax and all three parameters.
• Understand the relationship between useRef, forwardRef, and useImperativeHandle.
• Know the difference between React 19 and React 18 ref handling.
• Practice exposing custom methods from child components.
• Understand dependency management and common mistakes.
• Prefer declarative props and state when possible.

18. React JS Training Resources

Learn more about React JS concepts, Hooks, component development, and practical application building through the following resources.

• JustAcademy React JS Training Course – Explore React JS training and course details.
• Register for React JS Course Demo – Register for a course demonstration.
• Official React useImperativeHandle Documentation – Review the Hook's API and examples.
• Official React forwardRef Documentation – Learn about forwarding refs in React.

19. Conclusion

The useImperativeHandle Hook provides a controlled way for child components to expose selected methods through refs. It is especially useful for reusable inputs, scrolling behavior, text selection, and integrations with imperative APIs. Understand how it works with useRef and the ref-handling differences between React 19 and React 18 and earlier. Use it selectively, keeping most application behavior declarative through props and state.