logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.1.7
  • Ant Design of React
  • Getting Started
  • Real project with Umi
  • Use in create-react-app
  • Use in TypeScript
  • CSS Compatible
  • Customize Theme
  • Use custom date library
  • V4 to V5
  • Third-Party Libraries
  • Internationalization
  • FAQ
  • Contributing
  • Change Log
Customize theme with ConfigProvider
Customize Design Token
Use Preset Algorithms
Customize Component Token
Other Ways to Use Dynamic Themes
Switch Themes Dynamically
Local Theme
Consume Design Token
Static consume (e.g. less)
Advanced
Life Cycle of Design Token
Seed Token
Map Token
Alias Token
Algorithm
Legacy Browser Compatible
Server Side Render (SSR)
Shadow DOM Usage
API
Theme
OverrideToken
SeedToken
MapToken
AliasToken
StyleProvider
How to Debug your Theme
Theme Presets
FAQ
Why component re-mounted when theme changed from undefined to some object or to undefined?

Customize Theme

CSS CompatibleUse custom date library

Resources

Ant Design Charts
Ant Design Pro
Ant Design Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
ahooks-React Hooks Library
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuqueAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconfSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTechMore Products

yuqueYuQue-Document Collaboration Platform
AntVAntV-Data Visualization
EggEgg-Enterprise Node.js Framework
kitchenKitchen-Sketch Toolkit
xtechAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community

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.

In version 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 component;
  4. ...

Customize theme with ConfigProvider

In version 5.0 we call the smallest element that affects the theme Design Token. By modifying the Design Token, we can present various themes or components.

Customize Design Token

You can pass theme to ConfigProvider to customize theme. After migrate to V5, theme of V5 will be applied by default. Here's a simple example:

import { Button, ConfigProvider } from 'antd';
import React from 'react';
const App: React.FC = () => (
<ConfigProvider
theme={{
token: {
colorPrimary: '#00b96b',
},
}}
>
<Button />
</ConfigProvider>
);
export default App;

You will get a theme with primary color #00b96b. And we can see the change in Button:

themed button

Use Preset Algorithms

Themes with different styles can be quickly generated by modifying algorithm. Ant Design 5.0 provides three sets of preset algorithms by default, which are default algorithm theme.defaultAlgorithm, dark algorithm theme.darkAlgorithm and compact algorithm theme.compactAlgorithm. You can switch algorithms by modifying the algorithm property of theme in ConfigProvider.

import { Button, ConfigProvider, theme } from 'antd';
import React from 'react';
const App: React.FC = () => (
<ConfigProvider
theme={{
algorithm: theme.darkAlgorithm,
}}
>
<Button />
</ConfigProvider>
);
export default App;

Customize Component Token

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.

import { Checkbox, ConfigProvider, Radio } from 'antd';
import React from 'react';
const App: React.FC = () => (
<ConfigProvider
theme={{
components: {
Radio: {
colorPrimary: '#00b96b',
},
},
}}
>
<Radio>Radio</Radio>
<Checkbox>Checkbox</Checkbox>
</ConfigProvider>
);
export default App;

In this way, we changed the primary color of Radio to #00b96b, and Checkbox is not affected.

component token

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

Other Ways to Use Dynamic Themes

Switch Themes Dynamically

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.

Local Theme

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.

import { Button, ConfigProvider } from 'antd';
import React from 'react';
const App: React.FC = () => (
<ConfigProvider
theme={{
token: {
colorPrimary: '#1677ff',
},
}}
>
<Button />
<ConfigProvider
theme={{
token: {
colorPrimary: '#1890ff',
},
}}
>
<Button />
</ConfigProvider>
</ConfigProvider>
);
export default App;

Consume Design Token

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

import { Button, theme } from 'antd';
import React from 'react';
const { useToken } = theme;
const App: React.FC = () => {
const { token } = useToken();
return <Button style={{ backgroundColor: token.colorPrimary }}>Button</Button>;
};
export default App;

Static consume (e.g. less)

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

import { theme } from 'antd';
const { defaultAlgorithm, defaultSeed } = theme;
const mapToken = defaultAlgorithm(defaultSeed);

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.

Advanced

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 Cycle of Design Token

token

Seed Token

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

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

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

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],
};

Legacy Browser Compatible

Please ref to CSS Compatible.

