React 20 ref as a Prop: Migrating Away From forwardRef Across a Large Component Library

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. This distinction is critical. Component libraries shipping to thousands of projects must execute this migration without breaking consuming applications. The path forward balances backward compatibility, versioning hygiene, and TypeScript correctness. Key Takeaways - React 20 treats ref as a standard prop, eliminating the need forforwardRef wrappers in all component definitions. - Migration requires updating TypeScript interfaces to include ref as a prop field and removingforwardRef function wrappers from component exports. - Component libraries must treat this as a breaking change, releasing a new major version with clear upgrade documentation and codemods when possible. - Testing must verify that consuming code can still attach refs to migrated components without runtime errors or TypeScript compilation failures. - The migration reduces maintenance burden by eliminating parallel prop interfaces and simplifying component signatures across large codebases. Why React 20 Made ref a Standard Prop React's original architecture treated refs as a special case because the reconciler needed direct control over DOM element references during commit phases. The forwardRef API emerged as a workaround-a way to thread refs through component boundaries when the props object deliberately excluded them. This created a bifurcation in how developers thought about component APIs: regular props went through the props object, but refs required a separate code path. The consequence was immediate and pervasive. Every component library that exposed DOM elements to consumers needed forwardRef wrappers. A simple button component became a higher-order function. TypeScript definitions split into two parts: the props interface and the ref type parameter. Documentation had to explain why some components accepted refs while others did not, even when both rendered DOM elements. React 20 resolves this by integrating ref handling directly into the reconciler's props diffing algorithm. When the reconciler processes a component's props, it now handles ref assignments the same way it handles event handlers or style objects. The special case disappears from the API surface. The implication here is that component library authors no longer maintain two parallel APIs for the same component. A button that accepts onClick can accept ref through the same props object. TypeScript inference works uniformly across all props. The cognitive overhead of explaining ref forwarding to new team members vanishes. This matters because component libraries often contain hundreds of components. Each forwardRef wrapper represents a maintenance point-a place where TypeScript generics might drift, where documentation must stay synchronized, where automated refactoring tools struggle. Eliminating these wrappers reduces the surface area for bugs and simplifies onboarding for contributors. Migration Strategy: Identifying Components That Need Updates The first step in any large-scale migration is establishing which components require changes. Not every component in a library uses forwardRef , and not every component that renders a DOM element needs to expose a ref. The migration targets components where external consumers expect to attach refs-typically leaf components that wrap native HTML elements or third-party DOM-producing libraries. Start by scanning the codebase for forwardRef imports. A simple grep or AST-based search identifies these components immediately. Cross-reference this list against the library's public API documentation. Any component documented as "ref-capable" must be updated, even if the current implementation does not use forwardRef . The second filter is usage data. If the library has telemetry or download statistics, prioritize components that appear in the most consuming projects. A button component with 50,000 weekly downloads demands migration before an obscure utility component with 200. This prioritization lets teams ship incremental releases, spreading the migration risk across multiple versions. Components that render other components from the same library typically do not need changes. If a Card component renders a Button , and both are in the same library, the Card does not need to forward refs-the consuming application attaches refs directly to the Button . This reduces the migration scope significantly in libraries with deep component hierarchies. The edge cases appear in higher-order components and render prop patterns. A HOC that wraps an arbitrary component must decide whether to expose the wrapped component's ref. In React 19, this required forwardRef at the HOC level. In React 20, the HOC accepts ref as a prop and passes it through manually. The pattern changes, but the core logic remains. Code Migration Patterns: Before and After Examples The mechanical transformation from forwardRef to a standard prop follows a consistent pattern. Here is a typical button component in React 19: import { forwardRef, ButtonHTMLAttributes } from 'react'; interface ButtonProps extends ButtonHTMLAttributes { variant: 'primary' | 'secondary'; } const Button = forwardRef ( ({ variant, children, ...props }, ref) => { const className = variant === 'primary' ? 'btn-primary' : 'btn-secondary'; return ( {children} ); } ); Button.displayName = 'Button'; export default Button; The React 20 version eliminates the wrapper function and accepts ref as a standard prop: import { Ref, ButtonHTMLAttributes } from 'react'; interface ButtonProps extends ButtonHTMLAttributes { variant: 'primary' | 'secondary'; ref?: Ref ; } function Button({ variant, children, ref, ...props }: ButtonProps) { const className = variant === 'primary' ? 'btn-primary' : 'btn-secondary'; return ( {children} ); } export default Button; The changes are minimal but load-bearing. The forwardRef wrapper disappears. The ref prop moves into the ButtonProps interface as an optional field. The function signature becomes a standard function component instead of a callback within forwardRef . The displayName assignment becomes unnecessary because the function name provides it directly. This pattern scales across component complexity. A more complex component with multiple refs requires explicit prop names, but the structure remains identical. Consider a split-pane component that exposes refs to both panes: import { Ref } from 'react'; interface SplitPaneProps { leftRef?: Ref ; rightRef?: Ref ; leftContent: React.ReactNode; rightContent: React.ReactNode; } function SplitPane({ leftRef, rightRef, leftContent, rightContent }: SplitPaneProps) { return ( {leftContent} {rightContent} ); } export default SplitPane; No forwardRef wrapper appears. The refs flow through props like any other value. The consuming code remains unchanged-developers still pass leftRef={myRef} when rendering the component. The failure mode here is subtle but expensive. Teams that forget to add ref to the TypeScript interface will ship components that accept refs at runtime but fail TypeScript compilation in consuming projects. The migration must include interface updates alongside function signature changes, and automated tests must verify both paths. Handling TypeScript: Props Interfaces and Generic Components TypeScript definitions require deliberate updates during migration. The forwardRef API used a second type parameter for the ref type, separated from the props interface. React 20 collapses this into a single interface, but the type definitions must match the runtime behavior exactly. Start by importing the Ref type from React. This type represents all valid ref values: callback refs, object refs from useRef , and null. Add it to the props interface as an optional field: import { Ref } from 'react'; interface InputProps { label: string; placeholder?: string; ref?: Ref ; } The optional marker is critical. Most consuming code does not attach refs to every component instance. Making ref required would break existing usage patterns and force consumers to pass ref={null} explicitly-a poor developer experience. Generic components introduce additional complexity. A List component that renders items of type T might need a ref to the container element. The generic type parameter must not conflict with the ref type: import { Ref } from 'react'; interface ListProps { items: T[]; renderItem: (item: T) => React.ReactNode; ref?: Ref ; } function List ({ items, renderItem, ref }: ListProps ) { return ( {items.map((item, index) => ( {renderItem(item)} ))} ); } The T parameter applies to the items array, while Ref applies to the container. TypeScript infers both independently. This pattern works because React 20 does not require special handling for refs in generic components-they are just props. Higher-order components that wrap arbitrary components face