Customize Theme

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:

Switching theme dynamically；
Multiple themes；
Customizing theme variables for some component；
...

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 React from 'react';
import { ConfigProvider, Button } from 'antd';

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 React from 'react';
import { ConfigProvider, Button, theme } from 'antd';

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 React from 'react';
import { ConfigProvider, Radio, Checkbox } from 'antd';

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

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 React from 'react';
import { ConfigProvider, Button } from 'antd';

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 React from 'react';
import { Button, theme } from 'antd';

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

Compatible adjustment

Ant Design default using CSS-in-JS with :where Selector to reduce priority to avoid user additional adjust style cost when updating to v5. If you want to support old browser, you can use @ant-design/cssinjs to adjust this behavior (Please note keep version align with antd):

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

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.

Server Side Render (SSR)

Use @ant-design/cssinjs to extract style:

import React from 'react';
import { renderToString } from 'react-dom/server';
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';

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 React from 'react';
import { createRoot } from 'react-dom/client';
import { StyleProvider } from '@ant-design/cssinjs';

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

Property	Description	Type	Default
token	Modify Design Token	`AliasToken`	-
inherit	Inherit theme configured in upper ConfigProvider	boolean	true
algorithm	Modify the algorithms of theme	`(token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]`	`defaultAlgorithm`
components	Modify Component Token and Alias Token applied to components	OverrideToken	-

OverrideToken

Property	Description	Type	Default
`Component` (可以是任意 antd 组件名，如 `Button`)	用于修改 Component Token 以及覆盖该组件消费的 Alias Token	`ComponentToken & AliasToken`	-

SeedToken

Token Name	Description	Type	Default Value
borderRadius	Border radius of base components	number	6
colorBgBase	Used 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
colorError	Used to represent the visual elements of the operation failure, such as the error Button, error Result component, etc.	string	#ff4d4f
colorInfo	Used to represent the operation information of the Token sequence, such as Alert, Tag, Progress, and other components use these map tokens.	string	#1677ff
colorPrimary	Brand 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
colorSuccess	Used to represent the token sequence of operation success, such as Result, Progress and other components will use these map tokens.	string	#52c41a
colorTextBase	Used 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
colorWarning	Used to represent the warning map token, such as Notification, Alert, etc. Alert or Control component(like Input) will use these map tokens.	string	#faad14
controlHeight	The height of the basic controls such as buttons and input boxes in Ant Design	number	32
fontFamily		string	-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'
fontSize		number	14
lineType	Border style of base components	string	solid
lineWidth	Border width of base components	number	1
motionUnit	The unit of animation duration change	number	0.1
sizeStep	The 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 2	number	4
sizeUnit	The unit of size change, in Ant Design, our base unit is 4, which is more fine-grained control of the size step	number	4
wireframe		boolean	false
zIndexBase	The 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.	number	0
zIndexPopupBase	Base zIndex of component like FloatButton, Affix which can be cover by large popup	number	1000

MapToken

继承所有 SeedToken 的 Property