Server Side Render (SSR)

Use @ant-design/cssinjs to extract style:

import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import { renderToString } from 'react-dom/server';
export default () => {
// SSR Render
const cache = createCache();
const html = renderToString(
<StyleProvider cache={cache}>
<MyApp />
</StyleProvider>,
);
// Grab style from cache
const styleText = extractStyle(cache);
// Mix with style
return `
<!DOCTYPE html>
<html>
<head>
${styleText}
</head>
<body>
<div id="root">${html}</div>
</body>
</html>
`;
};

Shadow DOM Usage

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>,
);

API

Theme

PropertyDescriptionTypeDefault
tokenModify Design TokenAliasToken-
inheritInherit theme configured in upper ConfigProviderbooleantrue
algorithmModify the algorithms of theme(token: SeedToken) => MapToken | ((token: SeedToken) => MapToken)[]defaultAlgorithm
componentsModify Component Token and Alias Token applied to componentsOverrideToken-

OverrideToken

PropertyDescriptionTypeDefault
Component (Can be any antd Component name like Button)Modify Component Token or override Component used Alias TokenComponentToken & AliasToken-

SeedToken

Token NameDescriptionTypeDefault Value
borderRadiusBorder radius of base componentsnumber6
colorBgBaseUsed to derive the base variable of the background color gradient. In v5, we added a layer of background color derivation algorithm to produce map token of background color. But PLEASE DO NOT USE this Seed Token directly in the code!string#fff
colorErrorUsed to represent the visual elements of the operation failure, such as the error Button, error Result component, etc.string#ff4d4f
colorInfoUsed to represent the operation information of the Token sequence, such as Alert, Tag, Progress, and other components use these map tokens.string#1677ff
colorPrimaryBrand color is one of the most direct visual elements to reflect the characteristics and communication of the product. After you have selected the brand color, we will automatically generate a complete color palette and assign it effective design semantics.string#1677ff
colorSuccessUsed to represent the token sequence of operation success, such as Result, Progress and other components will use these map tokens.string#52c41a
colorTextBaseUsed to derive the base variable of the text color gradient. In v5, we added a layer of text color derivation algorithm to produce gradient variables of text color gradient. But please do not use this Seed Token directly in the code!string#000
colorWarningUsed to represent the warning map token, such as Notification, Alert, etc. Alert or Control component(like Input) will use these map tokens.string#faad14
controlHeightThe height of the basic controls such as buttons and input boxes in Ant Designnumber32
fontFamilystring-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'
fontSizenumber14
lineTypeBorder style of base componentsstringsolid
lineWidthBorder width of base componentsnumber1
motionBasenumber0
motionEaseInBackstringcubic-bezier(0.71, -0.46, 0.88, 0.6)
motionEaseInOutstringcubic-bezier(0.645, 0.045, 0.355, 1)
motionEaseInOutCircstringcubic-bezier(0.78, 0.14, 0.15, 0.86)
motionEaseInQuintstringcubic-bezier(0.755, 0.05, 0.855, 0.06)
motionEaseOutstringcubic-bezier(0.215, 0.61, 0.355, 1)
motionEaseOutBackstringcubic-bezier(0.12, 0.4, 0.29, 1.46)
motionEaseOutCircstringcubic-bezier(0.08, 0.82, 0.17, 1)
motionEaseOutQuintstringcubic-bezier(0.23, 1, 0.32, 1)
motionUnitThe unit of animation duration changenumber0.1
opacityImagenumber1
sizePopupArrownumber16
sizeStepThe base step of size change, the size step combined with the size change unit, can derive various size steps. By adjusting the step, you can get different layout modes, such as the size step of the compact mode of V5 is 2number4
sizeUnitThe unit of size change, in Ant Design, our base unit is 4, which is more fine-grained control of the size stepnumber4
wireframebooleanfalse
zIndexBaseThe base Z axis value of all components, which can be used to control the level of some floating components based on the Z axis value, such as BackTop, Affix, etc.number0
zIndexPopupBaseBase zIndex of component like FloatButton, Affix which can be cover by large popupnumber1000

MapToken

Inherit all SeedToken properties

