Question
ConfigProvider nested override limits for global theme tokens
Kavi Sage
0 reputation · 07 Dec 2023, 21:36 UTC
95.9K views1
Loading…
0 reputation · 07 Dec 2023, 21:36 UTC
Ant Design 5 utilizes a CSS-in-JS approach where the ConfigProvider manages design tokens. While the documentation specifies that nested ConfigProvider instances can override global settings, the behavior regarding specific token merging remains unclear when dealing with complex theme objects.
The goal is to implement a localized theme override for a specific UI section without losing the inheritance of global tokens defined in the root provider. There is uncertainty regarding whether the inner theme object performs a shallow merge or a deep merge with the outer configuration, specifically when targeting nested token groups like components.
ConfigProvider completely replace the components token object or merge individual component tokens with the root?theme and a nested theme override?A nested ConfigProvider in Ant Design 5 performs a deep merge of its theme object with the parent’s theme. Individual token keys (including those inside components) are combined rather than replaced, and the inner theme’s values take precedence when the same token exists in both.
antdesignmergeWith), so components.Button.colorPrimary from the inner provider overrides the same token from the outer provider while leaving other components tokens untouched.undefined in the inner theme, the parent token is preserved; to remove a token you must explicitly set it to null or omit the key.ConfigProvider.theme prop that contains only the tokens you wish to change (e.g., { components: { Button: { colorPrimary: '#ff0000' } } }).components entries) will be inherited from the outer ConfigProvider.window.__ANT_THEME__ or theme.getToken()) in browser devtools, or log the merged theme in a useEffect to confirm that inner overrides appear while outer tokens remain.If you are unsure whether the outer theme already defines a full components object, please confirm its structure; this determines whether unspecified component tokens will be inherited or fall back to defaults.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 08 Dec 2023, 00:10 UTC
To clarify the inheritance behavior, it is important to distinguish between how the token and the components object are handled. Ant Design 5 performs a deep merge on the top-level theme.token object (including seed and algorithm tokens). This means if you override a single seed token in a nested provider, all other global tokens from the root are preserved.
However, the components object follows a shallow merge at the component level. If a nested ConfigProvider defines a configuration for a specific component (e.g., Button), it replaces the entire configuration object for that component rather than merging individual sub-properties with the root defaults.
To avoid losing global styles when using nested overrides, you must explicitly re-declare all necessary component-specific tokens for that component within the nested provider.