TutorialHow-To GuidesReferenceConceptual Guides

v3 Docsv2 Docsv1 Docs
Sign Up for Free

Recipes: Working with Themes

A Gatsby theme abstracts Gatsby configuration (shared functionality, data sourcing, design) into an installable package. This means that the configuration and functionality isn’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another.

Creating a new site using a theme

Found a theme you’d like to use on your project? Awesome! You can configure it for use by following the steps below.

If you’d like to take a look at more theme options, check out this list of themes.



  1. Create a gatsby site
  1. Change directory and install theme

In this example, our theme is gatsby-theme-blog. You can replace that reference with whatever your theme is named.

  1. Add theme to gatsby-config.js

Follow the instructions found in the README of the theme you’re using to determine what configuration it requires.

To learn how to further customize the blog theme, check out the available configuration options in the Gatsby-theme-blog Documentation.

  1. Run gatsby develop, the theme should now be running on your site. In this case with the blog theme configured with the basePath to "/blog", it should be available at http://localhost:8000/blog.

Additional resources

Creating a new site using a theme starter

Creating a site based on a starter that configures a theme follows the same process as creating a site based on a starter that doesn’t configure a theme. In this example you can use the starter for creating a new site that uses the official Gatsby blog theme.



  1. Generate a new site based on the blog theme starter:
  1. Run your new site:

Additional resources

Building a new theme

Video hosted on



  1. Generate a new theme workspace using the Gatsby theme workspace starter:
  1. Run the example site in the workspace:

Additional resources

Edit this page on GitHub
© 2022 Gatsby, Inc.