Token NameDescriptionTypeDefault Value
borderRadiusLGLG size border radius, used in some large border radius components, such as Card, Modal and other components.number8
borderRadiusOuternumber4
borderRadiusSMSM size border radius, used in small size components, such as Button, Input, Select and other input components in small sizenumber4
borderRadiusXSXS size border radius, used in some small border radius components, such as Segmented, Arrow and other components.number2
colorBgContainerstring#ffffff
colorBgElevatedstring#ffffff
colorBgLayoutstring#f5f5f5
colorBgMaskThe background color of the mask, used to cover the content below the mask, Modal, Drawer and other components use this tokenstringrgba(0, 0, 0, 0.45)
colorBgSpotlightstringrgba(0, 0, 0, 0.85)
colorBorderDefault border color, used to separate different elements, such as: form separator, card separator, etc.string#d9d9d9
colorBorderSecondarySlightly lighter than the default border color, this color is the same as `colorSplit`. Solid color is used.string#f0f0f0
colorErrorActivestring#d9363e
colorErrorBgstring#fff2f0
colorErrorBgHoverstring#fff1f0
colorErrorBorderstring#ffccc7
colorErrorBorderHoverstring#ffa39e
colorErrorHoverstring#ff7875
colorErrorTextstring#ff4d4f
colorErrorTextActivestring#d9363e
colorErrorTextHoverstring#ff7875
colorFillstringrgba(0, 0, 0, 0.15)
colorFillQuaternarystringrgba(0, 0, 0, 0.02)
colorFillSecondarystringrgba(0, 0, 0, 0.06)
colorFillTertiarystringrgba(0, 0, 0, 0.04)
colorInfoActivestring#0958d9
colorInfoBgstring#e6f4ff
colorInfoBgHoverstring#bae0ff
colorInfoBorderstring#91caff
colorInfoBorderHoverstring#69b1ff
colorInfoHoverstring#69b1ff
colorInfoTextstring#1677ff
colorInfoTextActivestring#0958d9
colorInfoTextHoverstring#4096ff
colorPrimaryActivestring#0958d9
colorPrimaryBgLight background color of primary color, usually used for weak visual level selection state.string#e6f4ff
colorPrimaryBgHoverstring#bae0ff
colorPrimaryBorderstring#91caff
colorPrimaryBorderHoverstring#69b1ff
colorPrimaryHoverstring#4096ff
colorPrimaryTextstring#1677ff
colorPrimaryTextActivestring#0958d9
colorPrimaryTextHoverstring#4096ff
colorSuccessActivestring#389e0d
colorSuccessBgLight background color of success color, used for Tag and Alert success state background colorstring#f6ffed
colorSuccessBgHoverLight background color of success color, but antd does not use this token currentlystring#d9f7be
colorSuccessBorderstring#b7eb8f
colorSuccessBorderHoverstring#95de64
colorSuccessHoverstring#95de64
colorSuccessTextstring#52c41a
colorSuccessTextActivestring#389e0d
colorSuccessTextHoverstring#73d13d
colorTextstringrgba(0, 0, 0, 0.88)
colorTextQuaternarystringrgba(0, 0, 0, 0.25)
colorTextSecondarystringrgba(0, 0, 0, 0.65)
colorTextTertiarystringrgba(0, 0, 0, 0.45)
colorWarningActivestring#d48806
colorWarningBgstring#fffbe6
colorWarningBgHoverstring#fff1b8
colorWarningBorderstring#ffe58f
colorWarningBorderHoverstring#ffd666
colorWarningHoverstring#ffd666
colorWarningTextstring#faad14
colorWarningTextActivestring#d48806
colorWarningTextHoverstring#ffc53d
colorWhitePure white color don't changed by themestring#fff
controlHeightLGnumber40
controlHeightSMnumber24
controlHeightXSnumber16
fontSizeHeading1number38
fontSizeHeading2number30
fontSizeHeading3number24
fontSizeHeading4number20
fontSizeHeading5number16
fontSizeLGnumber16
fontSizeSMnumber12
fontSizeXLnumber20
lineHeightnumber1.5714285714285714
lineHeightHeading1number1.2105263157894737
lineHeightHeading2number1.2666666666666666
lineHeightHeading3number1.3333333333333333
lineHeightHeading4number1.4
lineHeightHeading5number1.5
lineHeightLGnumber1.5
lineHeightSMnumber1.6666666666666667
lineWidthBoldThe default line width of the outline class components, such as Button, Input, Select, etc.number2
motionDurationFaststring0.1s
motionDurationMidstring0.2s
motionDurationSlowstring0.3s
sizenumber16
sizeLGnumber24
sizeMDnumber20
sizeMSnumber16
sizeSMnumber12
sizeXLnumber32
sizeXSnumber8
sizeXXLnumber48
sizeXXSnumber4