Token Name	Description	Type	Default Value
borderRadiusLG	LG size border radius, used in some large border radius components, such as Card, Modal and other components.	number	8
borderRadiusSM	SM size border radius, used in small size components, such as Button, Input, Select and other input components in small size	number	4
borderRadiusXS	XS size border radius, used in some small border radius components, such as Segmented, Arrow and other components.	number	2
colorBgContainer		string	#ffffff
colorBgElevated		string	#ffffff
colorBgLayout		string	#f5f5f5
colorBgMask	The background color of the mask, used to cover the content below the mask, Modal, Drawer and other components use this token	string	rgba(0, 0, 0, 0.45)
colorBgSpotlight		string	rgba(0, 0, 0, 0.85)
colorBorder	Default border color, used to separate different elements, such as: form separator, card separator, etc.	string	#d9d9d9
colorBorderSecondary	Slightly lighter than the default border color, this color is the same as `colorSplit`. Solid color is used.	string	#f0f0f0
colorErrorActive		string	#d9363e
colorErrorBg		string	#fff2f0
colorErrorBgHover		string	#fff1f0
colorErrorBorder		string	#ffccc7
colorErrorBorderHover		string	#ffa39e
colorErrorHover		string	#ff7875
colorErrorText		string	#ff4d4f
colorErrorTextActive		string	#d9363e
colorErrorTextHover		string	#ff7875
colorFill		string	rgba(0, 0, 0, 0.15)
colorFillQuaternary		string	rgba(0, 0, 0, 0.02)
colorFillSecondary		string	rgba(0, 0, 0, 0.06)
colorFillTertiary		string	rgba(0, 0, 0, 0.04)
colorInfoActive		string	#0958d9
colorInfoBg		string	#e6f4ff
colorInfoBgHover		string	#bae0ff
colorInfoBorder		string	#91caff
colorInfoBorderHover		string	#69b1ff
colorInfoHover		string	#69b1ff
colorInfoText		string	#1677ff
colorInfoTextActive		string	#0958d9
colorInfoTextHover		string	#4096ff
colorPrimaryActive		string	#0958d9
colorPrimaryBg	Light background color of primary color, usually used for weak visual level selection state.	string	#e6f4ff
colorPrimaryBgHover		string	#bae0ff
colorPrimaryBorder		string	#91caff
colorPrimaryBorderHover		string	#69b1ff
colorPrimaryHover		string	#4096ff
colorPrimaryText		string	#1677ff
colorPrimaryTextActive		string	#0958d9
colorPrimaryTextHover		string	#4096ff
colorSuccessActive		string	#389e0d
colorSuccessBg	Light background color of success color, used for Tag and Alert success state background color	string	#f6ffed
colorSuccessBgHover	Light background color of success color, but antd does not use this token currently	string	#d9f7be
colorSuccessBorder		string	#b7eb8f
colorSuccessBorderHover		string	#95de64
colorSuccessHover		string	#95de64
colorSuccessText		string	#52c41a
colorSuccessTextActive		string	#389e0d
colorSuccessTextHover		string	#73d13d
colorText		string	rgba(0, 0, 0, 0.88)
colorTextQuaternary		string	rgba(0, 0, 0, 0.25)
colorTextSecondary		string	rgba(0, 0, 0, 0.65)
colorTextTertiary		string	rgba(0, 0, 0, 0.45)
colorWarningActive		string	#d48806
colorWarningBg		string	#fffbe6
colorWarningBgHover		string	#fff1b8
colorWarningBorder		string	#ffe58f
colorWarningBorderHover		string	#ffd666
colorWarningHover		string	#ffd666
colorWarningText		string	#faad14
colorWarningTextActive		string	#d48806
colorWarningTextHover		string	#ffc53d
colorWhite	Pure white color don't changed by theme	string	#fff
lineWidthBold	The default line width of the outline class components, such as Button, Input, Select, etc.	number	2
motionDurationFast		string	0.1s
motionDurationMid		string	0.2s
motionDurationSlow		string	0.3s
size		number	16
sizeLG		number	24
sizeMD		number	20
sizeMS		number	16
sizeSM		number	12
sizeXL		number	32
sizeXS		number	8
sizeXXL		number	48
sizeXXS		number	4

AliasToken

继承所有 SeedToken 和 MapToken 的 Property

