Nested Theme Providers
While in most cases, you'll be using a
ThemeProvider component at the root of your application to set a site-wide theme,
nested Theme Providers are a powerful way to adjust styles contextually.
For example, when building a Gatsby theme, you may want to set some base thematic values that the user can easily override to match their site, but keep some theme-specific styles for use only in the pages that your Gatsby theme generates. Or, you might want to have a global theme, but adjust styles in a small section of a page to render with a dark color scheme.
How contexts merge
When adding a nested Theme Provider, it will inherit the
components object from its parent.
theme object will be deeply merged with the outer context's theme.
components object will override any outer context components, but apply styling based on
The inner Theme Provider will not create a new color mode state, but inherit this from the parent.
ThemeProvider component can use a functional theme to avoid deep merging the objects or to control the way the two objects are merged in a more granular way.
When building a Gatsby theme, you should use
gatsby-plugin-theme-ui for parts of your theme that should be overridden or merged with other themes.
If you need to specify a Gatsby theme-specific subtheme, use a nested Theme Provider in a layout component that only renders around pages that you control.
This allows the end user to change their site-level theme without affecting custom styles you might need in your theme.
The end user can still shadow any components in your theme if they need to.