Gatsby Themes introduce a concept called Component Shadowing. This feature allows users to override a component in order to customize its rendering.
With other theming approaches it's impossible to change aspects of a theme if a configuration option hasn't been built in. Component Shadowing provides a powerful escape hatch to let users make quick, one-off changes that might not make sense to support in the theme itself.
For example, imagine you've installed
gatsby-theme-blog and want to customize the author
Bio component to add a link to their personal website. Before Component Shadowing, this new functionality would require configuration at the theme level or using a fork of the codebase. These approaches result in a difficult upgrade path and a maintenance burden.
Component Shadowing let's you replace the theme's original file,
gatsby-theme-blog/src/components/bio.js, with your own to implement any changes you need.
If you've installed
gatsby-theme-blog you'll notice that it renders a
Bio component which is used in the
BlogPost template. If you'd like to change the
Bio component you can do so with Component Shadowing.
Theme File Structure
gatsby-theme-blog has the following file structure (some files have been omitted for brevity):
Component Shadowing uses a naming convention to determine which component will be rendered. In order to override the
Bio component in
gatsby-theme-blog, create a file named
Any file that lives in the
src/gatsby-theme-blog directory of the user's site will be used instead of a file with the same name in the theme's
This means that
user-site/src/gatsby-theme-blog/components/bio.js will be rendered in place of
With a successful shadow of the
Bio component you'll result in the following directory tree:
Leveraging Component Shadowing is a great way to introduce small changes to a theme and even layer in new functionality.
Note: In the future we'll publish a technical post that will dive into the internals of Component Shadowing.
gatsby-theme-blog has a design tokens file which is used to define font sizing, spacing, and colors. If you want to modify these values, you can shadow it.
To do so, create a file named
You'll result in the following directory tree:
Now, blue and red will have your custom values and will be reflected in the theme wherever
theme.colors.red are used.
How much shadowing is too much shadowing?
If you've found yourself shadowing a large amount of components in a particular theme it might make sense to use a fork instead.
In the future we'll be introducing new tooling around Component Shadowing that will list when shadowing occurs, what files are available to shadow, and the ability to eject from a theme.
Component Shadowing is a powerful feature for making one-off changes to a theme without the need for complex configuration or maintaining a fork of the code. It's a stable feature in Gatsby Themes and is currently being used in production.