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.