React Reference ยท Concepts and Pitfalls
Upgrading to React 19
A checklist for moving an app to React 19: removed APIs, replacements for defaultProps and forwardRef, changed error handling, and new features worth adopting.
React 19 is mostly additive, but it removes a set of long-deprecated APIs and changes a few behaviors. Most apps that already run React 18.3 without warnings upgrade with little work: the 18.3 release added warnings for exactly the things 19 removes. A good path is to update to 18.3 first, fix every warning, then move to 19.
This page lists what breaks, what replaces it, and which new features are worth adopting afterwards. Versions: React 19.0 shipped the removals and most new APIs listed here; 19.2 added <Activity> and useEffectEvent.
// React 18.3 warns; React 19 no longer supports: Button.defaultProps = { size: 'md' }; // use a default parameter ReactDOM.render(<App />, container); // use createRoot
Try it
Removed APIs and their replacements
| Removed or changed | Do this instead |
|---|---|
ReactDOM.render, hydrate, unmountComponentAtNode |
createRoot(container).render(), hydrateRoot(), root.unmount() |
ReactDOM.findDOMNode |
A ref on the element |
propTypes checks on components |
TypeScript, or a validation library (the field is ignored) |
defaultProps on function components |
Default parameter values (classes keep defaultProps) |
String refs (ref="input") |
useRef or createRef |
Legacy context (contextTypes, getChildContext) |
createContext |
React.createFactory |
JSX or createElement |
Module-pattern components (function returning an object with render) |
Normal function or class components |
react-test-renderer/shallow |
Testing Library or react-test-renderer itself (the package is deprecated) |
react-dom/test-utils act |
import { act } from 'react' |
| UMD builds | ESM, or a CDN that serves modules |
Passing a ref to a function component no longer needs forwardRef: ref is an ordinary prop for function components. forwardRef still works and will be deprecated later. Reading element.ref is deprecated; use element.props.ref.
Behavior changes
- Errors are not re-thrown. Errors caught by an error boundary are logged once through
onCaughtError; errors nobody caught go toonUncaughtError. Both are options ofcreateRoot, so you can route them to a reporting service. Errors from hydration useonRecoverableError. - Suspense commits fallbacks sooner. When a component suspends, React shows the nearest fallback without first rendering the siblings; those siblings are prepared afterwards.
- Strict Mode reuses memoized results. During its second render in development,
useMemoanduseCallbackreuse the first render's results. - Hydration errors are clearer, with a diff of server and client output instead of several messages.
useReduceranduseReftyping changed in@types/react19:useRefrequires an argument, and the globalJSXnamespace is gone (useReact.JSX). Run the official codemods.- Third-party packages that rely on removed internals (
__SECRET_INTERNALS...) or onfindDOMNodemust be updated before you can upgrade.
New features worth adopting
- Actions with
useActionState,useOptimistic,useFormStatusand<form action>. useto read promises and context in render, including after an early return.<title>,<meta>and<link>rendered anywhere in the tree and hoisted into<head>, plus resource preloading APIs.<Context value>instead of<Context.Provider>, andrefas a prop.- Custom elements work with props and events.
<Activity>anduseEffectEvent(19.2).
Usage notes
- Upgrade in this order: React 18.3, fix warnings, switch to React 19, run
npx types-react-codemodfor TypeScript projects and the React codemod collection for the runtime changes. - Do not mix versions:
reactandreact-dommust have the same version. - Lock the test setup: import
actfromreact, and setglobalThis.IS_REACT_ACT_ENVIRONMENT = truein custom harnesses. - Roll out gradually: the new features are opt-in, so you can keep class components,
forwardRefand.Providerwhile you migrate. - Read your dependency changelogs; UI libraries often publish a React 19 compatible release.