React v19 Adaptation - Semi Design

Start · React v19 Adaptation

React v19 Adaptation

React v19 adaptation

Since the release of React v19, React has introduced numerous underlying mechanism and API changes, including upgrades and adjustments to the render mechanism, ref, context, TypeScript types, and related deprecated APIs. To ensure that the Semi Design component library is smoothly compatible with both React v19 and lower versions, we provide the original component package @douyinfe/semi-ui for React versions below v19, as well as a new package @douyinfe/semi-ui-19 specifically adapted for React v19, so users can choose as needed. This guide will help you understand how to install, use, and the precautions to take.

Installation & Usage

If your project is using React v19, please use @douyinfe/semi-ui-19. For React versions below v19, continue using @douyinfe/semi-ui as before.


# For users of React v19
# Using npm
npm i @douyinfe/semi-ui-19 

# Using yarn
yarn add @douyinfe/semi-ui-19

# Using pnpm
pnpm add @douyinfe/semi-ui-19

To use, just import components from @douyinfe/semi-ui-19:


import React, { Component } from 'react';
import { Button, Toast } from '@douyinfe/semi-ui-19';

const SemiApp = () => {
    return (
        <Button onClick={() => Toast.warning({ content: 'I can now adapt to React v19.' })}>
            Hello Semi
        </Button>
    );
};

Why maintain two packages?

React v19 introduces several major updates, new deprecations, breaking changes, and TypeScript modifications. Check the React v19 Upgrade Guide for details. For most changes, we have re-implemented components to ensure they work consistently across different React versions.

However, the removal of ReactDOM.render and ReactDOM.findDOMNode in React v19 cannot be simply patched to work with both React versions.

For the Semi component library:

Modal, Notification, and Toast components use ReactDOM.render to mount content onto nodes.
Tooltip uses ReactDOM.findDOMNode to obtain the real DOM node, and other popover components like Popover and PopConfirm are implemented based on Tooltip.

For frontend projects:

Some legacy projects do not have an urgent need to upgrade to React v19.
Some projects use syntax or APIs removed in React v19, so they need to continue using the Semi library supporting React below v19 for now.

Therefore, to ensure functional consistency, we use different code implementations for React v19 and versions below it, and continue to update both @douyinfe/semi-ui-19 (React v19) and @douyinfe/semi-ui (below v19) for at least a year.

Notes

The removal of ReactDOM.findDOMNode in React v19 makes it impossible to find and return the real DOM node for a given class component instance.

For Tooltip and other popover components based on Tooltip (such as Popover, PopConfirm), if the children are class components and the props are forwarded to the real DOM node, it works fine with @douyinfe/semi-ui. However, in @douyinfe/semi-ui-19, it may not work, and you should wrap the class component in a real DOM node (such as <span>, <div>, <p>, etc.) for a workaround.

For example:


// @douyinfe/semi-ui
// The children of Tooltip is a class component (MyComponent), props are forwarded to the real DOM node
// Works fine
import React from 'react';
import { Tooltip } from '@douyinfe/semi-ui';

class MyComponent extends React.Component {
    render() {
        return (<span {...this.props} style={{ border: '2px solid var(--semi-color-border)' }}>ClassComponent</span>);
    }
};

() => (<Tooltip content="Hello">
    <MyComponent>Hover me</MyComponent>
</Tooltip>);


// Using @douyinfe/semi-ui-19,
// Can't use MyComponent as a direct child of Tooltip
// wrap it in a real DOM node for proper functioning
import React from 'react';
import { Tooltip, Button } from '@douyinfe/semi-ui-19';

class MyComponent extends React.Component {
    render() {
        return (<span {...this.props} style={{ border: '2px solid var(--semi-color-border)' }}>ClassComponent</span>);
    }
};

() => (<Tooltip content="Hello">
    <span style={{ display: 'inline-flex' }}>
        <MyComponent>Hover me</MyComponent>
    </span>
</Tooltip>);