forwardRef & useImperativeHandle

Reviewed & published by Brayan K

forwardRef is a React technique that lets a parent pass a ref through a custom component down to a real DOM node inside it, and useImperativeHandle lets that component expose a small set of imperative methods — like focus() or scrollTo() — instead of the raw node. Together they give a parent controlled, imperative access to a child.

Part of the free React course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn

• What a ref's .current holds and why it isn't forwarded by default
• Passing a ref to a child DOM node with forwardRef
• Exposing a custom API with useImperativeHandle
• When a ref beats a prop (focus, scroll, measure)
• Keeping the exposed API small and intentional
• How React 19 turns ref into a normal prop

1️⃣ Refs Hold a Node You Can Command

A ref created with useRef(null) is just an object with a mutable .current. Attach it to a DOM element and React fills .current with that node, letting you call imperative methods like focus(). The catch: pass that ref to your own component and it doesn't reach the inner node automatically.

function Form() {
  const inputRef = useRef(null);
  function handleClick() {
    inputRef.current.focus();        // command the DOM node
  }
  return (
    <>
      <input ref={inputRef} />         
      <button onClick={handleClick}>Focus</button>
    </>
  );
}

// A ref is a box with a .current property React fills in for you.
// For a DOM node, ref.current becomes that element so you can call
// imperative methods on it (focus, scrollTo, play...).
// We mock a DOM node so you can see the shape:

const inputRef = { current: null };

const fakeInputNode = {
  value: "",
  focus() { console.log("input focused!"); },
  select() { console.log("text selected!"); },
};

inputRef.current = fakeInputNode;   // React assigns the node here

inputRef.current.focus();           // input focused!
inputRef.current.select();          // text selected!
console.log("has node:", inputRef.current !== null);  // true

2️⃣ forwardRef — Send the Ref Down

Wrap your component in forwardRef so it receives a second argument, ref, after props. Attach that ref to the inner element you want the parent to control. Now <TextInput ref={myRef} /> gives the parent the underlying <input>.

const TextInput = forwardRef(function TextInput(props, ref) {
  return <input ref={ref} placeholder={props.label} />;
});

// Parent can now focus the inner input:
function Parent() {
  const ref = useRef(null);
  return <TextInput ref={ref} label="Email" />;
}

// forwardRef passes the parent's ref DOWN to a chosen inner node.
// We model it: the component receives (props, ref) and attaches the
// ref to the node it wants the parent to control.

function forwardRef(render) {
  return function (props, ref) { return render(props, ref); };
}

const TextInput = forwardRef(function (props, ref) {
  const node = { focus() { console.log("focused", props.label); } };
  ref.current = node;             // attach ref to the inner node
  return "<input> for " + props.label;
});

const myRef = { current: null };
TextInput({ label: "Email" }, myRef);
myRef.current.focus();            // focused Email

3️⃣ useImperativeHandle — Expose a Small API

Often you don't want to hand the parent the raw node — you want a deliberate, minimal API. Inside the forwarded component, call useImperativeHandle(ref, () => ({ ... })) to define exactly which methods ref.current exposes. The parent sees only focus() and clear(), not the whole DOM node.

const FancyInput = forwardRef(function FancyInput(props, ref) {
  const innerRef = useRef(null);
  useImperativeHandle(ref, () => ({
    focus() { innerRef.current.focus(); },
    clear() { innerRef.current.value = ""; },
  }));
  return <input ref={innerRef} />;
});
// Parent: ref.current.focus();  ref.current.clear();

// 🎯 YOUR TURN — fill in each ___ then press "Try it Yourself".
// useImperativeHandle exposes a CUSTOM api on the parent's ref.
// Expose focus() and clear(); hide everything else.

const ref = { current: null };
let value = "hello";

function useImperativeHandle(targetRef, createHandle) {
  targetRef.current = createHandle();    // attach the custom api
}

useImperativeHandle(ref, () => ({
  focus() { console.log("focused"); },
  clear() { value = ___; console.log("cleared:", value); },  // 👉 ""
}));

ref.current.focus();                     // focused
ref.current.clear();                     // cleared:
console.log("can call scrollTo?", typeof ref.current.scrollTo);  // undefined

// ✅ Expected output:
//    focused
//    cleared:
//    undefined

🧩 Reorder Challenge

These lines build a forwarded input that exposes a custom API. Put them in the right order:

A.   useImperativeHandle(ref, () => ({
B.   const FancyInput = forwardRef(function (props, ref) {
C.   const innerRef = useRef(null);
D.   focus() { innerRef.current.focus(); } }));
E.   return <input ref={innerRef} />;

Common Errors (and the fix)

• ref.current is null. — You passed a ref to a custom component without forwardRef (in React 18-). Wrap the component so the ref reaches a real node.
• Exposing the whole DOM node. — Then parents poke at internals freely. Use useImperativeHandle to expose only the methods you intend.
• Reaching for a ref when a prop would do. — Refs are for imperative actions. If state/props can express it, prefer the declarative path.
• Reading ref.current during render. — It isn't set yet. Use it inside effects or event handlers, not in the render body.

📋 Quick Reference

🧠 Quick Recall

1. Why doesn't a ref reach your custom component's input by default?

ref is special and isn't forwarded like other props. Wrap with forwardRef (React 18-) so it reaches the inner node.

2. What does useImperativeHandle control?

Exactly which methods ref.current exposes, instead of the raw DOM node — a small, intentional API.

3. When is a ref the right call over a prop?

For imperative actions like focus, scroll, select, play, or measuring the DOM — things props can't naturally express.

Mini-Challenge: Expose an Imperative API

Build the handle a component would attach to a forwarded ref — just focus and scrollToTop — then call both. Run it and check your output.

// 🎯 MINI-CHALLENGE: expose a small imperative API
//
// Build createHandle() that returns an object with:
//   - focus()       -> logs "focus"
//   - scrollToTop() -> logs "scroll 0"
// Attach it to ref.current, then call BOTH methods.
//
// ✅ Expected output:
//    focus
//    scroll 0

const ref = { current: null };

// your code here

🎉 Lesson Complete

• ✅ A ref's .current holds a node you can command imperatively
• ✅ forwardRef passes a parent's ref to a chosen inner node
• ✅ useImperativeHandle exposes a small, intentional API
• ✅ Prefer props; use refs only for focus/scroll/measure and similar

Practice quiz

Continue this course

• Previous: useSyncExternalStore
• Next: Compound Components Pattern — Share implicit state via context for flexible APIs like <Tabs><Tab/></Tabs>
• Quick reference: React cheat sheet

Frequently asked questions

Why doesn't passing a ref to my custom component work by default?

ref is a special prop React handles itself, so it isn't forwarded to your inner DOM node automatically. In React 18 and earlier you wrap the component in forwardRef so the ref reaches the element you choose, like the underlying <input>.

What does useImperativeHandle do?

It lets a component expose a custom set of methods to its parent's ref instead of the raw DOM node. The parent calls ref.current.focus() or ref.current.scrollToTop(), and you decide exactly what those methods do — a small, deliberate imperative API.

When should I use a ref instead of props?

Props are for data and declarative behavior. Reach for a ref only for imperative actions that don't fit state: focusing an input, selecting text, scrolling, playing media, or measuring the DOM. If a prop can express it, prefer the prop.

Did React 19 change forwardRef?

Yes. In React 19 a function component can receive ref as a normal prop, so many cases no longer need forwardRef. useImperativeHandle still exists for exposing a custom API. forwardRef remains valid and is everywhere in existing code, so it's important to recognize.