On this page
12. What is forwardRef and how did React 19 change it?
- How do you pass a ref to a child component?
- What is useImperativeHandle?
- Is forwardRef deprecated?
Short answer
forwardRef lets a function component receive a ref from its parent and pass it on to a DOM element inside it, so the parent can call focus(), measure the element or scroll to it. Before React 19, ref was a special prop that function components could not read, so forwardRef was required. In React 19, ref is a normal prop for function components: you just destructure it, and forwardRef is no longer needed (it still works, but will be deprecated).
Explanation
Refs give you direct access to a DOM node. By default a component's DOM is private: a parent cannot reach into a child's <input>. Design-system components like <TextInput> or <Button> often need to expose their inner element so parents can manage focus, which matters for accessibility and form libraries.
Before React 19
const TextInput = forwardRef(function TextInput(props, ref) {
return <input ref={ref} {...props} />;
});
React 19
function TextInput({ ref, ...props }) {
return <input ref={ref} {...props} />;
}
Exposing less than the whole node: useImperativeHandle
Sometimes you don't want the parent to have the full DOM node. useImperativeHandle lets you pick which methods the parent gets, which keeps the component's internals private.
Example
import { useImperativeHandle, useRef } from "react";
// React 19: `ref` arrives as a normal prop.
function SearchBox({ ref, ...props }) {
const inputRef = useRef(null);
// Parent gets only focus() and clear(), not the raw <input>.
useImperativeHandle(ref, () => ({
focus: () => inputRef.current.focus(),
clear: () => {
inputRef.current.value = "";
},
}));
return <input ref={inputRef} type="search" {...props} />;
}
export default function Toolbar() {
const searchRef = useRef(null);
return (
<>
<SearchBox ref={searchRef} placeholder="Search" />
<button onClick={() => searchRef.current.focus()}>Focus search</button>
<button onClick={() => searchRef.current.clear()}>Clear</button>
</>
);
}
Common mistakes
- In React 18 or earlier, passing
refto a plain function component and gettingnullplus a warning. Wrap it inforwardRef(or rename the prop, such asinputRef). - Using refs to do what props can do, like
ref.current.open()instead of anisOpenprop. Refs are an escape hatch for focus, measurement, scrolling and third-party libraries. - Reading
ref.currentduring render. It isnullon the first render and not tracked by React; read it in effects or event handlers. - Forgetting
displayNamefor anonymousforwardRefcomponents, which then show up asForwardRefin DevTools. A named inner function fixes it.
Follow-up questions
- Do class components need forwardRef? No. A
refon a class component points to the class instance. For classes,refis still not passed inprops. - What are ref cleanup functions? In React 19, a callback ref can return a cleanup function, which React calls when the element is removed, just like an effect.
- How do HOCs handle refs? Before React 19 an HOC had to use
forwardRefto pass the ref through. With ref as a prop, spreading{...props}passes it along. - Should I migrate existing forwardRef code? It keeps working. React provides a codemod, so migrate when convenient.
Quick recap
forwardRefpasses a parent's ref to an element inside a function component.- React 19 makes
refa normal prop, soforwardRefis no longer needed. useImperativeHandleexposes chosen methods instead of the whole DOM node.- Use refs for focus, measurement and imperative APIs, not for data flow.