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.
How contexts merge
When adding a nested Theme Provider, it will inherit the theme
and
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
parent.
Functional Themes
The nested 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
granular way.
Gatsby themes
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.