DEV Community

Cover image for Ant Design 5.0 is Released!

Posted on

Ant Design 5.0 is Released!


At the end of September, we released v5 alpha version. After 2 months of adjustment, API has gradually stabilized. Thanks to the community for the valuable suggestions and contributions, it is the power of the community that enables Ant Design to complete a lot of renovation work in a short period of time. Here we will explain some major updates of v5. Of course, you can also go directly to the changelog page to view the complete update content.

Same as the previous major version release. We will switch v4 from the master branch to the 4.x-stable branch into maintenance. v4 will continue to be maintained for 1 year, and patches will still be released for bugs, but no new Feature Requests will be accepted after that. The deadline is the end of 2023. Original official website was migrated to

Design upgrade

In terms of design, we have added 4 types of new components and 4+ variant components according to our business practices and the voice of the community. These components have been scrutinized to ensure their versatility and extensibility. We hope they will bring you a good use experience. At the same time, we have opened up some heavy assets that have been used internally for a long time to help you serve more business scenarios.


In addition we have fully upgraded the components with default styles. Adhering to the core of happy work, we have upgraded the system vision in three directions: "more focus", "distraction", and "relaxation". It involves the optimization and adjustment of multiple global styles such as main colors, rounded corners, text levels, and interactive feedback. In addition, we have also de-linearized the navigation framework and almost all components. These changes bring a brand-new feeling, and also easier to use in the specific use process. Of course you can easily customize your own theme with one click according to the style algorithm and configuration tools we provide in 5.0 if you have different aesthetics and demands for style themes.



Finally, we are experimenting with a theme package called "Happy Work", which contains emotional enhancement features. When users use it in a specific scenario, there will be rich but restrained animations, bringing users a little "happy feeling". We hope this is a start, calling on industry design to pay more attention to enterprise-level products, and inject more emotion into cold enterprise-level products to care for our users. The happy work theme pack will be launched after the press conference, so stay tuned~

Brand new Design Token Model


In v4, we create lots of less variables to support theme customization capabilities. However, expect color palettes, there is no corresponding algorithm for other fonts, line heights, and spacing. In v5, we transformed all tokens can be derived based on Seed + Algorithm. The new Design Token Model supports multi-algorithm pipelines, which greatly reduces developer expansion costs. You can choose an existing algorithm and add your own extended algorithm (of course, you can also write a complete set of algorithms) to generate a complete set of Design Tokens:


CSS-in-JS Dynmaic Theme

In the past we have tried to provide dynamic theming capabilities through CSS Variables. After a period of exploration, we found that maintenance cost of the intermediate variables becomes non-negligible with the complexity of the design system increases. Therefore, CSS Variables in v4 stayed in the dynamic theme color and did not further provide the dynamic ability of dark colors and other tokens. In v5, we face dynamic themes again with the need of flexibility.

At the beginning of v5, we spent a few months comparing the popular dynamic theming solutions: CSS Variables and CSS-in-JS. CSS-in-JS doesn't need to maintain intermediate variables, but has more runtime overhead (if you're not familiar with this, please read Why We're Breaking Up with CSS-in-JS). We prefer the latter in terms of maintenance costs, but we don't want to compromise the user experience. So after a series of attempts, we developed a CSS-in-JS library @ant-design/cssinjs for the component level. It achieves higher cache efficiency by sacrificing dynamism, thus reducing the performance penalty at runtime.

With the dynamic theme capability, you can adjust and nest themes arbitrarily through ConfigProvider:

<ConfigProvider theme={{ token: { colorPrimary: 'red' }}}>
  <ConfigProvider theme={{ token: { colorPrimary: 'blue' }}}>
    <MyApp />
Enter fullscreen mode Exit fullscreen mode

Even adjusted for a single component:

<ConfigProvider theme={{
  components: {
    Button: { colorText: 'red' },
  <MyApp />
Enter fullscreen mode Exit fullscreen mode

Code is boring? You can experience examples directly on our homepage:


The new CSS-in-JS solution natively supports Tree Shaking, and in v5 you no longer need to use babel-plugin-import to remove unused styles. It will automatically load styles on demand.

More components

New FloatButton component is used for global functionality on the website, the original BackTop will be its child component:


New Tour component is added to guide users through product features:


Additionally, we provide some variants of components for inline use:


Compatibility tweaks

Browser minimum version adjustment

In June of this year, IE announced that it would stop maintenance, so the compatibility adjustment of Ant Design v5 was upgraded from IE 11 to Edge, and the rest of the modern browsers remained unchanged. All IE compatibility style code will be removed. At this point, we can combine RTL and LTR styles through CSS Logical Properties to further reduce maintenance costs.

Replace Moment.js with Day.js

Moment.js transitioned to Legacy Project in 2020. Considering that switching the date library would lead to Break Change, we chose to continue using Moment.js during v4 until the end of v4. With v5, we switched to the more lightweight Day.js. In addition to the smaller package size, Day.js also brings immutable capabilities.

Of course, if you want your project to still use Moment.js after an upgrade, you can replace it with the @ant-design/moment-webpack-plugin.

API non-Break adjustments

During Ant Design's 7-year development, some APIs were forked. This leads to additional memory costs for developers, and it also makes it difficult for us to choose when adding new APIs. Originally, we planned to organize and merge a series of APIs. Similar to the v3 upgrade to v4, we will prompt developers to migrate APIs in the current version, and remove obsolete APIs in v5. However, after community communication, we decided to change the plan as follows: Each major version will only adjust a small number of APIs, and the original deprecated APIs will continue to be compatible in the new version, and will be deferred until the next major version to remove. This time we changed the following parts, and v5 will be fully compatible with the original writing:

  • Popup like components open and visible are unified to open to match to HTML Spec.
  • dropdownClassName and popupClassName are unified to popupClassName for better semantics.
  • Structural syntactic sugar (e.g. ) is replaced with data-driven in preparation for performance optimization.
  • Deprecate static methods (such as Message.error), and recommend application layer encapsulation to support React 18 concurrent mode.

Components removement

v5 will remove the Comment and PageHeader components, and BackTop will become a FloatButton sub-component. Since the Comment component itself provides no actual capabilities other than styling, developers still need extra work to implement the commenting functionality. Also, we decided to remove it from v5 due to not many actual usage scenarios, but you can still find it in the compatibility pack. The PageHeader component also required some development work to make it work, so we moved it into ProComponents and used it with ProLayout to provide real interactivity.

Upgrade Guide

As mentioned in Compatibility Adjustments, since v5 will not make API Break Changes, you can try migrating via our codemod tool. For Moment.js, you can use the @ant-design/moment-webpack-plugin to replace. If your project relies on antd's less files, please refer to our migration documentation for compatibility via less-loader. For detailed documentation, please click here.

Future plan

In the future we plan to provide more components, some of them are already on the agenda, such as WaterMark, QrCode, ColorPicker. We've heard the voices for Table performance, and we plan to provide virtual scrolling capabilities for the display state, which will natively support fixed column capabilities. Also, since in v4 we have converged the structural syntactic sugar into data-driven properties, we have better opportunities to optimize performance, including but not limited to Menu, Table, Steps, Collapse, Tabs, Dropdown, and more.

On the design side, we will update the official site to provide more component-level design guidelines, which will be continuously updated by the design team. We have written a lot of articles in the Chinese community in the past, and we hope to take this opportunity to provide English versions of the articles so that international developers and designers can read them together. let us wait and see.

Write at the end

After 7 years, Ant Design has become an ecologically rich community. During the period, the help of community is inseparable. From Ant Design v4, a large number of community volunteers participated to v5, and most of the functions were completed by community. It is you who made Ant Design v5 complete the research and development work so quickly, and you made open source beautiful. Thank you everyone!


Top comments (1)

afc163 profile image