---
group:
  title: Advanced
  order: 1
order: 0
title: 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.

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

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](/components/app) to simplify the problem of usingModal and other methods that need to manually implant the contextHolder.
:::

### Customize Design Token

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

You can modify some theme variables through the `token` property in `theme`. Some theme variables will cause changes to other theme variables, which we call Seed Tokens.

```tsx
import React from 'react';
import { Button, ConfigProvider, Space } from 'antd';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      token: {
        // Seed Token, affects wide range
        colorPrimary: '#00b96b',
        borderRadius: 2,

        // Derived token, affects narrow range
        colorBgContainer: '#f6ffed',
      },
    }}
  >
    <Space>
      <Button type="primary">Primary</Button>
      <Button>Default</Button>
    </Space>
  </ConfigProvider>
);

export default App;
```


### Use Preset Algorithms

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

You can quickly generate distinct themes by modifying algorithms. We provide three preset algorithms by default: `theme.defaultAlgorithm`, `theme.darkAlgorithm`, and `theme.compactAlgorithm`. You can switch algorithms through the `algorithm` property in `theme`, and multiple algorithms can be configured, which will take effect in order.

```tsx
import React from 'react';
import { Button, ConfigProvider, Input, Space, theme } from 'antd';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      // 1. Use dark algorithm alone
      algorithm: theme.darkAlgorithm,

      // 2. Combine dark algorithm and compact algorithm
      // algorithm: [theme.darkAlgorithm, theme.compactAlgorithm],
    }}
  >
    <Space>
      <Input placeholder="Please Input" />
      <Button type="primary">Submit</Button>
    </Space>
  </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.

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

In addition to the overall Design Token, each component also exposes its own Component Token to enable component-specific style customization capabilities, without mutual influence between different components. Similarly, you can also override other Design Tokens consumed by the component through this method. In version `>= 5.8.0`, the component token supports passing the `algorithm` property to enable derivative calculation or pass in other algorithms.

```tsx
import React from 'react';
import { Button, ConfigProvider, Divider, Input, Space } from 'antd';

const App: React.FC = () => (
  <>
    <ConfigProvider
      theme={{
        components: {
          Button: {
            colorPrimary: '#00b96b',
            algorithm: true, // Enable algorithm
          },
          Input: {
            colorPrimary: '#eb2f96',
            algorithm: true, // Enable algorithm
          },
        },
      }}
    >
      <Space>
        <div style={{ fontSize: 14 }}>Algorithm Enabled:</div>
        <Input placeholder="Please Input" />
        <Button type="primary">Submit</Button>
      </Space>
    </ConfigProvider>
    <Divider />
    <ConfigProvider
      theme={{
        components: {
          Button: {
            colorPrimary: '#00b96b',
          },
          Input: {
            colorPrimary: '#eb2f96',
          },
        },
      }}
    >
      <Space>
        <div style={{ fontSize: 14 }}>Algorithm Disabled:</div>
        <Input placeholder="Please Input" />
        <Button type="primary">Submit</Button>
      </Space>
    </ConfigProvider>
  </>
);

export default App;
```


### Disable Motion

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

Ant Design includes some built-in component interaction animations to make enterprise pages more detailed. In some extreme scenarios, this may affect page interaction performance. If you need to turn off animations, you can set `motion` in `token` to `false`.

```tsx
import React, { useEffect, useRef, useState } from 'react';
import { Checkbox, Col, ConfigProvider, Flex, Radio, Row, Switch } from 'antd';

const App: React.FC = () => {
  const [checked, setChecked] = useState<boolean>(false);
  const timerRef = useRef<ReturnType<typeof setInterval>>(null);

  useEffect(() => {
    timerRef.current = setInterval(() => {
      setChecked((prev) => !prev);
    }, 500);
    return () => {
      if (timerRef.current) {
        clearInterval(timerRef.current);
      }
    };
  }, []);

  const nodes = (
    <Flex gap="small">
      <Checkbox checked={checked}>Checkbox</Checkbox>
      <Radio checked={checked}>Radio</Radio>
      <Switch checked={checked} />
    </Flex>
  );

  return (
    <Row gutter={[24, 24]}>
      <Col span={24}>{nodes}</Col>
      <Col span={24}>
        <ConfigProvider theme={{ token: { motion: false } }}>{nodes}</ConfigProvider>
      </Col>
    </Row>
  );
};

