V4 to V5
This document will help you upgrade from antd 4.x
version to antd 5.x
version. If you are using 3.x
or older version, please refer to the previous upgrade document to 4.x.
Upgrade preparation
- Please upgrade to the latest version of 4.x first, and remove / modify related APIs according to the console warning message.
Incompatible changes in v5
Design specification
- Basic rounded corner adjustment, changed from
2px
to four layers of radius, which are2px
4px
6px
and8px
. For example, radius of default Button is modified from2px
to6px
. - Primary color adjustment, changed from #1890ff to #1677ff.
- Global shadow optimization, adjusted from three layers of shadows to two layers, which are used in common components (Card .e.g) and popup components (Dropdown .e.g).
- Overall reduction in wireframe usage.
Technology adjustment
Remove less, adopt CSS-in-JS, for better support of dynamic themes. The bottom layer uses @ant-design/cssinjs as a solution.
- All less files are removed, and less variables are no longer exported.
- CSS files are no longer included in package. Since CSS-in-JS supports importing on demand, the original
antd/dist/antd.css
has also been abandoned. If you need to reset some basic styles, please importantd/dist/reset.css
. - If you need to reset the style of the component, but you don't want to introduce
antd/dist/reset.css
to pollute the global style, You can try using the App in the outermost layer to solve the problem that native elements do not have antd specification style.
Remove css variables and dynamic theme built on top of them.
LocaleProvider has been deprecated in 4.x (use
<ConfigProvider locale />
instead), we removed the related folderantd/es/locale-provider
andantd/lib/locale-provider
in 5.x.Replace built-in Moment.js with Dayjs. For more: Use custom date library.
babel-plugin-import
is no longer supported. CSS-in-JS itself has the ability to import on demand, and plugin support is no longer required. Umi users can remove related configurations.// config/config.tsexport default {antd: {- import: true,},};
Compatibility
- DO NOT support IE browser anymore.
Component API adjustment
The classname API of the component popup box is unified to
popupClassName
, anddropdownClassName
and other similar APIs will be replaced.- AutoComplete
- Cascader
- Select
- TreeSelect
- TimePicker
- DatePicker
- Mentions
import { Select } from 'antd';const App: React.FC = () => (<Select- dropdownClassName="my-select-popup"+ popupClassName="my-select-popup"/>);export default App;The controlled visible API of the component popup is unified to
open
, andvisible
and other similar APIs will be replaced.- Drawer
visible
changed toopen
. - Modal
visible
changed toopen
. - Dropdown
visible
changed toopen
. - Tooltip
visible
changed toopen
. - Tag
visible
is removed. - Slider
tooltip
related API converged totooltip
property. - Table
filterDropdownVisible
changed tofilterDropdownOpen
.
import { Modal, Tag, Table, Slider } from 'antd';const App: React.FC = () => {const [visible, setVisible] = useState(true);return (<>- <Modal visible={visible}>content</Modal>+ <Modal open={visible}>content</Modal>- <Tag visible={visible}>tag</Tag>+ {visible && <Tag>tag</Tag>}<Tabledata={[]}columns={[{title: 'Name',dataIndex: 'name',- filterDropdownVisible: visible,+ filterDropdownOpen: visible,}]}/>- <Slider tooltipVisible={visible} />+ <Slider tooltip={{ open: visible }} /></>);}export default App;- Drawer
getPopupContainer
: AllgetPopupContainer
are guaranteed to return a unique div. This method will be called repeatedly under React 18 concurrent mode.Upload List structure changes. #34528
Notification
- Static methods are no longer allowed to dynamically set
prefixCls
maxCount
top
bottom
getContainer
inopen
, Notification static methods will now have only one instance. If you need a different configuration, useuseNotification
. close
was renamed todestroy
to be consistent with message.
- Static methods are no longer allowed to dynamically set
Drawer
style
&className
are migrated to Drawer panel node, the original properties are replaced byrootClassName
androotStyle
.The deprecated
message.warn
in 4.x is now completely removed, please usemessage.warning
instead.
Component refactoring and removal
Remove
locale-provider
Directory.LocaleProvider
was removed in v4, please useConfigProvider
instead.Move Comment component into
@ant-design/compatible
.Move PageHeader component into
@ant-design/pro-components
.- import { PageHeader, Comment } from 'antd';+ import { Comment } from '@ant-design/compatible';+ import { PageHeader } from '@ant-design/pro-components';const App: React.FC = () => (<><PageHeader /><Comment /></>);export default App;BackTop is deprecated in
5.0.0
, and is merged into FloatButton.- import { BackTop } from 'antd';+ import { FloatButton } from 'antd';const App: React.FC = () => (<div>- <BackTop />+ <FloatButton.BackTop /></div>);export default App;
Start upgrading
Use git to save your code and install latest version:
npm install --save antd@5.x
If you want to use v4 deprecated component like Comment
or PageHeader
. You can install @ant-design/compatible
and @ant-design/pro-components
for compatible:
npm install --save @ant-design/compatible@v5-compatible-v4npm install --save @ant-design/pro-components
You can manually check the code one by one against the above list for modification. In addition, we also provide a codemod cli tool @ant-design/codemod-v5 To help you quickly upgrade to v5.
Before running codemod cli, please submit your local code changes.
# Run directly through npxnpx -p @ant-design/codemod-v5 antd5-codemod src# Or run directly through pnpmpnpm --package=@ant-design/codemod-v5 dlx antd5-codemod src
Note that codemod cannot cover all scenarios, and it is recommended to check for incompatible changes one by one.
less migration
If you using antd less variables, you can use compatible package to covert it into v4 less variables and use less-loader to inject them:
const { theme } = require('antd/lib');const { convertLegacyToken, defaultTheme } = require('@ant-design/compatible/lib');const { defaultAlgorithm, defaultSeed } = theme;const mapV5Token = defaultAlgorithm(defaultSeed);const v5Vars = convertLegacyToken(mapV5Token);const mapV4Token = theme.getDesignToken(defaultTheme);const v4Vars = convertLegacyToken(mapV4Token);// Webpack Configmodule.exports = {// ... other configloader: 'less-loader',options: {lessOptions: {modifyVars: v5Vars, // or v4Vars},},};
And then remove antd less reference in your less file:
// Your less file-- @import (reference) '~antd/es/style/themes/index';or-- @import '~antd/es/style/some-other-less-file-ref';
Remove babel-plugin-import
Remove babel-plugin-import
from package.json and modify .babelrc
:
"plugins": [- ["import", { "libraryName": "antd", "libraryDirectory": "lib"}, "antd"],]
Umi user can disable by config:
// config/config.ts or .umircexport default {antd: {- import: true,+ import: false,},};
Replace Day.js locale
Replace moment.js locale with day.js locale:
- import moment from 'moment';+ import dayjs from 'dayjs';- import 'moment/locale/zh-cn';+ import 'dayjs/locale/zh-cn';- moment.locale('zh-cn');+ dayjs.locale('zh-cn');
🚨 You need to pay attention to the day.js plugin system. If you find that the function originally in moment.js cannot be used in day.js, please refer to the day.js plugin document.
If you do not want to replace with day.js, you can use @ant-design/moment-webpack-plugin
to keep moment.js:
npm install --save-dev @ant-design/moment-webpack-plugin
// webpack-config.jsimport AntdMomentWebpackPlugin from '@ant-design/moment-webpack-plugin';module.exports = {// ...plugins: [new AntdMomentWebpackPlugin()],};
Switch to theme of v4
If you don't want the style to change after upgrade, we have provided a v4 theme in @ant-design/compatible
that can restore v4 style.
```sandpackconst sandpackConfig = {dependencies: {'@ant-design/compatible': 'v5-compatible-v4',},};import {defaultTheme, // Default themedarkTheme, // Dark theme} from '@ant-design/compatible';import { ConfigProvider, Button, Radio, Space } from 'antd';export default () => (<ConfigProvider theme={defaultTheme}><Space direction="vertical"><Button type="primary">Button</Button><Radio.Group><Radio value={1}>A</Radio><Radio value={2}>B</Radio><Radio value={3}>C</Radio><Radio value={4}>D</Radio></Radio.Group></Space></ConfigProvider>);
Legacy browser support
Ant Design v5 using :where
css selector to reduce CSS-in-JS hash priority. You can use @ant-design/cssinjs
StyleProvider
to cancel this function. Please ref Compatible adjustment.
Multiple versions coexist
We do not recommend multiple versions coexist, it will make the application more complex (such as style override, ConfigProvider not reused, etc.). It's better to use micro-applications such as qiankun for page level development.
Install v5 through alias
$ npm install --save antd-v5@npm:antd@5# or$ yarn add antd-v5@npm:antd@5# or$ pnpm add antd-v5@npm:antd@5
The package.json will be:
{"antd": "4.x","antd-v5": "npm:antd@5"}
Now, antd in your project is still v4, and antd-v5 is v5.
import React from 'react';import { Button as Button4 } from 'antd'; // v4import { Button as Button5 } from 'antd-v5'; // v5export default () => (<><Button4 /><Button5 /></>);
Then config prefixCls
of ConfigProvider to avoid style conflict:
import React from 'react';import { ConfigProvider as ConfigProvider5 } from 'antd-v5';export default () => (<ConfigProvider5 prefixCls="ant5"><MyApp /></ConfigProvider5>);
Encounter problems
If you encounter problems during the upgrade, please go to GitHub issues for feedback. We will respond and improve this document as soon as possible.