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. ```mermaid flowchart LR A("Component receives ref prop") --> B("forwardRef wrapper intercepts") B --> C("Extra function layer") C --> D("TypeScript generics proliferate") D --> E("Maintenance burden increases") style E stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` 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. ```mermaid flowchart LR A("Component receives ref prop") --> B("Direct prop destructuring") B --> C("Single interface definition") C --> D("Maintenance overhead drops") style D stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` 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 for `forwardRef` wrappers in all component definitions. - Migration requires updating TypeScript interfaces to include `ref` as a prop field and removing `forwardRef` 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. ```mermaid flowchart TD A("React 20 reconciler processes component") --> B("Props diffing algorithm runs") B --> C("ref handled as standard prop") C --> D("DOM element receives ref callback") D --> E("Component renders without wrapper") style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` 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`. ```mermaid flowchart LR A("Scan codebase for forwardRef imports") --> B("Build component candidate list") B --> C("Cross-reference public API docs") C --> D("Filter to ref-capable components") D --> E("Prioritize by consumer usage metrics") style E stroke:#7c9cf0,fill:#142544,color:#eaf2ff ``` 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: ```typescript 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 ( ); } ); Button.displayName = 'Button'; export default Button; ``` The React 20 version eliminates the wrapper function and accepts `ref` as a standard prop: ```typescript 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 ( ); } 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: ```typescript 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: ```typescript 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: ```typescript import { Ref } from 'react'; interface ListProps { items: T[]; renderItem: (item: T) => React.ReactNode; ref?: Ref; } function List({ items, renderItem, ref }: ListProps) { return (

