Crashes, 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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstalliTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
For Ant Design 6, most design changes that people make with CSS overrides can be made through theme tokens set on ConfigProvider. zeroRuntime is a separate setting. It is not a token. It stops Ant Design from generating component styles at runtime, and it requires you to import a precompiled stylesheet yourself. The two work together, but they solve different problems, and treating them as one thing is the most common source of confusion.
Tokens and zeroRuntime do different jobs
Tokens describe the values a theme is built from: colors, sizes, radii, and similar settings. zeroRuntime decides how the component styles that use those values reach the browser. Ant Design’s theme documentation lists token, algorithm, components, and cssVar alongside zeroRuntime as options of the same theme object, which is why they are easy to blur together.
| Question | Theme tokens (token, algorithm, components) |
zeroRuntime |
|---|---|---|
| What it controls | The values a theme uses, such as color, size, and radius, and how components are tuned | Whether component styles are generated at runtime or supplied by a precompiled stylesheet |
| Where it is set | theme prop on ConfigProvider |
theme prop on ConfigProvider, as zeroRuntime: true |
| Requires an extra CSS import | No | Yes, the stylesheet must be imported |
| Introduced | Part of the theme API used since Ant Design 5 | Ant Design 6.0.0, according to the theme documentation |
| Replaces the other | No | No. It does not replace token customization |
In practical terms, if you want a different brand color, a denser layout, or a dark variant, you change tokens. If you want to change how the stylesheet is delivered, you consider zeroRuntime. Neither choice is a reason to write selectors against Ant Design’s internal class names.
Change the design with tokens before writing CSS
Work down this list in order. Stop at the first step that covers your change.
#1 Best Overall
- Global token. Set the value in
theme.tokenonConfigProvider, for example<ConfigProvider theme={{ token: { colorPrimary: '#722ed1' } }}>. One global value updates every component that reads it. - Preset algorithm. If you need a whole-theme variant such as dark mode, set it through the
algorithmproperty rather than recoloring each component by hand. - Component token. If only one component needs a different value, set it under
theme.componentsusing the component’s name as the key. This keeps the change inside that component’s own tokens. - Custom CSS. Use a stylesheet rule only for layout or behavior that no token expresses. Write it against your own wrapper elements, not against Ant Design’s generated internals.
Most overrides that existed in Ant Design 5 projects fall into the first three steps. The last step is where custom CSS still belongs, and it is also where the migration risks described below appear.
Turn on zeroRuntime in Ant Design 6
Ant Design’s theme documentation describes zeroRuntime as a mode that prevents runtime style generation and requires an extra CSS import. It was added in version 6.0.0. Ant Design’s stated reason for offering it is performance: the documentation says that “starting from 6.0.0, we provide zeroRuntime mode to further improve application performance” (Ant Design documentation, “Customize Theme”).
- Confirm that the project is on Ant Design 6.0.0 or later and runs React 18 or later.
- Import the full stylesheet once, in your application entry file:
import 'antd/dist/antd.css'; - Enable the mode on the provider:
<ConfigProvider theme={{ zeroRuntime: true }}>. Keep your token and component settings in the samethemeobject if you already use them. - Check the result in the browser. Component styles should now come from the imported file. The documentation states that this full stylesheet does not include hashed class names, so do not write selectors that depend on generated hashed names. Target your own wrappers or the documented class names instead.
The full stylesheet contains styles for all Ant Design components. That is the trade-off: nothing is generated at runtime, but the file is broader than what most pages use.
When the full stylesheet is too broad
Ant Design recommends @ant-design/static-style-extract when the full stylesheet is unsuitable. The two situations the documentation names are an application that needs fewer styles and an application that uses configuration changes such as a custom prefix. The package generates static styles, and its documented example selects the components to include through an includes option.
| Option | Full precompiled stylesheet (antd/dist/antd.css) |
Generated static styles (@ant-design/static-style-extract) |
|---|---|---|
| Component coverage | All Ant Design components | Only the components listed in includes |
| Custom prefix or other style configuration | Not stated as a supported case in the documentation | Named in the documentation as a case it addresses |
| Setup | One import plus zeroRuntime: true |
Run the extraction, then include the generated file in the application build |
| Measured size or speed difference | Not stated by the documentation | Not stated by the documentation |
If you choose the generated route, make the generated file part of the build output. A file that is generated but not loaded produces the same unstyled result as a missing import.
Layer order if you use @layer
Ant Design’s compatibility documentation says that @layer support is available from version 5.17.0. This is the mechanism for lowering the priority of Ant Design’s styles so that your own CSS wins without high-specificity selectors. The documentation’s rule for combining it with zeroRuntime is that the precompiled standalone stylesheet must be imported into the matching layer. Its example is:
Rank #4
@import url(antd.css) layer(antd);
Two checks follow from that rule:
- The Ant Design stylesheet must sit in the layer you named for it, not in the unlayered global scope. Unlayered styles outrank every layer, so a stray import defeats the lowered priority.
- Your reset CSS needs a layer assigned consistently. If it is unlayered while Ant Design’s styles are lowered, the reset can override Ant Design styles you did not intend it to touch.
When a style appears to ignore your override, check the layer order first. A style that looks correct in one page and wrong in another often points to a stylesheet loaded in a different layer.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Moving an Ant Design 5 project to 6
The official v5-to-v6 migration guide makes several points that matter before you change styling strategy:
Best Value
- React: Ant Design 6 requires React 18 or later.
- Browsers: Ant Design 6 no longer supports Internet Explorer.
- CSS variables: Version 6 uses CSS variables by default.
- Custom selectors: Changes to component DOM can break custom styles that target internal nodes. Audit any selector that reaches into a component’s inner elements.
- Migration checks: The guide recommends the Ant Design CLI to find deprecated APIs, component usage that has changed, and version differences.
Expect the DOM audit to take the longest. Overrides that target inner nodes are the ones most likely to need rewriting, and token settings that replace them are usually the cleaner fix.
What the documentation does not establish
Ant Design’s documentation describes the intent behind zeroRuntime but does not publish a measured bundle-size or runtime-performance comparison. This article therefore does not claim a specific speed gain or size saving. Test the mode on your own page weight and rendering before you assume a benefit.
The documentation also does not list every configuration that the full stylesheet supports, so if your project depends on a non-default setting, verify it against the current theme documentation and the static-style package’s own documentation before committing to either delivery method.
Quick Recap
“
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.
