# Migrating from Ant Design v5 to v6: The Official Guide

> 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.

- Repository: [Ant Design Team/ant-design](https://github.com/ant-design/ant-design)
- Tags: migration-guide
- Published: 2026-02-27

---

**The official migration guide for Ant Design v5 to v6 is located at [`docs/react/migration-v6.en-US.md`](https://github.com/ant-design/ant-design/blob/main/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`](https://github.com/ant-design/ant-design/blob/main/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`](https://github.com/ant-design/ant-design/blob/main/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:

```bash

# 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`](https://github.com/ant-design/ant-design/blob/main/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`](https://github.com/ant-design/ant-design/blob/main/Modal.tsx) and [`Alert.tsx`](https://github.com/ant-design/ant-design/blob/main/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:

```tsx
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`:

```tsx
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`](https://github.com/ant-design/ant-design/blob/main/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.

### How do I disable the new blur effect on Modal and Drawer masks?

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.