{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 a different challenge. The HOC must preserve the wrapped component's ref type while adding its own props. This requires conditional types: ```typescript import { ComponentType, Ref, ComponentPropsWithoutRef } from 'react'; function withLogger

( Component: ComponentType

): ComponentType

}> { return function LoggedComponent(props: P & { ref?: Ref }) { console.log('Rendering with props:', props); return ; }; } ``` This approach is fragile and error-prone in large codebases. The better pattern is to avoid ref forwarding in HOCs entirely. If consumers need a ref to the wrapped component, they should render it directly instead of wrapping it in a HOC. This aligns with React's composition philosophy and reduces maintenance burden. The distinction here matters for libraries shipping to diverse TypeScript configurations. Some consuming projects enable strict null checks; others do not. The `ref` type must work correctly in both modes, which means using `Ref` instead of custom union types or optional chaining assumptions. ## Breaking Changes and Versioning Strategy for Component Libraries Migrating from `forwardRef` to ref-as-prop represents a breaking change for any component library. The runtime behavior remains compatible—components still accept refs—but the TypeScript definitions change shape. Consuming projects that import component types directly will see compilation errors until they update. The versioning strategy must follow semantic versioning strictly. Increment the major version number when shipping the migration. Document the breaking changes in the changelog with specific examples of old and new usage patterns. Provide a migration guide that shows the diff for common component types. ```mermaid flowchart LR A("Identify breaking changes") --> B("Increment major version") B --> C("Document migration patterns") C --> D("Publish changelog with diffs") D --> E("Release with deprecation warnings") style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Some teams attempt to maintain backward compatibility by shipping both `forwardRef` and ref-as-prop versions in parallel. This strategy creates a maintenance nightmare. The codebase doubles in size for the duration of the compatibility window. Test coverage must verify both code paths. Documentation must explain when to use each variant. A cleaner approach is a hard cutover with a deprecation period. Ship the new major version with ref-as-prop exclusively. Mark the old version as deprecated in the package registry. Provide a compatibility shim for teams that cannot upgrade immediately: ```typescript // compatibility-shim.ts import { forwardRef, ComponentType } from 'react'; export function createForwardRefShim

( Component: ComponentType

) { return forwardRef>((props, ref) => { return ; }); } ``` This shim wraps the new ref-as-prop component in a `forwardRef` wrapper, providing the old API surface for consumers who have not migrated yet. The shim ships as a separate export, not as the default behavior, so teams opt into compatibility explicitly. The failure mode here is releasing the migration without adequate communication. Developers upgrading to the new major version encounter TypeScript errors with no clear explanation. The changelog must include a "Migration Guide" section with before-and-after code examples for every common component type in the library. Related patterns for handling breaking changes in production React applications appear in [React 19 concurrent rendering production patterns](/react-19-concurrent-rendering-production-patterns) and [React error boundaries production patterns](/react-error-boundaries-production-patterns). ## Testing Your Migration: Ensuring Ref Forwarding Still Works Test coverage for ref forwarding requires verifying both runtime behavior and TypeScript compilation. The runtime tests confirm that refs attach to the correct DOM elements. The type tests ensure that consuming code compiles without errors when passing refs. Start with a basic runtime test using a testing library like Jest and React Testing Library: ```typescript import { render } from '@testing-library/react'; import { useRef, useEffect } from 'react'; import Button from './Button'; test('Button forwards ref to underlying button element', () => { let capturedRef: HTMLButtonElement | null = null; function TestComponent() { const buttonRef = useRef(null); useEffect(() => { capturedRef = buttonRef.current; }, []); return ; } render(); expect(capturedRef).toBeInstanceOf(HTMLButtonElement); expect(capturedRef?.tagName).toBe('BUTTON'); }); ``` This test renders the component, attaches a ref, and verifies that the ref points to the correct DOM element type. The test catches regressions where the ref assignment gets dropped during refactoring. ```mermaid flowchart LR A("Render component with ref") --> B("useEffect captures ref value") B --> C("Assert ref points to correct element") C --> D("Verify DOM node properties") D --> E("Test passes") style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Type-level tests require a different approach. Use TypeScript's `expectType` utility from libraries like `tsd` or `expect-type`: ```typescript import { expectType } from 'tsd'; import { useRef } from 'react'; import Button from './Button'; const buttonRef = useRef(null); // Should compile without errors expectType(); // Should reject invalid ref types // @ts-expect-error expectType(); ``` These type tests run during CI and fail the build if component interfaces drift. The tests verify that `ref` accepts the correct element type and rejects incompatible types. For component libraries with hundreds of components, generate ref forwarding tests automatically. Write a script that scans the codebase for exported components, generates a test file for each, and runs the suite during CI. This approach ensures comprehensive coverage without manual test authoring. The edge case appears in components that conditionally render different elements based on props. A component that renders either a `button` or an `a` element depending on an `href` prop must type the ref union correctly: ```typescript import { Ref } from 'react'; interface ButtonLinkProps { href?: string; children: React.ReactNode; ref?: Ref; } function ButtonLink({ href, children, ref }: ButtonLinkProps) { if (href) { return } href={href}>{children}; } return ; } ``` Testing these components requires separate test cases for each rendering path, verifying that the ref attaches to the correct element type in each scenario. ## Frequently Asked Questions ### What happens to existing code using forwardRef after upgrading to React 20? Existing `forwardRef` usage continues to work in React 20—the API remains supported for backward compatibility. However, new code should adopt ref-as-prop to avoid the wrapper overhead and simplify TypeScript definitions. ### Can a component library ship both forwardRef and ref-as-prop versions during a transition period? Yes, but maintaining both versions doubles the maintenance burden and test surface area. A cleaner approach is to ship ref-as-prop exclusively in a new major version and provide a compatibility shim for teams that need the old API temporarily. ### How do higher-order components handle refs in React 20? HOCs accept `ref` as a standard prop and pass it through to the wrapped component. The HOC's props interface must include `ref` with the appropriate element type, and the component must forward it explicitly in the JSX. ### Do TypeScript generic components require special handling for refs? No special handling is required. Generic components accept `ref` as a prop with the appropriate element type, and TypeScript infers both the generic type parameter and the ref type independently without conflicts. ### What testing strategy verifies that refs work after migration? Runtime tests should render the component with a ref, capture the ref value in a `useEffect`, and assert that it points to the correct DOM element. Type-level tests using `expectType` should verify that the component accepts valid ref types and rejects invalid ones. ## Conclusion: Simplifying Component APIs Post-Migration The migration from `forwardRef` to ref-as-prop eliminates a historical artifact that added complexity without delivering proportional value. Component libraries that complete this migration reduce their maintenance surface, improve TypeScript inference, and simplify onboarding for contributors who no longer need to understand why refs require special handling. The execution requires discipline: semantic versioning, comprehensive testing, clear migration documentation, and a willingness to treat the change as the breaking change it is. Teams that rush the migration without adequate communication will see support requests spike as consumers encounter unexpected TypeScript errors. That covers the essential patterns for migrating large component libraries to React 20's ref-as-prop system. Apply these in production and the difference will be immediate—fewer wrapper functions, cleaner type definitions, and a codebase that aligns with React's evolving composition model.

Posts tagged “component library”

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