Tokens and zeroRuntime are often mentioned together, but they do different jobs. Design tokens change the theme values Ant Design uses: colors, sizing, algorithms, and component-level values. zeroRuntime changes how component CSS reaches the browser. It turns off runtime style generation and asks you to import a precompiled stylesheet. In Ant Design 6, the practical answer is to make supported design changes through the theme API, and to use zeroRuntime when you want precompiled component styles. Enabling zeroRuntime does not replace token configuration, so it is not a shortcut around customization.
Tokens and zeroRuntime solve different problems
Most of the confusion in the title comes from treating these as one feature. The table below separates them.
As an Amazon Associate I earn from qualifying purchases.
| Question | Design tokens | zeroRuntime |
|---|---|---|
| What it controls | Theme values: global tokens, preset algorithms, and component tokens | How component styles are supplied: generated at runtime, or precompiled CSS |
| Where it is set | The theme property of ConfigProvider |
The theme property of ConfigProvider, plus an explicit stylesheet import |
| Changes the visual design? | Yes, for the design changes the theme API supports | Not by itself; it changes delivery of the component styles |
| Replaces CSS overrides? | Covers supported design changes; custom CSS is still needed for anything outside the theme API | Not stated as a replacement for overrides in the official theme documentation |
What zeroRuntime does
Ant Design’s theme documentation states that zeroRuntime was added in version 6.0.0. It prevents runtime style generation and requires an additional CSS import. The documented full-stylesheet setup has two parts: import the complete stylesheet, import 'antd/dist/antd.css';, and set theme={{ zeroRuntime: true }} on ConfigProvider.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The documentation says the full stylesheet includes all Ant Design component styles and does not include hashed class names. The official guide describes the mode this way: “Starting from 6.0.0, we provide zeroRuntime mode to further improve application performance.” That is the documented intent. The official material does not provide a measured performance result, so this article does not claim a speed or bundle-size gain.
#1 Best Overall
Configure tokens first
Before changing how styles are delivered, check whether the design change is already covered by the theme API. Work through the levels in this order:
- Global token. Change a shared value such as the primary color through
tokenin thethemeproperty ofConfigProvider. - Preset algorithm. If you want a different overall look, such as a dark theme, apply an algorithm through the same
themeproperty. - Component token. If one component needs a different value, use the
componentskey inside the samethemeconfiguration for that component’s tokens.
<ConfigProvider
theme={{
token: { colorPrimary: '#1677ff' },
components: { Button: { /* component tokens */ } },
}}
>
<App />
</ConfigProvider>Only fall back to CSS overrides for changes that the theme API does not express. Overrides aimed at internal component markup are the most fragile option, as covered in the migration section below.
Rank #2
Choose a style-delivery path
The official guidance offers two ways to supply component styles when you use zeroRuntime. The table compares them on the points that matter in a real project.
Recommended Free Tools
| Factor | Full precompiled stylesheet | Static styles via @ant-design/static-style-extract |
|---|---|---|
| Style coverage | All component styles | Selected components, chosen through the package’s includes option |
| Fit with configuration changes | Documented as the default path; may be unsuitable when the project changes configuration, such as a custom prefix | Documented for cases where the full stylesheet is unsuitable, including configuration changes such as a custom prefix |
| Integration effort | Import one stylesheet and enable zeroRuntime |
Generate the static file and make sure it is included in the application build |
| Bundle size or runtime speed | Not stated; no measured comparison in the official documentation | Not stated; no measured comparison in the official documentation |
Set up zeroRuntime step by step
- Confirm that your project is on Ant Design 6 and that React is version 18 or later.
- Import the full stylesheet once, in your application entry file:
import 'antd/dist/antd.css';. - Set
zeroRuntime: truein thethemeproperty ofConfigProvider. - Keep your token and component-token configuration in place. Enabling
zeroRuntimedoes not remove it. - If the full stylesheet is too broad, or your project changes configuration such as a custom prefix, evaluate
@ant-design/static-style-extractand include the generated file in your build. - If you also use the
@layermechanism, place the stylesheet inside the matching layer (see below).
Upgrading from Ant Design 5
The official v5-to-v6 migration guide covers the following points. Check the current guide before upgrading, since version requirements change over time.
- React: Ant Design 6 requires React 18 or later.
- Browsers: Internet Explorer is no longer supported. Check your browser support matrix against your audience.
- CSS variables: Ant Design 6 uses CSS variables by default, so custom CSS that depends on the older output should be tested.
- Icons: Update the icons package as the migration guide directs.
- Internal DOM: Component DOM changes can break custom selectors that target internal nodes. Review every selector that reaches into component internals.
- Migration checks: The guide recommends the Ant Design CLI to find deprecated APIs, component usage, and version differences.
Using zeroRuntime with @layer
Ant Design’s compatibility guide documents @layer support from version 5.17.0. It is a way to lower the priority of Ant Design’s styles so your own CSS wins without raising selector specificity. When you combine this with zeroRuntime, the precompiled standalone stylesheet must be imported into the same layer. The guide’s example is:
@import url(antd.css) layer(antd);Two rules keep the cascade predictable. Set the layer order on purpose, so the Ant Design layer sits where you expect relative to your own layers. Assign your reset CSS to a layer consistently. An unlayered or mis-layered reset can override the lowered-priority Ant Design styles, which is the same problem the layer was meant to prevent.
Rank #4
Troubleshooting
- Components appear unstyled after enabling zeroRuntime. The full stylesheet import is missing, or the build does not include it. Confirm the import runs in the entry file and that the bundled CSS contains Ant Design rules.
- Your overrides do not win when using @layer. The Ant Design stylesheet is outside its layer, the layer order is wrong, or the reset CSS is unlayered. Check each of these in that order.
- The full stylesheet does not fit your setup. If you use a custom prefix or need only some components, the full stylesheet may be the wrong choice. Evaluate static style extraction instead.
- Custom selectors broke after the v6 upgrade. Component DOM changed. Rewrite selectors to target documented tokens or public class hooks where possible, rather than internal nodes.
What is not established
The official documentation does not publish a measured performance number for zeroRuntime, a bundle-size comparison against runtime generation, or a benchmark for static extraction. If performance is your reason for switching, measure your own application before and after the change. The version numbers in this article are the ones stated in Ant Design’s documentation at the time of writing, and they should be checked against the current docs before you upgrade.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteQuick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
