How to Implement Dark Mode in Ant Design: A Complete Guide Using Design Tokens

Wrap your application with Ant Design's ConfigProvider and set the theme.algorithm to theme.darkAlgorithm to instantly switch your entire UI to dark mode.

When you implement dark mode in Ant Design applications, you leverage the framework's built-in design token system rather than writing custom CSS overrides. The ant-design/ant-design repository provides a robust theming engine that generates dark-mode color palettes algorithmically, ensuring consistent contrast and accessibility across all components.

Understanding Ant Design's Dark Mode Architecture

Ant Design's theming engine relies on design tokens—configurable variables that control colors, spacing, shadows, and typography. The dark mode implementation resides in components/theme/themes/dark/index.ts, where the darkAlgorithm generates a complete set of dark-themed tokens by invoking @ant-design/colors with the { theme: 'dark' } configuration. This algorithm automatically calculates background colors, text colors, and border values optimized for low-light environments.

Enabling Dark Mode with ConfigProvider

The ConfigProvider component serves as the distribution mechanism for theme tokens throughout your application. Located in components/config-provider/index.tsx, it accepts a theme prop that accepts an algorithm field. When you provide theme.darkAlgorithm, the provider resolves the token set via the internal useTheme hook and creates a DesignTokenContext that descendant components consume to render dark styles.

To implement basic dark mode, wrap your root component:

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

const App = () => (
  <ConfigProvider
    theme={{
      algorithm: theme.darkAlgorithm,
    }}
  >
    <Input placeholder="Enter something…" />
    <Button type="primary">Submit</Button>
  </ConfigProvider>
);

export default App;

Combining Algorithms and Customizing Tokens

Ant Design allows you to compose multiple algorithms to achieve specific visual effects. For example, combining darkAlgorithm with compactAlgorithm produces a dense, dark interface ideal for data-heavy applications. You can also override specific design tokens while retaining the dark palette.

The following example demonstrates combining algorithms and customizing the primary color:

import React from 'react';
import { ConfigProvider, Button, theme } from 'antd';

const App = () => (
  <ConfigProvider
    theme={{
      algorithm: [theme.darkAlgorithm, theme.compactAlgorithm],
      token: {
        colorPrimary: '#ff4d4f',
      },
    }}
  >
    <Button type="primary">Primary in Dark + Compact</Button>
  </ConfigProvider>
);

export default App;

Accessing Dark Tokens Programmatically

When building custom components or applying dynamic styles, you may need to access the current token values directly. The useToken hook, exported from components/theme/index.tsx, returns the active design token set, including all dark mode values when the dark algorithm is active.

This approach ensures your custom elements remain consistent with Ant Design's theming:

import React from 'react';
import { ConfigProvider, theme, Card } from 'antd';

const ThemedCard = () => {
  const { token } = theme.useToken();
  return (
    <Card style={{ backgroundColor: token.colorBgContainer }}>
      Card that follows the dark theme background
    </Card>
  );
};

export default ThemedCard;

Because token generation occurs in pure JavaScript, dark mode works seamlessly with Server-Side Rendering (SSR). The server renders the correct CSS variables on the initial request, preventing flash-of-unstyled-content or theme mismatches during hydration.

Summary

• Ant Design implements dark mode through the design token system and configurable algorithms located in components/theme/themes/dark/index.ts.
• Enable dark mode by passing algorithm: theme.darkAlgorithm to ConfigProvider in components/config-provider/index.tsx.
• Combine algorithms such as darkAlgorithm and compactAlgorithm by providing an array to the algorithm property.
• Override specific tokens like colorPrimary while maintaining the dark palette using the token prop.
• Access current token values programmatically via the useToken hook from components/theme/index.tsx for custom component styling.
• Dark mode is fully compatible with SSR, with tokens generated on both server and client.

Frequently Asked Questions

Does Ant Design support dark mode out of the box?

Yes. Ant Design provides built-in dark mode support through the darkAlgorithm available in the theme object. You do not need to write custom CSS or manage color variables manually; simply import the algorithm from antd and apply it via ConfigProvider to transform your entire application.

Can I combine dark mode with the compact theme?

Yes. You can compose multiple algorithms by passing an array to the algorithm property in your theme configuration. For example, algorithm: [theme.darkAlgorithm, theme.compactAlgorithm] applies both the dark color palette and the compact spacing density simultaneously, as demonstrated in docs/react/demo/preset-algorithm.tsx.

How do I customize specific colors in dark mode?

Provide a token object alongside the algorithm in your ConfigProvider theme prop. The dark algorithm generates the base dark palette first, and then your custom token values override specific properties such as colorPrimary or colorBgContainer while preserving the remaining dark theme values.

Will dark mode work with server-side rendering (SSR)?

Yes. Because Ant Design's token system generates CSS variables through pure JavaScript calculations, dark mode works seamlessly with SSR frameworks like Next.js. The server renders the appropriate CSS variables on the initial request, and the client hydrates them without theme flashing or visual mismatches.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}