Ant Design Theme Customization: From Less Variables to CSS‑in‑JS and Performance Strategies

Background

The author’s team is upgrading to Ant Design 5.0, which requires theme customization to align with a newly revised UE specification, prompting a need for systematic Antd component theming.

Current Situation

High‑frequency components have been identified and styled via design tokens to meet team standards for colors, border‑radius, fonts, etc. However, some components (e.g., button, select) cannot be fully customized through tokens alone, necessitating style overrides.

Goals

Identify components that need style overrides and the specific override points.

Research a high‑performance, highly extensible, and compatible style‑override solution.

Ant Design Theme Customization Evolution

Antd 4.x Era

Simple Overview

Antd 4.x used Less for styling, exposing a set of global and component variables that could be overridden via @primary-color , @font-size-base , etc.

@primary-color: #1890ff; // global primary color
@link-color: #1890ff; // link color
@success-color: #52c41a; // success color
@warning-color: #faad14; // warning color
@error-color: #f5222d; // error color
@font-size-base: 14px; // base font size

Overrides were typically applied using Less's modifyVars in a Webpack configuration:

// webpack.config.js
module.exports = {
  rules: [{
    test: /\.less$/,
    use: [{ loader: 'style-loader' }, { loader: 'css-loader' }, { loader: 'less-loader', options: { lessOptions: { modifyVars: { 'primary-color': '#1DA57A', 'link-color': '#1DA57A', 'border-radius-base': '2px' }, javascriptEnabled: true } } }]
  }]
}

What Are CSS Variables?

CSS variables (custom properties) were standardized by W3C in 2012 and are now supported by all major browsers. They allow style values to be defined once and referenced elsewhere, and can be manipulated via JavaScript, making them ideal for theming.

Key advantages for theming include compile‑time resolution (no runtime cost) and seamless theme switching without page flicker.

Theme switches do not cause jank.

Theme changes can refresh instantly without a full reload.

These benefits are not achievable with runtime‑based CSS‑in‑JS solutions, which must re‑serialize styles on each switch.

Limitations of CSS‑Variable‑Based Antd Theming

Insufficient flexibility – cannot easily support nested themes or multiple simultaneous themes.

For example, dark‑mode Modal backgrounds may clash with the page Layout background, requiring manual overrides that the default CSS‑variable system cannot address.

Antd 5.x Era

Simple Overview

On 2022‑11‑18 Ant Design 5.0 was released, replacing the Less approach with a CSS‑in‑JS solution built on a Design Token model, enabling nested and multiple themes.

❝ Key point: Theme configuration moved from compile‑time to runtime code. ❞

What Is CSS‑in‑JS?

CSS‑in‑JS writes CSS inside JavaScript files, allowing variables, conditionals, and functions to influence styles. Popular libraries include styled‑components and Emotion.

The core characteristic is runtime execution – styles are interpreted and injected when the application runs.

Advantages and Drawbacks of CSS‑in‑JS

Advantages:

No global style conflicts thanks to module‑scoped styles.

Built‑in tree‑shaking removes unused style modules.

Styles are co‑located with components, simplifying maintenance.

High flexibility via JavaScript variables.

Drawbacks:

Runtime overhead: each render must serialize styles into CSS, increasing CPU usage, especially problematic under React 18 concurrent mode.

Increased bundle size (e.g., Emotion ~7.9 KB gzipped, styled‑components ~12.7 KB).

Potential version conflicts when multiple CSS‑in‑JS libraries are loaded.

SSR implementations vary across React versions.

Root Causes of CSS‑in‑JS Performance Issues

Each CSS block receives a hash generated from its full content; during re‑renders the hash must be recomputed, causing extra work. When styles depend on component props, the cost becomes noticeable.

Frequent component re‑renders.

Dynamic styles that change with props.

How Antd Addresses the Problem

Antd adopts two strategies:

Component styles are static – a component’s full style is inserted once regardless of prop changes.

Style caching – identical component‑token pairs share a cached hash, preventing repeated serialization.

Benchmark

A benchmark comparing styled‑components, Emotion, and Ant Design’s own solution shows Antd’s component‑level approach outperforms others on both first and second renders for stable styles.

Style‑Override Options

Antd does not restrict how applications override its styles; options include Less, Sass, styled‑components, Tailwind, Emotion, etc.

Two major categories exist: CSS‑module (compile‑time) and CSS‑in‑JS (runtime). Global overrides are discouraged due to maintainability concerns.

Official Solution – antd‑style

Background

Antd’s own CSS‑in‑JS implementation provides high performance but can be verbose for application‑level usage. The antd‑style library offers a business‑level CSS‑in‑JS solution built on Ant Design V5 tokens.

What Is antd‑style?

antd‑style is a token‑aware CSS‑in‑JS library designed for business applications and libraries that wrap Ant Design components, delivering performance, extensibility, and SSR compatibility.

Installation

yarn add antd-style
# or
npm install antd-style

Usage Example

import React from 'react';
import { ConfigProvider } from 'antd';
import { createStyles } from 'antd-style';

const useButtonStyle = () => {
  const { getPrefixCls } = React.useContext(ConfigProvider.ConfigContext);
  const btnPrefixCls = getPrefixCls('btn');

  return createStyles(({ css, token }) => ({
    btn: css`
      background: red;
      .${btnPrefixCls}-icon { color: green; };
      background: ${token.colorPrimary};
    `,
  }))();
};

function GeekProvider(props: { children?: React.ReactNode }) {
  const { styles } = useButtonStyle();
  return
{props.children}
;
}

More usage details are available in the official documentation.

Does It Meet the Goals?

High Performance ✅ – Benchmarks show antd‑style outperforms styled‑components and Emotion.

High Extensibility ✅ – Being a CSS‑in‑JS solution, it supports custom tokens and composable styles.

Strong Compatibility ✅ – Supports SSR and upcoming micro‑frontend scenarios.

Common Misconception

antd‑style does not completely eliminate performance concerns; it is still slower than the low‑level @ant-design/cssinjs library when props‑driven dynamic styles are required.

Conclusion

Compared with Less, Sass, styled‑components, or Emotion, antd‑style provides a balanced solution for Ant Design‑based component libraries, offering superior performance, extensibility, and compatibility, though it remains under active development and may have a learning curve.