ant-design Documentation

1. Project Overview & Quickstart (ant-design/ant-design) Copy Chapter

File: README.md Copy Chapter

✨ Features Copy Chapter

• 🌈 Enterprise-class UI designed for web applications.
• 📦 A set of high-quality React components out of the box.
• 🛡 Written in TypeScript with predictable static types.
• ⚙️ Whole package of design resources and development tools.
• 🌍 Internationalization support for dozens of languages.
• 🎨 Powerful theme customization based on CSS-in-JS.

🖥 Environment Support Copy Chapter

• Modern browsers
• Server-side Rendering
• Electron

📦 Install Copy Chapter

npm install antd

yarn add antd

pnpm add antd

bun add antd

🔨 Usage Copy Chapter

import { Button, DatePicker } from 'antd';

export default () => (
  <>
    PRESS ME
    <DatePicker placeholder="select date" />
  </>
);

🔗 Links Copy Chapter

• Home page
• Components Overview
• Sponsor
• Change Log
• rc-components
• 🆕 Ant Design X
• Ant Design Pro
• Pro Components
• Ant Design Mobile
• Ant Design Mini
• Ant Design Charts
• Ant Design Web3
• Landing Pages
• Ant Motion
• Scaffold Market
• Developer Instruction
• Versioning Release Note
• FAQ
• Online Playground for bug reports
• Customize Theme
• How to Apply for Being A Collaborator

⌨️ Development Copy Chapter

Use opensumi.run, a free online pure front-end dev environment.

Or clone locally:

$ git clone [email protected]:ant-design/ant-design.git
$ cd ant-design
$ npm install
$ npm start

Open your browser and visit http://127.0.0.1:8001, see more at Development.