export default App;
```


## Advanced

### Zero Runtime {#zero-runtime}

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.

```tsx
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](https://github.com/ant-design/static-style-extract) to generate static styles.

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

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

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

```tsx
import React, { useState } from 'react';
import { Button, ColorPicker, ConfigProvider, Divider, Input, Space } from 'antd';

const App: React.FC = () => {
  const [primary, setPrimary] = useState('#1677ff');

  return (
    <>
      <ColorPicker showText value={primary} onChange={(color) => setPrimary(color.toHexString())} />
      <Divider />
      <ConfigProvider
        theme={{
          token: {
            colorPrimary: primary,
          },
        }}
      >
        <Space>
          <Input placeholder="Please Input" />
          <Button type="primary">Submit</Button>
        </Space>
      </ConfigProvider>
    </>
  );
};

export default App;
```


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

### Nested Theme

You can nest `ConfigProvider` to achieve local theme changes. Design Tokens that have not been changed in the sub-theme will inherit from the parent theme.

```tsx
import React from 'react';
import { Button, ConfigProvider, Space } from 'antd';

const App: React.FC = () => (
  <ConfigProvider
    theme={{
      token: {
        colorPrimary: '#1677ff',
      },
    }}
  >
    <Space>
      <Button type="primary">Theme 1</Button>
      <ConfigProvider
        theme={{
          token: {
            colorPrimary: '#00b96b',
          },
        }}
      >
        <Button type="primary">Theme 2</Button>
      </ConfigProvider>
    </Space>
  </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.

### Consume Design Token

If you want to use the Design Token of the current theme, we provide a `useToken` hook to get it.

```tsx
import React from 'react';
import { theme } from 'antd';

const { useToken } = theme;

const App: React.FC = () => {
  const { token } = useToken();

  return (
    <div
      style={{
        backgroundColor: token.colorPrimaryBg,
        padding: token.padding,
        borderRadius: token.borderRadius,
        color: token.colorPrimaryText,
        fontSize: token.fontSize,
      }}
    >
      Use Design Token
    </div>
  );
};

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:

```jsx
import { theme } from 'antd';

const { getDesignToken } = theme;

const globalToken = getDesignToken();
```

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

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

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

Compatible package provide convert function to transform to v4 less variable. Read [this](/docs/react/migration-v5) for detail.

### Theme editor

We provide tools to help users debug themes: [Theme Editor](/theme-editor)

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

## Design Token

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

![token](https://gw.alipayobjects.com/mdn/rms_08e378/afts/img/A*uF3kTrY4InUAAAAAAAAAAAAAARQnAQ)

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

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

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

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

```tsx
import { theme } from 'antd';

const { darkAlgorithm, compactAlgorithm } = theme;

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

## API

### Theme

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| 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 | `ComponentsConfig` | - |  |
| cssVar | CSS Variables Configuration | [cssVar](#css-var) | - |  |
| hashed | Style patch on the hash className | boolean | true |  |
| zeroRuntime | Enable zero-runtime mode, which will not generate style at runtime, need to import additional CSS file | boolean | false | 6.0.0 |

### ComponentsConfig

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| `Component` (Can be any antd Component name like `Button`) | Modify Component Token or override Component used Alias Token | `ComponentToken & AliasToken & { algorithm: boolean \| (token: SeedToken) => MapToken` \| `((token: SeedToken) => MapToken)[]}` | - |

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

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| prefix | Prefix of CSS variables, same as `prefixCls` configured on ConfigProvider by default | string | `ant` |  |
| key | Unique key for current theme, filled with `useId` by default | string | `useId` in React 18 |  |

### SeedToken

<TokenTable type="seed"></TokenTable>

### MapToken

> Inherit all SeedToken properties

<TokenTable type="map"></TokenTable>

### AliasToken

> Inherit all SeedToken and MapToken properties

<TokenTable type="alias"></TokenTable>

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