React 20 ref as a Prop: Migrating Away From forwardRef Across a Large Component Library
This article was written with the assistance of AI, under human supervision and review.
Most React component library maintenance debt stems from a single historical artifact: forwardRef. The pattern emerged because refs were special-cased in React's original architecture—passing them required wrapping every component that needed to expose a DOM handle. Component library teams spent years adding forwardRef wrappers to hundreds of components, maintaining parallel prop interfaces, and explaining to developers why some components accepted refs while others did not.
React 20 eliminates this complexity by treating ref as a standard prop. The wrapper disappears. The special case vanishes. Teams maintaining component libraries face a straightforward migration path, but the execution requires deliberate planning across versioning, TypeScript definitions, and test coverage.
React 20's approach removes the wrapper entirely. The ref prop flows through component props like className or onClick. TypeScript inference improves because the prop interface becomes a single object instead of a split between props and ref parameters.