🤝 Contributing [](https://makeapullrequest.com) Copy Chapter

Let's build a better antd together.

We warmly invite contributions from everyone. Before you get started, please take a moment to review our Contribution Guide. Feel free to share your ideas through Pull Requests or GitHub Issues. If you're interested in enhancing our codebase, explore the Development Instructions and enjoy your coding journey! :)

For collaborators, adhere to our Pull Request Principle and utilize our Pull Request Template when creating a Pull Request.

Issue funding Copy Chapter

We use Issuehunt to up-vote and promote specific features that you would like to see and implement. Check our backlog and help us:

❤️ Backers [](https://opencollective.com/ant-design#support) Copy Chapter

File: docs/react/common-props.en-US.md Copy Chapter

group: title: Advanced order: 6 title: Common Props Copy Chapter

Tips: The following generic properties apply to most antd components; those not supported are described separately.

File: docs/react/compatible-style.en-US.md Copy Chapter

group: title: Advanced order: 1 title: CSS Compatible Copy Chapter

Default Style Compatibility Copy Chapter

Ant Design supports the last 2 versions of modern browsers. If you need to be compatible with legacy browsers, please perform downgrade processing according to actual needs:

If you need to support older browsers, please use @ant-design/cssinjs StyleProvider for degradation handling according to your actual requirements.

`:where` in selector Copy Chapter

• antd version: >=5.0.0
• MDN: :where
• Browser Compatibility: caniuse
• Minimum Chrome Version Supported: 88
• Default Enabled: Yes

The CSS-in-JS feature of Ant Design uses the ":where" selector by default to lower the CSS selector specificity, reducing the additional cost of adjusting custom styles when upgrading for users. However, the compatibility of the ":where" syntax is relatively poor in older browsers (compatibility). In certain scenarios, if you need to support older browsers, you can use @ant-design/cssinjs to disable the default lowering of specificity (please ensure version consistency with antd).

import { StyleProvider } from '@ant-design/cssinjs';

// Config `hashPriority` to `high` instead of default `low`
// Which will remove `:where` wrapper
export default () => (
  <StyleProvider hashPriority="high">
    <MyApp />
  </StyleProvider>
);

It will turn :where to class selector:

--  :where(.css-bAMboO).ant-btn {
++  .css-bAMboO.ant-btn {
      color: #fff;
    }

Note: After turning off the :where downgrade, you may need to manually adjust the priority of some styles. Or you can use PostCSS plugin to raise application css selector priority. PostCSS provides many plugins can help on this. e.g:

• postcss-scopify
• postcss-increase-specificity
• postcss-add-root-selector

Raise priority through plugin:

--  .my-btn {
++  #root .my-btn {
      background: red;
    }

CSS Logical Properties Copy Chapter

• antd version: >=5.0.0
• MDN：CSS Logical Properties
• Browser Compatibility: caniuse
• Minimum Chrome Version Supported: 89
• Default Enabled: Yes

To unify LTR and RTL styles, Ant Design uses CSS logical properties. For example, the original margin-left is replaced by margin-inline-start, so that it is the starting position spacing under both LTR and RTL. If you need to be compatible with older browsers, you can configure transformers through the StyleProvider of @ant-design/cssinjs:

import { legacyLogicalPropertiesTransformer, StyleProvider } from '@ant-design/cssinjs';

// `transformers` provides a way to transform CSS properties
export default () => (
  <StyleProvider transformers={[legacyLogicalPropertiesTransformer]}>
    <MyApp />
  </StyleProvider>
);

When toggled, styles will downgrade CSS logical properties:

.ant-modal-root {
-- inset: 0;
++ top: 0;
++ right: 0;
++ bottom: 0;
++ left: 0;
}

`@layer` Copy Chapter

• antd version: >=5.17.0
• MDN：CSS @layer
• Browser Compatibility: caniuse
• Minimum Chrome Version Supported: 99
• Default Enabled: No

Ant Design supports configuring @layer for unified css priority downgrade since 5.17.0. After the downgrade, the style of antd will always be lower than the default CSS selector priority, so that users can override the style (please be sure to check the browser compatibility of @layer).When enable layer, the child element must wrap ConfigProvider to update the icon-related styles:

import { StyleProvider } from '@ant-design/cssinjs';
import { ConfigProvider } from 'antd';

export default () => (
  <StyleProvider layer>
    <ConfigProvider>
      <MyApp />
    </ConfigProvider>
  </StyleProvider>
);

antd styles will be encapsulated in @layer to lower the priority:

++  @layer antd {
      :where(.css-bAMboO).ant-btn {
        color: #fff;
      }
++  }

⚠️ zeroRuntime Scenario Notes (Added in 6.0.0)

When zeroRuntime is enabled, Ant Design’s styles are precompiled into a standalone antd.css file. If you also enable the @layer specificity–lowering mechanism, you must ensure that antd.css is placed inside the same layer (e.g., layer(antd)). Otherwise, its specificity will be higher than the styles injected by StyleProvider, causing the lowering mechanism to fail or resulting in unexpected override behavior.

/* global.css / app.css */
@layer theme, base, antd, components, utilities;

/* The precompiled antd.css output by zeroRuntime must explicitly specify a layer */
@import url(antd.css) layer(antd);

If you cannot use the @import ... layer() syntax, you may wrap the content during your build process instead:

@layer antd {
  /* contents of antd.css */
}

autoPrefixer Copy Chapter

• antd version: >=6.0.0
• Browser Compatibility: Automatically adds browser prefixes for wider browser support
• Default Enabled: No

Some styles rely on browser prefixes for compatibility. The autoPrefixer transformer can automatically add browser prefixes to styles, ensuring they work properly across different browsers.

import { autoPrefixTransformer, StyleProvider } from '@ant-design/cssinjs';

export default () => (
  <StyleProvider transformers={[autoPrefixTransformer]}>
    <MyApp />
  </StyleProvider>
);

The final transformed styles:

.sample-box {
--  user-select: none;
++  -webkit-user-select: none;
++  -moz-user-select: none;
++  -ms-user-select: none;
++  user-select: none;
  }

Rem Adaptation Copy Chapter

In responsive web development, there is a need for a convenient and flexible way to achieve page adaptation and responsive design. The px2remTransformer transformer can quickly and accurately convert pixel units in style sheets to rem units relative to the root element (HTML tag), enabling the implementation of adaptive and responsive layouts.

import { px2remTransformer, StyleProvider } from '@ant-design/cssinjs';

const px2rem = px2remTransformer({
  rootValue: 32, // 32px = 1rem; @default 16
});

export default () => (
  <StyleProvider transformers={[px2rem]}>
    <MyApp />
  </StyleProvider>
);

The resulting transformed styles:

.px2rem-box {
-  width: 400px;
+  width: 12.5rem;
   background-color: green;
-  font-size: 32px;
+  font-size: 1rem;
   border: 10PX solid #f0f;
 }

 @media only screen and (max-width: 600px) {
   .px2rem-box {
     background-color: red;
-    margin: 10px;
+    margin: 0.3125rem;
   }
 }

Options Copy Section

For more details, please refer to: px2rem.ts#Options

Shadow DOM Usage Copy Chapter

Since <style /> tag insertion is different from normal DOM in Shadow DOM scenario, you need to use StyleProvider of @ant-design/cssinjs to configure the container property to set the insertion position:

import { StyleProvider } from '@ant-design/cssinjs';
import { createRoot } from 'react-dom/client';

const shadowRoot = someEle.attachShadow({ mode: 'open' });
const container = document.createElement('div');
shadowRoot.appendChild(container);
const root = createRoot(container);

root.render(
  <StyleProvider container={shadowRoot}>
    <MyApp />
  </StyleProvider>,
);

Compatible with Third-party Style Libraries Copy Chapter

In some cases, you may need antd to coexist with other style libraries, such as Tailwind CSS, Emotion, styled-components, etc. Unlike traditional CSS solutions, these third-party libraries are often not easy to override antd styles by increasing CSS selector priority. You can configure @layer for antd to lower its CSS selector weight, and arrange @layer order to solve style override problems:

antd config `@layer` Copy Section

As mentioned earlier, when using StyleProvider, you must wrap ConfigProvider to update icon-related styles:

import { StyleProvider } from '@ant-design/cssinjs';

export default () => (
  <StyleProvider layer>
    <ConfigProvider>
      <MyApp />
    </ConfigProvider>
  </StyleProvider>
);

TailwindCSS Arrange `@layer` Copy Section

Before starting the following configuration, you need to enable @layer feature.

TailwindCSS v3

In global.css, adjust @layer to control the order of style override. Place tailwind-base before antd:

@layer tailwind-base, antd;

@layer tailwind-base {
  @tailwind base;
}
@tailwind components;
@tailwind utilities;

TailwindCSS v4

In global.css, adjust @layer to control the order of style override. Place antd in the right position:

@layer theme, base, antd, components, utilities;

@import 'tailwindcss';

reset.css and antd.css Copy Section

If you are using Ant Design’s reset.css, you need to assign it to a specific @layer to prevent it from overriding the lowered-specificity antd styles. Similarly, in the zeroRuntime scenario, if you import antd.css separately, you must also place it inside layer(antd) to keep the layer hierarchy consistent:

/* Both reset.css and antd.css must specify a layer */
@layer reset, antd;

/* reset styles */
@import url(reset.css) layer(reset);

/* antd styles */
@import url(antd.css) layer(antd);

This ensures that:

• reset.css will not override Ant Design styles that have been lowered via @layer
• antd.css (in zeroRuntime mode) stays aligned with the layer injected by StyleProvider
• Layer order still works correctly with third-party styling systems such as Tailwind, Emotion, or other CSS-in-JS libraries

With other CSS-in-JS libraries Copy Section

After configuring @layer for antd, you don't need to do any additional configuration for other CSS-in-JS libraries. Your CSS-in-JS can completely override antd styles.

SSR Scene Copy Section

When using SSR, styles are often rendered inline in HTML through <style />. At this time, please make sure that the styles with the specified @layer priority order are loaded before @layer is used.

❌ Wrong

<head>
  
  <style>
    @layer antd {
      /** ... */
    }
  </style>

  
  <link rel="stylesheet" href="/b9a0m0b9o0o3.css" />
  
  <style>
    @layer xxx, antd;
  </style>
</head>

✅ Correct

<head>
  
  <link rel="stylesheet" href="/b9a0m0b9o0o3.css" />
  
  <style>
    @layer xxx, antd;
  </style>

  
  <style>
    @layer antd {
      /** ... */
    }
  </style>
</head>

File: docs/react/contributing.en-US.md Copy Chapter

group: title: Other order: 1 title: Contributing Copy Chapter

The following is a set of guidelines for contributing to Ant Design. Please spend several minutes reading these guidelines before you create an issue or pull request.

Code of Conduct Copy Chapter

We have adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Open Development Copy Chapter

All work on Ant Design happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

Branch Organization Copy Chapter

According to our release schedule, we maintain two branches, master and feature. If you send a bugfix pull request, please do it against the master branch, if it's a feature pull request, please do it against the feature branch.

Bugs Copy Chapter

We are using GitHub Issues for bug tracking. The best way to get your bug fixed is by using our issue helper and provide reproduction steps with this template.

Before you report a bug, please make sure you've searched existing issues, and read our FAQ.

Proposing a Change Copy Chapter

If you intend to change the public API or introduce new feature, we also recommend you use our issue helper to create a feature request issue.

If you want to help on new API, please reference API Naming Rules to name it.

Your First Pull Request Copy Chapter

Working on your first Pull Request? You can learn how from this free video series:

How to Contribute to an Open Source Project on GitHub

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs or small features that have a relatively limited scope. This is a great place to get started.

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort.

If somebody claims an issue but doesn't follow up for more than two weeks, it's fine to take over it but you should still leave a comment.

Sending a Pull Request Copy Chapter

The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation.

Before submitting a pull request, please make sure the following is done:

1. Fork the repository and create your branch from the correct branch.
2. Run npm install in the repository root.
3. If you've fixed a bug or added code that should be tested, add tests!
4. Ensure the test suite passes (npm run test). Tip: npm test -- --watch TestName is helpful in development.
5. Run npm test -- -u to update the jest snapshots and commit these changes as well (if there are any updates).
6. Ensure the UI change passes npm run test:image, Run npm run test:image -- -u to update UI snapshots and commit these changes as well (if there are any updates), UI test base on Docker, need download the corresponding installation according to the platform
7. Make sure your code lints (npm run lint). Tip: Lint runs automatically when you git commit (Use Git Hooks).
8. Finally, please make sure that all GitHub CI checks pass, if they fail, you can click detail to enter the details to view the reason.

Sending a Pull Request to react-component:

Since antd's components are based on react-component, sometimes you may need to send pull request to the corresponding react-component repository. If it's a bugfix pull request, after it's merged, the core team will release a patch release for that component as soon as possible, then you only need to reinstall antd in your project to get the latest patch release. If it's a feature pull request, after it's merged, the core team will release a minor release, then you need raise another pull request to Ant Design to update dependencies, document and TypeScript interfaces (if needed).

Development Workflow Copy Chapter

npm or yarn are recommended as package management tools.

After you clone the antd code and use following commands to install dependencies:

You can also run the following common commands:

Run locally Copy Section

Runs Ant Design website locally.

Check the code style Copy Section

Run tests Copy Section

runs the complete test suite. (Make sure the NODE_ENV environment variable is unset, or it may causing some problems.)

Compile Copy Section

compiles TypeScript code to the lib and es directory.

Build Copy Section

creates UMD build of antd.

Development Tools Copy Chapter

• VSCode plugin for CSS in JS: https://marketplace.visualstudio.com/items?itemName=shezhangzhang.antd-design-token
• Ant Design cheatsheet in VS Code: https://github.com/fi3ework/vscode-antd-rush

Being a collaborator Copy Chapter

If you are an active contributor and are willing to work with Ant Design Team in our opensource workflow, you can apply to be a outside collaborator.

You can also refer to the following contribution guide to become an antd contributor:

• How to Grow as a Collaborator

File: docs/react/customize-theme.en-US.md Copy Chapter

group: title: Advanced order: 1 order: 0 title: Customize Theme demo: tocDepth: 4 Copy Chapter

Ant Design allows you to customize our design tokens to satisfy UI diversity from business or brand requirements, including primary color, border radius, border color, etc.

Since 5.0, we provide a new way to customize themes. Different from the less and CSS variables of the 4.x version, with CSS-in-JS, the ability of theming has also been enhanced, including but not limited to:

1. Switching theme dynamically；
2. Multiple themes；
3. Customizing theme variables for some components；
4. ...

Basic Usage Copy Chapter

We call the smallest element that affects the theme Design Token. By modifying the Design Token, we can present various themes or components. You can pass theme to ConfigProvider to customize theme.

:::warning
ConfigProvider will not take effect on static methods such as message.xxx, Modal.xxx, notification.xxx, because in these methods, antd will dynamically create new ones through ReactDOM.render React entities. Its context is not the same as the context of the current code, so context information cannot be obtained.

When you need context information (such as the content configured by ConfigProvider), you can use the Modal.useModal method to return the modal entity and the contextHolder node. Just insert it where you need to get the context, or you can use App Component to simplify the problem of usingModal and other methods that need to manually implant the contextHolder.
:::

Customize Design Token Copy Section

By modifying token property of theme, we can modify Design Token globally. Some tokens will affect other tokens. We call these tokens Seed Token.

Customize Design Token

Use Preset Algorithms Copy Section

Themes with different styles can be quickly generated by modifying algorithm. We provide three sets of preset algorithms by default:

• default algorithm theme.defaultAlgorithm
• dark algorithm theme.darkAlgorithm
• compact algorithm theme.compactAlgorithm

You can switch algorithms by modifying the algorithm property of theme in ConfigProvider.

Use Preset Algorithms

Customize Component Token Copy Section

In addition to Design Token, each component will also have its own Component Token to achieve style customization capabilities for components, and different components will not affect each other. Similarly, other Design Token of components can also be overridden in this way.

:::info{title=Algorithm of Component Token}
By default, all component tokens can only override global token and will not be derived based on Seed Token.

In version >= 5.8.0, component tokens support the algorithm property, which can be used to enable algorithm or pass in other algorithms.
:::

Customize Component Token

Disable Motion Copy Section

antd has built-in interaction animations to make enterprise-level pages more detailed. In some extreme scenarios, it may affect the performance of page interaction. If you need to turn off the animation, try setting motion of token to false:

Disable Motion

Advanced Copy Chapter

Zero Runtime {#zero-runtime} Copy Section

Starting from 6.0.0, we provide zeroRuntime mode to further improve application performance. When enabled, Ant Design will no longer generate component styles at runtime, so you need to manually import the style files.

import 'antd/dist/antd.css';

export default () => (
  <ConfigProvider theme={{ zeroRuntime: true }}>
    <App />
  </ConfigProvider>
);

antd/dist/antd.css contains all antd component styles, but does not include hashed className. If you want to import fewer styles, or cannot use the default styles due to configuration changes like prefix, we recommend using @ant-design/static-style-extract to generate static styles.

import fs from 'fs';
import { extractStyle } from '@ant-design/static-style-extract';

const cssText = extractStyle({
  includes: ['Button'], // Only include Button component styles
});

fs.writeFileSync('/path/to/somewhere', cssText);

Switch Themes Dynamically Copy Section

In v5, dynamically switching themes is very simple for users, you can dynamically switch themes at any time through the theme property of ConfigProvider without any additional configuration.

Switch Themes Dynamically

Nested Theme Copy Section

By nesting ConfigProvider you can apply local theme to some parts of your page. Design Tokens that have not been changed in the child theme will inherit the parent theme.

Nested Theme

Consume Design Token Copy Section

If you want to consume the Design Token under the current theme, we provide useToken hook to get Design Token.

Consume Design Token

Static consume (e.g. less) Copy Section

When you need token out of React life cycle, you can use static function to get them:

import { theme } from 'antd';

const { getDesignToken } = theme;

const globalToken = getDesignToken();

Same as ConfigProvider, getDesignToken could also accept a config object as theme:

import type { ThemeConfig } from 'antd';
import { theme } from 'antd';
import { createRoot } from 'react-dom/client';

const { getDesignToken, useToken } = theme;

const config: ThemeConfig = {
  token: {
    colorPrimary: '#1890ff',
  },
};

// By static function
const globalToken = getDesignToken(config);

// By hook
const App = () => {
  const { token } = useToken();
  return null;
};

// Example for rendering
createRoot(document.getElementById('#app')).render(
  <ConfigProvider theme={config}>
    <App />
  </ConfigProvider>,
);

If you want to use in preprocess style framework like less, use less-loader for injection:

{
  loader: "less-loader",
  options: {
    lessOptions: {
      modifyVars: mapToken,
    },
  },
}

Compatible package provide convert function to transform to v4 less variable. Read this for detail.

Theme editor Copy Section

We provide tools to help users debug themes: Theme Editor

You can use this tool to freely modify Design Token to meet your theme expectations.

Design Token Copy Chapter

In Design Token, we provide a three-layer structure that is more suitable for the design, and disassemble the Design Token into three parts: Seed Token, Map Token and Alias Token. These three groups of Tokens are not simple groupings, but a three-layer derivation relationship. Map Tokens are derived from Seed Tokens, and Alias Tokens are derived from Map Tokens. In most cases, using Seed Tokens is sufficient for custom themes. But if you need a higher degree of theme customization, you need to understand the life cycle of Design Token in antd.

Life of Design Token Copy Section

Seed Token Copy Section

Seed Token means the origin of all design intent. For example, we can change the theme color by changing colorPrimary, and the algorithm inside antd will automatically calculate and apply a series of corresponding colors according to the Seed Token:

const theme = {
  token: {
    colorPrimary: '#1890ff',
  },
};

Map Token Copy Section

Map Token is a gradient variable derived from Seed. It is recommended to implement custom Map Token through theme.algorithm, which can ensure the gradient relationship between Map Tokens. It can also be overridden by theme.token to modify the value of some map tokens individually.

const theme = {
  token: {
    colorPrimaryBg: '#e6f7ff',
  },
};

Alias Token Copy Section

Alias Token is used to control the style of some common components in batches, which is basically a Map Token alias, or a specially processed Map Token.

const theme = {
  token: {
    colorLink: '#1890ff',
  },
};

Algorithm Copy Section

The basic algorithm is used to expand the Seed Token into a Map Token, such as calculating a gradient color palette from a basic color, or calculating rounded corners of various sizes from a basic rounded corner. Algorithms can be used alone or in any combination, for example, dark and compact algorithms can be combined to get a dark and compact theme.

import { theme } from 'antd';

const { darkAlgorithm, compactAlgorithm } = theme;

const theme = {
  algorithm: [darkAlgorithm, compactAlgorithm],
};

API Copy Chapter

Theme Copy Section

ComponentsConfig Copy Section

algorithm of component is false by default, which means tokens of component will only override global token. When it is set with true, the algorithm will be the same as global. You can also pass algorithm or Array of algorithm, and it will override algorithm of global.

cssVar {#css-var} Copy Section

SeedToken Copy Section

MapToken Copy Section

Inherit all SeedToken properties

AliasToken Copy Section

Inherit all SeedToken and MapToken properties

FAQ Copy Chapter

Why component re-mounted when `theme` changed from `undefined` to some object or to `undefined`? Copy Section

In ConfigProvider, we pass context through DesignTokenContext. When theme is undefined, a layer of Provider will not be set, so React VirtualDOM structure changes from scratch or from existence to nothing, causing components to be re-mounted. Solution: Replace undefined with an empty object {}.

File: docs/react/faq.en-US.md Copy Chapter

group: title: Other order: 2 title: FAQ Copy Chapter

Here are the frequently asked questions about Ant Design and antd that you should look up before you ask in the community or create a new issue. We also maintain a FAQ issues label for common GitHub issues.

Is there a difference between `undefined` and `null` in the controlled components of `antd`? Copy Chapter

Yes. antd will treat undefined as uncontrolled but null as controlled component which means empty value of it.

As input element, React treats both undefined and null as uncontrolled. When the value is converted from a valid value to undefined or null, the component is no longer controlled, which causes some unexpected cases.

But in antd, undefined is treated as uncontrolled, and null is used as an explicit empty value of controlled components. To deal with some cases (e.g. allowClear) like clearing the value when the value is non-primitive. If you need a component controlled with the value valid, just set the value as null.

Note: For options in Select-like components, it is strongly recommended not to use undefined and null as value in option. Please use string | number as a valid value in option.

Can I use internal API which is not documented on the site? Copy Chapter

NOT RECOMMENDED. Internal API is not guaranteed to be compatible with future versions. It may be removed or changed in some versions. If you really need to use it, you should make sure these APIs are still valid when upgrading to a new version or just lock version for usage.

Why API request should be strict discussion? Copy Chapter

We are cautious when adding APIs because some APIs may not be abstract enough to become historical debt. For example, when there is a need to change the way of interaction, these poor abstractions may cause breaking changes. To avoid such problems, we recommend that new features be implemented through HOCs first.

`Select Dropdown DatePicker TimePicker Popover Popconfirm` disappears when I click another popup component inside it. How do I resolve this? Copy Chapter

This is an old bug that has been fixed since v3.11.x. If you're using an older version, you can use <Select getPopupContainer={trigger => trigger.parentElement}> to render a component inside Popover. (Or other getXxxxContainer props)

https://ant.design/components/select/#Select-props

Related issue: #3487 #3438

How do I prevent `Select Dropdown DatePicker TimePicker Popover Popconfirm` scrolling with the page? Copy Chapter

Use <Select getPopupContainer={trigger => trigger.parentElement}> (API reference) to render a component inside the scroll area. If you need to config this globally in your application, try <ConfigProvider getPopupContainer={trigger => trigger.parentElement}> (API reference)

And make sure that parentElement is position: relative or position: absolute.

Related issue: #3487 #3438

How do I modify the default theme of Ant Design? Copy Chapter

See: customize-theme.

How do I modify `Menu`/`Button`(etc.)'s style? Copy Chapter

While you can override a component's style, we don't recommend doing so. antd is not only a set of React components, but also a design specification as well.

How to avoid breaking change when update version? Copy Chapter

antd will avoid breaking change in minor & patch version. You can safely do the following things:

• Official demo usage
• FAQ suggestion. Including codesandbox sample, marked as FAQ issue

And which you should avoid doing:

• Bug as feature. It will break in any other case (e.g. Use div as Tabs children)
• Use magic code to realize requirement but which can be realized with normal API

How to use other date-time lib like Moment.js? Copy Chapter

Please refer to Use custom date library.

It doesn't work when I change `defaultValue` dynamically. Copy Chapter

The defaultXxxx (e.g. defaultValue) of Input/Select(etc...) only works on the first render. It is a specification of React. Please read React's documentation.

Why does modifying props in mutable way not trigger a component update? Copy Chapter

antd use shallow compare of props to optimize performance. You should always pass the new object when updating the state. Please ref React's document

Does `antd` have a mirror in China? Copy Chapter

Yes, you can visit https://ant-design.antgroup.com.

After I set the `value` of an `Input`/`Select`(etc.) component, the value cannot be changed by user's action. Copy Chapter

Try onChange to change value, and please read React's documentation.

Components are not vertically aligned when placed in single row. Copy Chapter

Try Space component to make them aligned.

antd overrides my global styles Copy Chapter

Yes, antd is designed to help you develop a complete background application. To do so, we override some global styles for styling convenience, and currently these cannot be removed or changed. More info at https://github.com/ant-design/ant-design/issues/4331 .

Alternatively, follow the instructions in How to avoid modifying global styles?

I cannot install `antd` and `antd`'s dependencies in mainland China. Copy Chapter

To potentially solve this, try npm mirror china and cnpm.

I set `dependencies.antd` as the git repository in `package.json`, but it doesn't work. Copy Chapter

Please install antd with either npm or yarn.

`message` and `notification` is lower case, but other components are capitalized. Is this a typo? Copy Chapter

No, message is just a function, not a React Component, thus it is not a typo that it is in lower case.

`antd` doesn't work well in mobile. Copy Chapter

Please check Ant Design Mobile as a possible solution, as antd has not been optimized to work well on mobile. You can also try the react-component repositories which start with 'm-' 'rn-', which are also designed for mobile.

Does `antd` supply standalone files like 'React'? Copy Chapter

Yes, you can import antd with script tag, but we recommend using npm to import antd, as it is simple and easy to maintain.

How do I extend antd's components? Copy Chapter

If you need some features which should not be included in antd, try to extend antd's component with HOC. more

antd will have a strict discussion on the demand for new components to prevent API corruption and become historical debt. And it is also more inclined to provide atomic capabilities for APIs so that developers can customize the features they need more flexibly.

How to get the definition which is not export? Copy Chapter

antd expose the basic component definitions. For the unexposed props, you can get them via the utility types provided by antd. For example:

import type { Checkbox, CheckboxProps, GetProp, GetProps, GetRef, Input } from 'antd';

// Get Props
type CheckboxGroupProps = GetProps<typeof Checkbox.Group>;

// Get Prop
type CheckboxValue = GetProp<CheckboxProps, 'value'>;

// Get Ref
type InputRef = GetRef<typeof Input>;

Date-related components locale is not working? Copy Chapter

Please check whether you have imported dayjs locale correctly.

import dayjs from 'dayjs';

import 'dayjs/locale/zh-cn';

dayjs.locale('zh-cn');

Please check whether there are two versions of dayjs installed.

npm ls dayjs

If you are using a mismatched version of dayjs with antd's dayjs in your project. That would be a problem cause locale not working.

How do I fix dynamic styles while using a Content Security Policy (CSP)? Copy Chapter

You can configure nonce by ConfigProvider.

When I set `mode` to `DatePicker`/`RangePicker`, why can I not select a year or month anymore? Copy Chapter

In a real world development, you may need a YearPicker, MonthRangePicker or WeekRangePicker. You are trying to add mode to DatePicker/RangePicker expected to implement those pickers. However, the DatePicker/RangePicker cannot be selected and the panels won't close now.

• Reproduction link: https://codesandbox.io/s/dank-brook-v1csy
• Same issues：#15572, #16436, #11938, #11735, #11586, #10425, #11053

Like the explanation explains, this is because <DatePicker mode="year" /> does not equal the YearPicker, nor is <RangePicker mode="month" /> equal to MonthRangePicker. The mode property was added to support showing time picker panel in DatePicker in antd 3.0, which simply controls the displayed panel, and won't change the original date picking behavior of DatePicker/RangePicker (for instance you will still need to click date cell to finish selection in a DatePicker, whatever the mode is).

Likewise, disabledDate cannot work on year/month panels of <DatePicker mode="year/month" />, but only on cells of date panel.

:::success{title=Workaround} You can refer to this article or this article, using mode and onPanelChange to encapsulate a YearPicker or MonthRangePicker for your needs.

Or you can simply upgrade to [email protected], in which we added more XxxPickers to meet those requirements, and disabledDate could be effect on those pickers too. :::

message/notification/Modal.confirm lost styles when set `prefixCls` on ConfigProvider? Copy Chapter

Static methods like message/notification/Modal.confirm are not using the same render tree as ``, but rendered to independent DOM node created by ReactDOM.render, which cannot access React context from ConfigProvider. Consider two solutions here:

1. Replace original usages with message.useMessage, notification.useNotification and Modal.useModal.

2. Use App.useApp to get message/notification/modal instance.

Why shouldn't I use component internal props or state with ref? Copy Chapter

You should only access the API by official doc with ref. Directly access internal props or state is not recommended which will make your code strong coupling with current version. Any refactor will break your code like refactor with Hooks version, delete or rename internal props or state, adjust internal node constructor, etc.

Why we need align pop component with `open` prop? Copy Chapter

For historical reasons, the display names of the pop components are not uniform, and both open and visible are used. This makes the memory cost that non-tsx users encounter when developing. It also leads to ambiguity about what name to choose when adding a feature. So we want to unify the attribute name, you can still use the original visible and it will still be backward compatible, but we will remove this attribute from the documentation as of v5.

Dynamic style using `:where` selector which not support old browser. Copy Chapter

Please ref dynamic theme document Legacy Browser Compatible part.

CSS-in-JS css priority conflict with tailwindcss? Copy Chapter

Same as above. You can adjust antd css priority to override. Related issue: #38794

How to let CSS-in-JS work with shadow DOM? Copy Chapter

Please ref document Shadow Dom Usage.

How to disable motion? Copy Chapter

Config with SeedToken:

import { ConfigProvider } from 'antd';

<ConfigProvider theme={{ token: { motion: false } }}>
  <App />
</ConfigProvider>;

How to support SSR？ Copy Chapter

Please ref dynamic theme document SSR part.

What is the relationship between colorPrimary and colorInfo and colorLink in V5? Copy Chapter

In the Ant Design Token system, colorPrimary and colorInfo are both Seed Token, so they are independent of each other. colorLink is an Alias Token, inherits colorInfo by default, and is independent of colorPrimary.

How to spell Ant Design correctly? Copy Chapter

Here are some typical wrong examples:

• ❌ AntD
• ❌ antD
• ❌ Antd
• ❌ ant design
• ❌ AntDesign
• ❌ antdesign
• ❌ Antdesign

Do you guys have any channel or website for submitting monetary donations, like through PayPal or Alipay? Copy Chapter

https://opencollective.com/ant-design

Use Form's `setFieldsValue` method to report an error if the object type contains `null` Copy Chapter

When we try to set the form value using the setFieldsValue method in the form instance of the form component, if the passed object contains the type null, such as:

// This is not real world code, just for explain
import { Form } from 'antd';

type Test = {
  value: string[] | null;
};

export default () => {
  const [form] = Form.useForm<Test>();

  form.setFieldsValue({
    value: null, // Error: Type "null" cannot be assigned to type "string[] | undefined".
  });
};

If you encounter the above error, please check the current project tsconfig.json contains the following configuration:

{
  "strictNullChecks": true
}

The above problem occurs if strictNullChecks is set to true, If you can determine the project don't need this configuration (see strictNullChecks to judge whether need the configuration). You can try changing to false to turn off the control strict check. However, if you do need to enable this feature, you can avoid this situation by using other types instead of null when defining types

Why doesn't antd handle precision issues encountered with browser zoom? Copy Chapter

Different browsers have different rendering behaviors when zooming. Fixing a precision issue in one browser often leads to issues in others. Additionally, zoom-related precision issues typically occur at extreme zoom levels, which are uncommon in regular use. The inconsistency in rendering arises from how browsers calculate and render elements during zoom operations, including subpixel rendering, rounding differences, and layout recalculations. Addressing these issues requires a significant amount of browser-specific code, which can negatively impact performance and maintainability, and may also be broken by iterations in the browsers themselves.

The antd component reported an error when using the App Router of Next.js Copy Chapter

If you are using the App Router of Next.js, when you use the sub-components provided by some antd components, such as Select.Option , Form.Item, Typography.Title, etc., you may get the following error:

Error: Cannot access .Option on the server. You cannot dot into a client module from a server component. You can only pass the imported name through.

Currently, this problem is waiting for Next.js to give an official solution. There are two workarounds as of now if you need to use sub-components in your page with the App Router:

• Create a wrapper component that extracts the sub-components that you need, and re-exports them. Take the Typography component as an example. A wrapper component would look something like this:

'use client';

import React from 'react';
import { Typography as OriginTypography } from 'antd';
import type { LinkProps } from 'antd/es/typography/Link';
import type { ParagraphProps } from 'antd/es/typography/Paragraph';
import type { TextProps } from 'antd/es/typography/Text';
import type { TitleProps } from 'antd/es/typography/Title';

const Title = React.forwardRef<HTMLElement, TitleProps & React.RefAttributes<HTMLElement>>(
  (props, ref) => <OriginTypography.Title ref={ref} {...props} />,
);

const Paragraph = React.forwardRef<HTMLElement, ParagraphProps & React.RefAttributes<HTMLElement>>(
  (props, ref) => <OriginTypography.Paragraph ref={ref} {...props} />,
);

const Link = React.forwardRef<HTMLElement, LinkProps & React.RefAttributes<HTMLElement>>(
  (props, ref) => <OriginTypography.Link ref={ref} {...props} />,
);

const Text = React.forwardRef<HTMLElement, TextProps & React.RefAttributes<HTMLElement>>(
  (props, ref) => <OriginTypography.Text ref={ref} {...props} />,
);

export { Title, Link, Text, Paragraph };

• You can also make the page fully client-rendered by adding use client tag at the beginning of your page's source:

'use client';

// This is not real world code, just for explain
export default () => {
  return (
    
      <Form>
        <Form.Item>
          Button
        </Form.Item>
      </Form>
    
  );
};

File: docs/react/getting-started.en-US.md Copy Chapter

group: title: Basic Usage order: 0 order: 0 title: Getting Started Copy Chapter

Ant Design React is dedicated to providing a good development experience for programmers. Before starting, it is recommended to learn React first, and correctly install and configure Node.js v16 or above.

The official guide also assumes that you have intermediate knowledge about HTML, CSS, and JavaScript, and React. If you are just starting to learn front-end or React, it may not be the best idea to use the UI framework as your first step.

Finally, if you are working in a local development environment, please refer to Scaffolding Guide to create a new project.

Your First Example Copy Chapter

Here is a simple online codesandbox demo of an Ant Design component to show the usage of Ant Design React.

First Example

Follow the steps below to play around with Ant Design yourself:

1. Create a codesandbox Copy Section

Visit https://u.ant.design/reproduce to create a codesandbox -- don't forget to press the save button as well to create a new instance.

2. Use and modify an antd component Copy Section

Replace the contents of index.js with the following code. As you can see, there is no difference between antd's components and typical React components.

If you have already set things up by following the Use with create-react-app, replace the content of /src/index.js as follows:

import React, { useState } from 'react';
import { DatePicker, message } from 'antd';
import { createRoot } from 'react-dom/client';

import './index.css';

const App = () => {
  const [date, setDate] = useState(null);
  const [messageApi, contextHolder] = message.useMessage();
  const handleChange = (value) => {
    messageApi.info(`Selected Date: ${value ? value.format('YYYY-MM-DD') : 'None'}`);
    setDate(value);
  };
  return (
    
      <DatePicker onChange={handleChange} />
      
        Selected Date: {date ? date.format('YYYY-MM-DD') : 'None'}
      
      {contextHolder}
    
  );
};

createRoot(document.getElementById('root')).render(<App />);

3. Explore more components Copy Section

You can view the list of components in the side menu of the Components page, such as the Alert component. Plenty of examples are also provided in the component pages and API documentation as well.

Click the "Open in Editor" icon in the first example to open an editor with source code to use out-of-the-box. Now you can import the Alert component into the codesandbox:

- import { DatePicker, message } from 'antd';
+ import { DatePicker, message, Alert } from 'antd';

Now add the following jsx inside the render function.

<DatePicker onChange={value => this.handleChange(value)} />
  
-   Selected Date: {date ? date.format('YYYY-MM-DD') : 'None'}
+   <Alert title="Selected Date" description={date ? date.format('YYYY-MM-DD') : 'None'} />

Select a date, and you can see the effect in the preview area on the right:

OK! Now that you know the basics of using antd components, you are welcome to explore more components in the codesandbox. When reporting a bug with ant design, we also strongly recommend using codesandbox to provide a reproducible demo as well.

4. Next Steps Copy Section

During actual real-world project development, you will most likely need a development workflow consisting of compile/build/deploy/lint/debug/ deployment. You can read the following documents on the subject or use the following scaffolds and examples provided below:

• Ant Design Pro
• create-next-app
• More scaffolds at Scaffold Market

Test with Jest Copy Chapter

If you use create-react-app follow the instructions here instead.

Jest does not support esm modules, and Ant Design uses them. In order to test your Ant Design application with Jest you have to add the following to your Jest config :

"transform": { "^.+\\.(ts|tsx|js|jsx)?$": "ts-jest" }

Import on Demand Copy Chapter

antd supports tree shaking of ES modules, so using import { Button } from 'antd'; would drop js code you didn't use.

Customize your Workflow Copy Chapter

If you want to customize your workflow, we recommend using webpack or vite to build and debug code. You can try out plenty of boilerplates available in the React ecosystem.

There are also some scaffolds which have already been integrated into antd, so you can try and start with one of these and even contribute.

File: docs/react/i18n.en-US.md Copy Chapter

group: title: Advanced order: 5 title: Internationalization Copy Chapter

The default language of antd is currently English. If you wish to use other languages, follow the instructions below.

ConfigProvider Copy Chapter

antd provides a React Component ConfigProvider for configuring antd locale text globally.

import { ConfigProvider } from 'antd';
import frFR from 'antd/locale/fr_FR';

return (
  <ConfigProvider locale={frFR}>
    <App />
  </ConfigProvider>
);

You can see the complete configuration here: ConfigProvider.

Note: fr_FR is the filename, the following table also follows the same rules.

The following languages are currently supported:

Supported languages: Copy Section

See more usage at ConfigProvider.

Adding new language Copy Chapter

If your language is not in above list, feel free to create a locale package based on the en_US language pack and send us a pull request. For reference, you can refer to the pull request of adding the Azerbaijani language as a sample.

Do it step by step:

1. Fork antd and git clone to local, switch to feature branch, pull it to make sure it's up-to-date, create a new branch based on feature branch, all work will be done in it.

   bash Copy

   git clone [email protected]:<your organization>/ant-design.git
   cd ant-design/
   git remote add upstream [email protected]:ant-design/ant-design.git
   git checkout -b <your new branch name> upstream/feature

2. Add the language support for @rc-component/picker, for example this.

3. Add the language support for @rc-component/pagination, for example this.

4. Wait for @rc-component/picker and @rc-component/pagination to release the new version containing the above.

5. Update the @rc-component/picker and @rc-component/pagination versions in antd and add the remaining other necessary content for the language. for example Azerbaijani PR.

6. Add a test case for the language in index.test.tsx.

7. update snapshots, you may also need to delete node_modules, lock files (yarn.lock or package-lock.json) and reinstall at first.

   bash Copy

   npm run test -- components/locale -u

8. Add the language to i18n list docs/react/i18n.en-US.md and docs/react/i18n.zh-CN.md.

9. Watch out the CI status, and if it failed, look at the logs and make some changes until it all passes.

10. Ok, now everything is ready for review.

File: docs/react/introduce.en-US.md Copy Chapter

order: 0 title: Ant Design of React Copy Chapter

Following the Ant Design specification, we developed a React UI library antd () that contains a set of high quality components and demos for building rich, interactive user interfaces.

✨ Features Copy Chapter

• 🌈 Enterprise-class UI designed for web applications.
• 📦 A set of high-quality React components out of the box.
• 🛡 Written in TypeScript with predictable static types.
• ⚙️ Whole package of design resources and development tools.
• 🌍 Internationalization support for dozens of languages.
• 🎨 Powerful theme customization in every detail.

Environment Support Copy Chapter

• Modern browsers
• Server-side Rendering
• Electron

Dropped support of IE8 after antd 2.0. Dropped support of React 15 and IE9/10 after antd 4.0. Dropped support of IE after antd 5.0. Dropped support of React 16/17 after antd 6.0.

Version Copy Chapter

• Stable:

You can subscribe to this feed for new version notifications: https://github.com/ant-design/ant-design/releases.atom

Installation Copy Chapter

Using npm or yarn or pnpm or bun Copy Section

We recommend using npm or yarn or pnpm or bun to install, it not only makes development easier, but also allow you to take advantage of the rich ecosystem of Javascript packages and tooling.

If you are in a bad network environment, you can try other registries and tools like cnpm.

Import in Browser Copy Section

Add script and link tags in your browser and use the global variable antd.

We provide antd.js and antd.min.js reset.css under dist folder in antd's npm package. You can also download these files directly from , or unpkg.

We strongly discourage loading the entire files this will add bloat to your application and make it more difficult to receive bugfixes and updates. Antd is intended to be used in conjunction with a build tool, such as webpack, which will make it easy to import only the parts of antd that you are using.

Note: You should import react, react-dom, dayjs before using antd.js.

Usage Copy Chapter

import React from 'react';
import { DatePicker } from 'antd';

const App = () => {
  return <DatePicker />;
};

export default App;

Use modularized antd Copy Section

antd supports ES modules tree shaking by default.

TypeScript Copy Section

antd provides a built-in ts definition, don't install @types/antd.

Links Copy Chapter

• Home page
• China Mirrors
• Components
• Change Log
• rc-components
• Ant Design Icons
• Ant Design Colors
• 🆕 Ant Design X
• Ant Design Pro
• Pro Components
• Ant Design Mobile
• Ant Design Mini
• Ant Design Charts
• Ant Design Web3
• 🤖 Ant Design CLI
• Landing Pages
• Ant Motion
• Scaffold Market
• Developer Instruction
• Versioning Release Note
• FAQ
• CodeSandbox Template for bug reports
• Awesome Ant Design
• Customize Theme
• How to Apply for Being A Collaborator

Non-React Implementations Copy Chapter

React is used to encapsulate a library of components which embody our design language. We welcome the community to implement our design system in other front-end frameworks of their choice.

Companies using antd Copy Chapter

Ant Design is widely used for building enterprise-level websites both domestically and internationally. You can refer to wappalyzer for reference data. If your company or product uses Ant Design, let us know here!

Contributing Copy Chapter

Please read our CONTRIBUTING.md first.

If you'd like to help us improve antd, just create a Pull Request. Feel free to report bugs and issues here.

If you're new to posting issues, we ask that you read How To Ask Questions The Smart Way and How to Ask a Question in Open Source Community and How to Report Bugs Effectively prior to posting. Well written bug reports help us help you!

Need Help? Copy Chapter

For questions on how to use antd, please post questions to GitHub Discussions using the Q&A tag or using the antd tag.

As always, we encourage experienced users to help those who are not familiar with antd!

2. Official Technical Reference & Guides (ant-design/ant-design.github.io) Copy Chapter

✨ Features Copy Chapter

• 🌈 Enterprise-class UI designed for web applications.
• 📦 A set of high-quality React components out of the box.
• 🛡 Written in TypeScript with predictable static types.
• ⚙️ Whole package of design resources and development tools.
• 🌍 Internationalization support for dozens of languages.
• 🎨 Powerful theme customization based on CSS-in-JS.

🖥 Environment Support Copy Chapter

• Modern browsers
• Server-side Rendering
• Electron

📦 Install Copy Chapter

npm install antd

yarn add antd

pnpm add antd

bun add antd

🔨 Usage Copy Chapter

import { Button, DatePicker } from 'antd';

export default () => (
  <>
    PRESS ME
    <DatePicker placeholder="select date" />
  </>
);

🔗 Links Copy Chapter

• Home page
• Components Overview
• Sponsor
• Change Log
• rc-components
• 🆕 Ant Design X
• Ant Design Pro
• Pro Components
• Ant Design Mobile
• Ant Design Mini
• Ant Design Charts
• Ant Design Web3
• Landing Pages
• Ant Motion
• Scaffold Market
• Developer Instruction
• Versioning Release Note
• FAQ
• Online Playground for bug reports
• Customize Theme
• How to Apply for Being A Collaborator

⌨️ Development Copy Chapter

Use opensumi.run, a free online pure front-end dev environment.

Or clone locally:

$ git clone [email protected]:ant-design/ant-design.git
$ cd ant-design
$ npm install
$ npm start

Open your browser and visit http://127.0.0.1:8001, see more at Development.

🤝 Contributing [](https://makeapullrequest.com) Copy Chapter

Let's build a better antd together.

We warmly invite contributions from everyone. Before you get started, please take a moment to review our Contribution Guide. Feel free to share your ideas through Pull Requests or GitHub Issues. If you're interested in enhancing our codebase, explore the Development Instructions and enjoy your coding journey! :)

For collaborators, adhere to our Pull Request Principle and utilize our Pull Request Template when creating a Pull Request.

Issue funding Copy Chapter

We use Issuehunt to up-vote and promote specific features that you would like to see and implement. Check our backlog and help us:

❤️ Backers [](https://opencollective.com/ant-design#support) Copy Chapter