Nested Theme Providers
While in most cases, you'll be using a
ThemeUIProvider 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.
When adding a nested Theme Provider, it will inherit the
components object from its parent. The
theme object will be deeply merged
with the outer context's theme. The
components object will override any outer
context components, but apply styling based on
theme.styles. The inner Theme
Provider will not create a new color mode state, but inherit this from the
ThemeUIProvider 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
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.