AliasToken

Inherit all SeedToken and MapToken properties

Token NameDescriptionTypeDefault Value
boxShadowstring 0 1px 2px 0 rgba(0, 0, 0, 0.03), 0 1px 6px -1px rgba(0, 0, 0, 0.02), 0 2px 4px 0 rgba(0, 0, 0, 0.02)
boxShadowSecondarystring 0 6px 16px 0 rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 9px 28px 8px rgba(0, 0, 0, 0.05)
colorBgContainerDisabledstringrgba(0, 0, 0, 0.04)
colorBgTextActivestringrgba(0, 0, 0, 0.15)
colorBgTextHoverstringrgba(0, 0, 0, 0.06)
colorBorderBgstring#ffffff
colorErrorOutlinestringrgba(255, 38, 5, 0.06)
colorFillAlterstringrgba(0, 0, 0, 0.02)
colorFillContentstringrgba(0, 0, 0, 0.06)
colorFillContentHoverstringrgba(0, 0, 0, 0.15)
colorHighlightstring#ff4d4f
colorIconstringrgba(0, 0, 0, 0.45)
colorIconHoverstringrgba(0, 0, 0, 0.88)
colorLinkstring#1677ff
colorLinkActivestring#0958d9
colorLinkHoverstring#69b1ff
colorSplitstringrgba(5, 5, 5, 0.06)
colorTextDescriptionstringrgba(0, 0, 0, 0.45)
colorTextDisabledstringrgba(0, 0, 0, 0.25)
colorTextHeadingstringrgba(0, 0, 0, 0.88)
colorTextLabelstringrgba(0, 0, 0, 0.65)
colorTextLightSolidstring#fff
colorTextPlaceholderstringrgba(0, 0, 0, 0.25)
colorWarningOutlinestringrgba(255, 215, 5, 0.1)
controlInteractiveSizenumber16
controlItemBgActivestring#e6f4ff
controlItemBgActiveDisabledstringrgba(0, 0, 0, 0.15)
controlItemBgActiveHoverstring#bae0ff
controlItemBgHoverstringrgba(0, 0, 0, 0.04)
controlOutlinestringrgba(5, 145, 255, 0.1)
controlOutlineWidthnumber2
controlPaddingHorizontalnumber12
controlPaddingHorizontalSMnumber8
controlTmpOutlinestringrgba(0, 0, 0, 0.02)
fontSizeIconnumber12
fontWeightStrongnumber600
linkDecorationundefined | TextDecoration<string | number>none
linkFocusDecorationundefined | TextDecoration<string | number>none
linkHoverDecorationundefined | TextDecoration<string | number>none
marginnumber16
marginLGnumber24
marginMDnumber20
marginSMnumber12
marginXLnumber32
marginXSnumber8
marginXXLnumber48
marginXXSnumber4
opacityLoadingnumber0.65
paddingnumber16
paddingContentHorizontalnumber16
paddingContentHorizontalLGnumber24
paddingContentHorizontalSMnumber16
paddingContentVerticalnumber12
paddingContentVerticalLGnumber16
paddingContentVerticalSMnumber8
paddingLGnumber24
paddingMDnumber20
paddingSMnumber12
paddingXLnumber32
paddingXSnumber8
paddingXXSnumber4
screenLGnumber992
screenLGMaxnumber1199
screenLGMinnumber992
screenMDnumber768
screenMDMaxnumber991
screenMDMinnumber768
screenSMnumber576
screenSMMaxnumber767
screenSMMinnumber576
screenXLnumber1200
screenXLMaxnumber1599
screenXLMinnumber1200
screenXSnumber480
screenXSMaxnumber575
screenXSMinnumber480
screenXXLnumber1600
screenXXLMinnumber1600

StyleProvider

Please ref @ant-design/cssinjs.

How to Debug your Theme

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.

Theme Presets

  • Ant Design 4.x

FAQ

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

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