Using a Theme
In this tutorial, you’ll learn how to use Gatsby themes by creating a new site using the official Gatsby blog theme.
Creating a site using a theme starter starts the same way as using a regular Gatsby starter:
Creating a new site from the starter installed all of the blog theme’s dependencies for you. Next, run the site and see what you have:
The blog theme starter ships with a solid gray image for the avatar. Add your own avatar by choosing the image you want, and overwriting the file located at
Customize the information on your site by replacing the site metadata in the
When using Gatsby themes, you can take advantage of something called component shadowing. This allows you to override the default component included in the theme with a custom one you’ve created.
The Gatsby blog theme package has a component that contains the content of the site author’s biography. The file path to that component (in the blog theme package, not your site) is
src/gatsby-theme-blog/components/bio-content.js. You can find this path by looking through the theme in your site’s
If you look at the file tree of your site, you’ll see it looks like this:
src directory of the site, there’s a
gatsby-theme-blog directory. Any file placed in that directory with a path that matches the path of a file in the blog theme directory will completely shadow the theme.
💡 The name of the directory (here
gatsby-theme-blog) must exactly mirror the name of the published theme package, which in this case is
Open up the
bio-content.js file and make some content edits:
At this point, you should have an updated avatar, updated site details, and an updated bio:
Now you can add your first blog post, and get rid of the demo content in the starter.
Create a new file in
my-blog/content/posts. Name it whatever you’d like (with a
.mdx file extension), and add some content! Here’s an example:
Delete the two demo posts in the
Restart the dev server, and you’ll see your updated blog content:
The blog theme ships with a default Gatsby purple theme, but you can override and customize the theming of your site to your heart’s content. In this tutorial, you’ll change a few colors.
/src/gatsby-theme-blog/gatsby-plugin-theme-ui/colors.js, and uncomment the code in that file.
Now, instead of a purple theme, you have a blue theme instead:
In this file, you’re pulling in the default color theme (imported as
defaultThemeColors here), and overriding certain color keys.
To see what other theme colors you can customize, check out the
colors.js file in the official blog theme (
This was a step-by-step introduction to using a Gatsby theme through looking at a specific example. Note that different themes will be built differently, to accept different customization options. To dive deeper, check out the Gatsby Theme docs.