Introduction
One of the most elegant improvements in React 19 is that ref is just a prop in React 19—no more boilerplate, no more confusion. For years, passing a ref to a function component required wrapping it with forwardRef, a pattern that felt awkward and added unnecessary cognitive load. In React 19, refs flow through components naturally, like any other prop, making your code cleaner and your component APIs more intuitive.
I've been building production systems for over five years, and I've spent countless hours refactoring ref-heavy code in design systems and component libraries. This change alone has saved me hours of redundant wrapper boilerplate. Let me walk you through why this matters and how it changes the way we write React today.
Function Components Accept ref Directly
In React 18 and earlier, if you wanted a parent component to access a DOM node or imperative handle inside a child function component, you had to reach for forwardRef. It was clunky:
// React 18 pattern
import { forwardRef } from 'react';
const Input = forwardRef((props, ref) => {
return <input ref={ref} {...props} />;
});
// Usage
const Form = () => {
const inputRef = useRef(null);
return <Input ref={inputRef} />;
};The wrapping function, the reversed parameter order (props first, ref second), and the mental model that refs are somehow "special" all contributed to friction. In React 19, ref is just a prop. You receive it like any other prop in your component signature:
// React 19 pattern
const Input = ({ ref, ...props }) => {
return <input ref={ref} {...props} />;
};
// Usage remains the same
const Form = () => {
const inputRef = useRef(null);
return <Input ref={inputRef} />;
};That's it. No wrapper. No forwardRef. No special ceremony. This is particularly powerful when you're building a component library where dozens of components might previously have required this wrapping. Multiply that by the number of components, and you save substantial code.
Let me show you a real-world scenario I encountered at my last project—a CRM platform with a complex form component library. Previously, every input-like component needed forwardRef. Now:
// A text input component
const TextInput = ({ ref, label, error, ...props }) => {
return (
<div>
<label>{label}</label>
<input
ref={ref}
aria-invalid={!!error}
{...props}
/>
{error && <span className="error">{error}</span>}
</div>
);
};
// A select component
const Select = ({ ref, options, ...props }) => {
return (
<select ref={ref} {...props}>
{options.map(opt => (
<option key={opt.value} value={opt.value}>{opt.label}</option>
))}
</select>
);
};
// A modal with imperative close
const Modal = ({ ref, children, ...props }) => {
const internalRef = useRef(null);
useImperativeHandle(ref, () => ({
open: () => internalRef.current?.showModal(),
close: () => internalRef.current?.close(),
}));
return <dialog ref={internalRef} {...props}>{children}</dialog>;
};All of these components now follow a consistent, familiar pattern. Refs aren't special ceremony—they're just part of your prop API.
forwardRef Will Be Deprecated Over Time
React maintainers have made it clear: forwardRef isn't going anywhere tomorrow, but it's gradually becoming unnecessary. The deprecation path is deliberately slow and gradual to avoid breaking existing code. However, the clear direction is that forwardRef is a legacy pattern.
This matters for your refactoring strategy. If you're maintaining a component library or a codebase with hundreds of components, you now have a clear migration path. You don't need to do it all at once—you can adopt the new pattern incrementally as you touch each component.
Here's how a gradual migration might look in a real library. Imagine you have a 50-component design system:
// Old pattern (will migrate away from)
import { forwardRef } from 'react';
const Button = forwardRef(({ variant, size, ...props }, ref) => {
return (
<button
ref={ref}
className={`btn btn-${variant} btn-${size}`}
{...props}
/>
);
});
// New pattern (adopt this)
const Button = ({ ref, variant, size, ...props }) => {
return (
<button
ref={ref}
className={`btn btn-${variant} btn-${size}`}
{...props}
/>
);
};The migration is mechanical and safe. Your tests pass unchanged because the external API (how consumers call the component) remains identical. The only difference is internal—the component no longer needs a wrapper.
For teams maintaining libraries, this is a significant maintenance win. You reduce lines of code, reduce cognitive overhead in code reviews, and align with the React team's direction.
Cleanup Functions Can Be Returned from ref Callbacks
This is a subtle but powerful enhancement. When you use a ref callback (instead of useRef), you can now return a cleanup function. This is helpful when your ref needs to set up and tear down event listeners or other side effects.
// React 18 pattern: awkward separation of setup and cleanup
const VideoPlayer = () => {
const videoRef = useRef(null);
useEffect(() => {
const video = videoRef.current;
if (!video) return;
const handlePlay = () => console.log('Playing');
const handlePause = () => console.log('Paused');
video.addEventListener('play', handlePlay);
video.addEventListener('pause', handlePause);
return () => {
video.removeEventListener('play', handlePlay);
video.removeEventListener('pause', handlePause);
};
}, []);
return <video ref={videoRef} />;
};In React 19, this logic can be colocated with the ref itself:
// React 19 pattern: cleanup in the callback
const VideoPlayer = () => {
return (
<video
ref={(video) => {
if (!video) return;
const handlePlay = () => console.log('Playing');
const handlePause = () => console.log('Paused');
video.addEventListener('play', handlePlay);
video.addEventListener('pause', handlePause);
// Return cleanup function
return () => {
video.removeEventListener('play', handlePlay);
video.removeEventListener('pause', handlePause);
};
}}
/>
);
};This is particularly useful in a ride-hailing or real-time trading platform where you need precise control over when listeners attach and detach. I used this pattern recently on a WebSocket connection that needed to be torn down correctly when a component unmounted:
const LiveOrderStream = ({ orderId }) => {
return (
<div
ref={(container) => {
if (!container) return;
const ws = new WebSocket(`wss://api.example.com/orders/${orderId}`);
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
container.textContent = update.status;
};
// Cleanup when ref unmounts
return () => ws.close();
}}
>
Connecting...
</div>
);
};The advantage is clear: setup and cleanup are no longer separated by a useEffect. They're together, in the ref callback. This makes the intent obvious and reduces the chance of cleanup-related bugs.
Simpler Component Library Code
If you're building or maintaining a component library—whether it's internal or open-source—React 19 refs will simplify your codebase substantially. I've worked on three production design systems, and this change alone reduces boilerplate by 10-15% in components that expose refs.
Consider a form validation library that needs to expose refs to inputs:
// A wrapped form component that provides refs to all inputs
const ValidatedForm = ({ ref, children, onSubmit }) => {
const fieldRefs = useRef({});
useImperativeHandle(ref, () => ({
validate: () => {
const errors = {};
Object.entries(fieldRefs.current).forEach(([name, field]) => {
if (!field.value) errors[name] = 'Required';
});
return errors;
},
submit: () => {
const errors = this.validate();
if (Object.keys(errors).length === 0) onSubmit();
},
}));
const registerField = (name, fieldRef) => {
fieldRefs.current[name] = fieldRef.current;
};
return <form>{children}</form>;
};
// Using it
const App = () => {
const formRef = useRef(null);
return (
<>
<ValidatedForm ref={formRef}>
<TextInput name="email" />
<TextInput name="password" />
</ValidatedForm>
<button onClick={() => formRef.current?.submit()}>Submit</button>
</>
);
};Previously, ValidatedForm would have been wrapped in forwardRef. Now it's just a function component that accepts ref as a prop. Simpler, clearer, less nesting.
For production systems handling commerce, CRM workflows, or trading platforms, this simplification multiplies. Every component you write with a ref becomes slightly easier to reason about, test, and refactor.
Common Mistakes
Mistake 1: Forgetting to destructure ref early
You might instinctively spread all props, including ref, which doesn't work as expected:
// Wrong: ref ends up in ...props
const Input = (props) => <input {...props} />;
// Correct: explicitly destructure ref
const Input = ({ ref, ...props }) => <input ref={ref} {...props} />;
Mistake 2: Mixing patterns in the same codebase
If you have legacy forwardRef components alongside new ref-as-prop components, developers can get confused about which pattern to follow. Plan a migration strategy and document it clearly.
Mistake 3: Not cleaning up ref callbacks
If your ref callback sets up listeners or timers, forgetting to return a cleanup function will leak resources:
// Wrong: no cleanup
<div ref={(el) => {
el.addEventListener('click', handler); // Leaks listener
}} />
// Correct: return cleanup
<div ref={(el) => {
if (!el) return;
el.addEventListener('click', handler);
return () => el.removeEventListener('click', handler);
}} />
Mistake 4: Accessing ref in render before it's attached
Refs are assigned after render, so don't try to read them synchronously during rendering:
// Wrong
const Component = ({ ref }) => {
console.log(ref.current); // null on first render
return <div ref={ref} />;
};
// Correct: read in useEffect or callback
const Component = ({ ref }) => {
useEffect(() => {
console.log(ref.current); // Now available
}, [ref]);
return <div ref={ref} />;
};
Key Takeaways
- Refs are just props now: In React 19,
refflows through components naturally. Receive it like any other prop and pass it to the DOM element. NoforwardRefwrapper needed. - forwardRef is legacy, not removed: The deprecation is gradual. You can refactor incrementally as you touch components, keeping your codebase stable during the transition.
- Ref callbacks can return cleanup functions: When you need setup and teardown logic (listeners, timers, WebSocket connections), return a cleanup function directly from your ref callback instead of using
useEffect. - Component libraries get simpler: Reducing
forwardRefboilerplate makes library code faster to write, easier to read, and less error-prone across dozens of components. - Watch for the null state: When a ref callback is called with
nullduring unmount, always guard against it. This is where your cleanup logic runs. - Test backward compatibility: If you're migrating an existing library, ensure your external API remains unchanged. The migration is internal only.
Comments
Loading comments…