Token Name	Type	Default Value
boxShadow	string	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)
boxShadowSecondary	string	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)
colorBgContainerDisabled	string	rgba(0, 0, 0, 0.04)
colorBgTextActive	string	rgba(0, 0, 0, 0.15)
colorBgTextHover	string	rgba(0, 0, 0, 0.06)
colorBorderBg	string	#ffffff
colorErrorOutline	string	rgba(255, 38, 5, 0.06)
colorFillAlter	string	rgba(0, 0, 0, 0.02)
colorFillContent	string	rgba(0, 0, 0, 0.06)
colorFillContentHover	string	rgba(0, 0, 0, 0.15)
colorHighlight	string	#ff4d4f
colorIcon	string	rgba(0, 0, 0, 0.45)
colorIconHover	string	rgba(0, 0, 0, 0.88)
colorLink	string	#1677ff
colorLinkActive	string	#0958d9
colorLinkHover	string	#69b1ff
colorSplit	string	rgba(5, 5, 5, 0.06)
colorTextDescription	string	rgba(0, 0, 0, 0.45)
colorTextDisabled	string	rgba(0, 0, 0, 0.25)
colorTextHeading	string	rgba(0, 0, 0, 0.88)
colorTextLabel	string	rgba(0, 0, 0, 0.65)
colorTextLightSolid	string	#fff
colorTextPlaceholder	string	rgba(0, 0, 0, 0.25)
colorWarningOutline	string	rgba(255, 215, 5, 0.1)
controlInteractiveSize	number	16
controlItemBgActive	string	#e6f4ff
controlItemBgActiveDisabled	string	rgba(0, 0, 0, 0.15)
controlItemBgActiveHover	string	#bae0ff
controlItemBgHover	string	rgba(0, 0, 0, 0.04)
controlOutline	string	rgba(5, 145, 255, 0.1)
controlOutlineWidth	number	2
controlPaddingHorizontal	number	12
controlPaddingHorizontalSM	number	8
controlTmpOutline	string	rgba(0, 0, 0, 0.02)
fontSizeHeading1	number	38
fontSizeHeading2	number	30
fontSizeHeading3	number	24
fontSizeHeading4	number	20
fontSizeHeading5	number	16
fontSizeIcon	number	12
fontSizeLG	number	16
fontSizeSM	number	12
fontSizeXL	number	20
fontWeightStrong	number	600
lineHeight	number	1.5714285714285714
lineHeightHeading1	number	1.2105263157894737
lineHeightHeading2	number	1.2666666666666666
lineHeightHeading3	number	1.3333333333333333
lineHeightHeading4	number	1.4
lineHeightHeading5	number	1.5
lineHeightLG	number	1.5
lineHeightSM	number	1.6666666666666667
linkDecoration	undefined \| TextDecoration<string \| number>	none
linkFocusDecoration	undefined \| TextDecoration<string \| number>	none
linkHoverDecoration	undefined \| TextDecoration<string \| number>	none
margin	number	16
marginLG	number	24
marginMD	number	20
marginSM	number	12
marginXL	number	32
marginXS	number	8
marginXXL	number	48
marginXXS	number	4
opacityLoading	number	0.65
padding	number	16
paddingContentHorizontal	number	16
paddingContentHorizontalLG	number	24
paddingContentHorizontalSM	number	16
paddingContentVertical	number	12
paddingContentVerticalLG	number	16
paddingContentVerticalSM	number	8
paddingLG	number	24
paddingMD	number	20
paddingSM	number	12
paddingXL	number	32
paddingXS	number	8
paddingXXS	number	4
screenLG	number	992
screenLGMax	number	1199
screenLGMin	number	992
screenMD	number	768
screenMDMax	number	991
screenMDMin	number	768
screenSM	number	576
screenSMMax	number	767
screenSMMin	number	576
screenXL	number	1200
screenXLMax	number	1599
screenXLMin	number	1200
screenXS	number	480
screenXSMax	number	575
screenXSMin	number	480
screenXXL	number	1600
screenXXLMin	number	1600

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

Customize Theme

Customize Theme

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

Compatible adjustment

Server Side Render (SSR)

Shadow DOM Usage

API

Theme

OverrideToken

SeedToken

MapToken

AliasToken

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

Compatible adjustment

Server Side Render (SSR)

Shadow DOM Usage

API

Theme

OverrideToken

SeedToken

MapToken

AliasToken

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 with `ConfigProvider`

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

Customize theme with `ConfigProvider`

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