Migrating from Ant Design v5 to v6: The Official Guide

Question

Find the official guide for migrating Ant Design v5 to v6. Learn about React 18+ requirements, package upgrades, and over 150 breaking API changes in this comprehensive resource.

Accepted Answer

The official migration guide for Ant Design v5 to v6 is located at docs/react/migration-v6.en-US.md in the ant-design/ant-design repository, covering React 18+ requirements, package upgrades, and over 150 breaking API changes.

Ant Design v6 introduces significant architectural improvements including CSS variables support, a streamlined styling API, and modern React features. This guide walks you through the complete migration path based on the official documentation and source code implementation.

Prerequisites for Migrating from Ant Design v5 to v6

Before beginning your migration, ensure your codebase meets the baseline requirements outlined in the official guide.

React Version Requirements

Ant Design v6 requires React 18 or higher. The framework drops support for React 17 entirely and removes the @ant-design/v5-patch-for-react-19 compatibility shim that was necessary in v5. According to docs/react/migration-v6.en-US.md, you must upgrade your project to the latest v5 release first, then ensure React 18+ is installed before installing antd@6.

Browser Support Changes

Version 6 targets modern browsers exclusively. Internet Explorer is no longer supported. The codebase in docs/react/migration-v6.en-US.md specifies that you should verify your target browser matrix aligns with modern evergreen browsers before proceeding.

Installation and Package Upgrades

You must upgrade both the core package and the icons library simultaneously to avoid version conflicts.

Upgrading antd and Icons

Install version 6 of both packages using your preferred package manager:


# npm

npm install --save antd@6 @ant-design/icons@6

# yarn

yarn upgrade antd@6 @ant-design/icons@6

# pnpm

pnpm update antd@6 @ant-design/icons@6

The @ant-design/icons package must be upgraded to v6 because older icon versions are incompatible with the new DOM structure and styling system introduced in Ant Design v6, as noted in the migration guide.

Breaking Changes When Migrating from Ant Design v5 to v6

Ant Design v6 introduces structural changes to components, requiring updates to custom CSS selectors and component props.

React Version Support and Shim Removal

As implemented in the source requirements, antd@6 strictly enforces React 18+. The @ant-design/v5-patch-for-react-19 package is no longer necessary and should be removed from your dependencies if you were using it for React 19 compatibility in v5.

DOM Structure and CSS Variables

Many components now use a new DOM layout and rely on CSS variables for theming instead of Less variables. According to docs/react/migration-v6.en-US.md, custom CSS selectors that target internal component nodes (such as .ant-btn > span) may break and require adjustment to target the new class names or use the provided classNames API.

API Deprecations and the New classNames/styles System

Over 150 props have been renamed or moved to the new classNames and styles configuration objects. This is one of the most extensive breaking changes in the migration.

Key examples from the source code:

Alert: closeText is deprecated in favor of closable.closeIcon
Button: iconPosition is renamed to iconPlacement
Modal: bodyStyle is moved to styles.body

The implementation in components like Modal.tsx and Alert.tsx now expects these properties nested within classNames or styles objects rather than as top-level props.

Overlay Components and Mask Blur

Modal, Drawer, and other overlay components now apply a blur effect to the mask by default. You can disable this behavior globally via ConfigProvider if you prefer the v5 appearance:

import { ConfigProvider, Modal, Drawer } from 'antd';

export default () => (
  <ConfigProvider
    modal={{ mask: { blur: false } }}
    drawer={{ mask: { blur: false } }}
  >
    <Modal open={true}>Content</Modal>
    <Drawer open={true}>Content</Drawer>
  </ConfigProvider>
);

Tag Component Margin Changes

The default trailing margin on Tag components has been removed. To restore the v5 spacing behavior globally, configure the ConfigProvider:

import { ConfigProvider, Tag } from 'antd';

export default () => (
  <ConfigProvider
    tag={{
      styles: {
        root: { marginInlineEnd: 8 },
      },
    }}
  >
    <Tag>Tag A</Tag>
    <Tag>Tag B</Tag>
    <Tag>Tag C</Tag>
  </ConfigProvider>
);

Complete Upgrade Checklist

The official guide concludes with a verification checklist. Before deploying to production, confirm:

React version is 18 or higher
@ant-design/icons is upgraded to version 6
Browser support matrix excludes Internet Explorer
Custom CSS selectors target the new DOM structure
All deprecated props are migrated to classNames or styles APIs
Overlay blur effects are configured as desired
Build completes without errors and console warnings are resolved

Summary

Migrating from Ant Design v5 to v6 requires careful attention to React version compatibility, DOM structure changes, and extensive API updates. Key takeaways include:

Upgrade to React 18+ and @ant-design/icons@6 before installing antd@6
Migrate over 150 deprecated props to the new classNames and styles configuration objects
Update custom CSS selectors to account for new DOM layouts and CSS variables
Configure overlay mask blur and Tag margins via ConfigProvider to match v5 behavior if needed

Frequently Asked Questions

Where is the official Ant Design v5 to v6 migration guide located?

The official migration guide is located at docs/react/migration-v6.en-US.md in the ant-design/ant-design repository on GitHub. This document contains the complete prerequisites, installation instructions, breaking changes list, and upgrade checklist maintained by the core team.

Does Ant Design v6 support React 17?

No, Ant Design v6 does not support React 17. According to the source code requirements in the migration guide, antd@6 strictly requires React 18 or higher and removes the compatibility shim that was previously used for React 19 support in v5.

What happened to bodyStyle and other style props in Ant Design v6?

In Ant Design v6, style-related props like bodyStyle have been moved into the styles object. For example, Modal.bodyStyle is now Modal.styles.body. Similarly, className-related props have been consolidated into the classNames object. This change affects over 150 props across the component library to provide a more consistent styling API.

You can disable the default mask blur effect globally by configuring the ConfigProvider component. Set modal={{ mask: { blur: false } }} and drawer={{ mask: { blur: false } }} on the ConfigProvider to restore the solid mask appearance from v5.