React 19 Upgrade in WordPress: What Developers Need to Know

WordPress is upgrading its React library from version 18 to 19, marking a significant evolution in its front-end framework integration. This upgrade is rolling out first in the Gutenberg plugin and will be part of the upcoming WordPress 7.1 release.

What Happened

WordPress announced its upgrade from React 18 to React 19, starting with the Gutenberg plugin version 23.3 and targeting WordPress 7.1 for core inclusion. This follows a preparatory phase where React 18.3 introduced deprecation warnings to ease the transition.

The upgrade removes long-deprecated ReactDOM APIs such as render, hydrate, and unmountComponentAtNode, mandating migration to new root-based APIs like createRoot and hydrateRoot. The findDOMNode method is removed from React itself but maintained via a polyfill in @wordpress/element.

React 19 also stops supporting defaultProps for function components, advocating for ES6 default parameters instead. Behavioral changes include the inert attribute switching from string to boolean, and ref callbacks gaining the ability to return cleanup functions, a new paradigm for DOM event management.

Function components can now accept refs as regular props, deprecating forwardRef. Additionally, new React hooks such as use, useActionState, useOptimistic, and useFormStatus are introduced to enhance UI state handling within WordPress.

TypeScript typings have been overhauled: MutableRefObject is deprecated, prop types in ReactElement are stricter, and conflicts between HTML element props and custom props require resolution.

Why This Matters

In real WordPress development environments, React is the backbone for the block editor and many custom interfaces. Upgrading to React 19 is not a simple patch; it involves breaking API changes that ripple through plugins and themes.

The removal of foundational ReactDOM methods forces developers to refactor rendering logic. For instance, code still using ReactDOM.render() will break, impacting any plugin or theme that bootstraps React apps manually. Agencies managing multiple client sites with custom blocks or admin interfaces must audit and update codebases to align with the new root API model.

The inert attribute change, subtle as it seems, can cause unexpected UI behavior if existing code sets inert as a string. This is especially relevant for accessibility and UI blocking patterns common in modal dialogs and sidebars within WordPress admin.

The new ref callback cleanup mechanism offers a cleaner lifecycle management option but introduces the risk of subtle bugs if existing callbacks return unexpected values. For production WordPress stacks, this means thorough testing to avoid DOM event leaks or double cleanup.

TypeScript updates are critical for developers using strict typing in their projects. The shift to unknown prop types and deprecated ref types can surface previously hidden bugs or require architectural changes to component typing. Plugin authors aiming for compatibility with the WordPress ecosystem’s direction must invest effort into updating their type definitions.

New React hooks introduced leverage the asynchronous and optimistic UI patterns increasingly relevant in modern WordPress features like inline editing, form validation, and real-time updates. These hooks promise more responsive experiences but require developers to understand their mechanics to implement them effectively.

What This Means for WordPress Users

Should You Care? Absolutely. If you manage or develop WordPress sites, especially those using custom blocks, admin interfaces, or React-based plugins, this upgrade directly impacts your work.

Should You Act? Yes. Start testing your themes and plugins against the Gutenberg plugin version shipping React 19 immediately. Use SCRIPT_DEBUG mode to surface warnings and errors. Identify deprecated API usage and migrate to the new React 19 patterns before WordPress 7.1 launches.

What Should You Change?

• Replace all instances of ReactDOM.render() and ReactDOM.hydrate() with createRoot() and hydrateRoot().
• Update unmountComponentAtNode() calls to root.unmount().
• Refactor any findDOMNode() usage to use refs instead; rely on the polyfill only as a short-term bridge.
• Replace defaultProps in function components with ES6 default parameters.
• Audit and fix inert attribute usage to boolean values.
• Review ref callbacks for return values and adapt them to the new cleanup function pattern.
• For TypeScript projects, update type annotations according to the React 19 typechecking guide and resolve any new type conflicts.
• Explore new React hooks like useActionState and useOptimistic to enhance user experience in your custom blocks and UI components.

For agencies managing multiple sites, this upgrade means allocating developer resources for testing and refactoring well ahead of WordPress 7.1’s stable release to avoid breaking changes in production.

For more detailed technical notes, visit the official Make WordPress Core announcement. Developers are encouraged to participate in testing via the Gutenberg plugin and report any issues early.