Skip to main content
Version: 4.xx.xx

Migration Guide

Ant Design released a new major version as a v5. This document will help you upgrade from antd 4.x version to antd 5.x version.

Ant Design removed less and adopt CSS-in-JS, for better support of dynamic themes. The bottom layer uses @ant-design/cssinjs as a solution. Some components are removed or renamed, and some APIs are changed.

Some of the changes are:

  • <PageHeader> component moved into @ant-design/pro-components. refine is using <PageHeader> in <List>, <Create>, <Edit>, <Show> components and added as a dependency. You don't need to install @ant-design/pro-components package manually.
  • <Comment> component moved into @ant-design/compatible.
  • moment.js is replaced with day.js.
  • less is removed from antd package.

Please refer to Ant Design Migration Guide for detailed information.

A little more clarification
refine packageAnt Design version
@pankod/refine-antd@3.x.xantd@4.x.x
@pankod/refine-antd@4.x.x, @refinedev/antd@5.x.xantd@5.x.x

Updating the packages

@refinedev/antd must be updated to 4.x.x

⚡️ You can easily update refine packages with refine CLI update command.

npm run refine update

How to add refine CLI to an existing project?

@refinedev/codemod package handles the breaking changes for your project automatically, without any manual steps. It migrates your @refinedev/antd version from 3.x.x to 4.x.x.

Just cd into root folder of your project (where package.json is contained) and run this command:

npx @refinedev/codemod antd4-to-antd5

And it's done. Now your project uses @refinedev/antd@4.x.x.

🚨 Customized or swizzled components and .less files cannot be migrated automatically. You need to migrate them manually.

Migrating your project manually

Updating Imports

  • CSS files are no longer included in package. Since CSS-in-JS supports importing on demand, the original styles/antd.less has also been abandoned. If you need to reset some basic styles, please import @refinedev/antd/dist/reset.css
App.tsx
- import "@refinedev/antd/dist/styles.min.css";
+ import "@refinedev/antd/dist/reset.css";

Updating Props

actionButtons and pageHeaderProps props was deprecated on @refinedev/antd@3.x.x and removed on @refinedev/antd@4.x.x from <List>, <Create>, <Edit>, <Show> component due to incosistency with all UI packages. Use headerButtons and headerProps props instead.

List.tsx
- <List actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}>
+ <List headerButtons={actionButtons} headerProps={pageHeaderProps}>
Create.tsx
- <Create actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}>
+ <Create headerButtons={actionButtons} headerProps={pageHeaderProps}>
Show.tsx
- <Show actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}>
+ <Show headerButtons={actionButtons} headerProps={pageHeaderProps}>
Edit.tsx
- <Edit actionButtons={actionButtons} pageHeaderProps={pageHeaderProps}>
+ <Edit headerButtons={actionButtons} headerProps={pageHeaderProps}>

Customized <Sider>

If you have customized or swizzled the <Sider> component, there may be a color mismatch issue. You can give theme dark to the <Menu> component in the <Sider> component.

Sider.tsx
    <AntdLayout.Sider
collapsible
collapsed={collapsed}
onCollapse={(collapsed: boolean): void => setCollapsed(collapsed)}
collapsedWidth={isMobile ? 0 : 80}
breakpoint='lg'
style={isMobile ? antLayoutSiderMobile : antLayoutSider}>
<RenderToTitle collapsed={collapsed} />
<Menu
+ theme='dark'
selectedKeys={[selectedKey]}
defaultOpenKeys={defaultOpenKeys}
mode='inline'
onClick={() => {
if (!breakpoint.lg) {
setCollapsed(true)
}
}}>
{renderSider()}
</Menu>
</AntdLayout.Sider>

Customized <Header>

If you have customized or swizzled the <Header> component, there may be a color mismatch issue. You can remove constant background color in <Header> component.

Header.tsx
   <AntdLayout.Header
style={{
display: 'flex',
justifyContent: 'flex-end',
alignItems: 'center',
padding: '0px 24px',
height: '64px',
- backgroundColor: '#FFF',
}}>

LESS Users

Ant Design removed less, uses and recommends CSS-in-JS instead. You need to manually migrate your .less files to CSS-in-JS. Ant Design's documentation for less migration.

Known Issues

Compile errors

Some users repored (issue#1, issue#2) compile errors after upgrading from @refinedev/antd@3.x.x to @refinedev/antd@4.x.x. They also provided solutions.

Solution 1

  1. remove node_modules folder
  2. remove package-lock.json file
  3. npm install

Solution 2

npm install react@latest react-dom@latest