Switch Ant Design v5 themes at runtime with ConfigProvider and design tokens

The problem: static themes force a rebuild

In Ant Design v4, changing a brand color or enabling dark mode usually meant editing Less variables and rebuilding the CSS bundle. If your React app needs a light/dark toggle or a primary color that can change without redeploying, that workflow is slow and impractical.

Ant Design v5 replaces Less variable theming with a token-based system exposed through ConfigProvider. Component styles derive from JavaScript tokens at runtime, so you can change colors without rebuilding stylesheets.

How ConfigProvider and design tokens work

ConfigProvider is a context component that supplies theme values to Ant Design components below it. The theme prop accepts an object that can contain a preset algorithm, a token object, or both. For example, { token: { colorPrimary: '#1890ff' } } changes the primary color, while { algorithm: theme.darkAlgorithm } switches the entire palette to dark surfaces.

An algorithm is a function that generates a full set of derived tokens from your base tokens. The default algorithm produces light surfaces; the dark algorithm produces dark surfaces and adjusts border and text colors accordingly. When you supply both an algorithm and a token override, Ant Design runs the algorithm first and then applies your explicit token values on top.

Design tokens are the named values Ant Design uses to generate component CSS. Changing colorPrimary updates primary buttons, links, and form states together because those components read the same token rather than hard-coded colors. The useTheme hook lets a child component read the active token context and style custom UI to match, which is useful when you wrap Ant Design components and need your own CSS variables to stay in sync.

Worked example: a light/dark toggle

This example wraps the application in ConfigProvider and switches between the default light algorithm and the dark algorithm when a user clicks a toggle. It is a configuration pattern, not a tested build, so verify the output in your own project.

import { ConfigProvider, Button, Switch, Space, theme } from 'antd';
import { useState } from 'react';

export default function ThemeToggleDemo() {
  const [dark, setDark] = useState(false);

  return (
    <ConfigProvider
      theme={{
        algorithm: dark ? theme.darkAlgorithm : theme.defaultAlgorithm,
        token: { colorPrimary: '#1890ff' },
      }}
    >
      <Space direction="vertical" align="start" style={{ padding: 24 }}>
        <Switch checked={dark} onChange={setDark} />
        <Button type="primary">Primary button</Button>
      </Space>
    </ConfigProvider>
  );
}

Where to run: in your React project root, after installing antd@5. Required permissions: none beyond normal file edits. Placeholders: replace '#1890ff' with your brand color. Expected checks: open browser dev tools, inspect the primary button, and confirm its background matches the active token. Switching the toggle should change surfaces without a page reload. Risks: mounting ConfigProvider after the first render can cause a flash of unstyled content, so wrap the app as early as possible.

Scoping themes to part of a page

You can nest ConfigProvider instances. An inner provider overrides the theme for its subtree while the rest of the app keeps the outer theme. This is useful when a single dashboard panel needs a dark surface inside a light application.

Because tokens are inherited through React context, the inner provider only needs to declare the values it changes. It does not need to repeat the full token set, which keeps the configuration small and reduces the chance of accidental overrides.

Limitations and what to check

• Runtime theme changes can produce a brief flash of unstyled content if ConfigProvider is mounted after initial render.
• Overriding too many tokens can break visual consistency or accessibility contrast; test custom colors against WCAG contrast ratios.
• Migration from Ant Design v4 Less variables to v5 tokens is not drop-in compatible; existing Less theme overrides must be rewritten.

Practical check: render a primary button and a text input under your ConfigProvider, open browser dev tools, and confirm the computed styles reflect the injected token-based CSS rather than a static Less build. If colors do not update when the theme prop changes, check that ConfigProvider actually wraps the components and that no outer provider is shadowing it.

Closing

Ant Design v5 makes runtime theming practical by treating colors as tokens instead of build-time Less variables. Wrap your app in ConfigProvider early, combine an algorithm with a token override, and verify with dev tools before shipping a toggle to users.