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
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
If you’ve installed
gatsby-theme-blog you’ll notice that it renders a
which is used in the
BlogPost template. If you’d like to change the
you can do so with Component Shadowing.
gatsby-theme-blog has the following file structure (some files have been omitted for
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
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.
Component Shadowing isn’t restricted to React components; you can override any
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.
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.