Skip to content

Getting Started

Gatsby Theme Catalyst is an opinionated set of integrated themes and starters to accelerate your next Gatsby project. There is one “core” theme which is built on until you have a complete site. This pattern allows for better maintainability through npm updates, developer choice for where to jump off, and a happy path for extendability using Gatsby’s component shadowing API.

This tutorial assumes the following:

  • That you understand Gatsby fundamentals
  • That you understand Gatsby themes

You might also want to read about component shadowing as this is a key concept for extending Gatsby themes.

What this covers

This getting started guide will get you up and running with a boilerplate starter. Content is authored in MDX and there is very minimal styling. If you want to test a more complete site, including SANITY integration, you should check out gatsby-theme-catalyst-bery.

Install the themes using a starter

This easiest way to get started is with a Gatsby starter. This tutorial will use gatsby-starter-catalyst which is intended as a boilerplate to build on top of.

The themes included in this starter are:

# create a new Gatsby site using the basic starter
gatsby new catalyst
# change into your new directory
cd catalyst
# launch the site
gatsby develop

Update gatsby-config.js

Open gatsby-config.js and update the placeholder data. Most fields are common to other Gatsby sites or documented with inline comments. You can read more about specialized fields like socialLinks in the gatsby-config section of the docs.

Update your branding

This is section is updated for Gatsby Theme Catalyst v6 and above

Branding is managed via component shadowing to give you full presentational control over the logo and site title. The file you want to modify is located at src/components/header/branding.js. There are inline code comments explaining what each section of the file is doing.

If you just want to update the logo and site title, without touching the code, you can update the site title via gatsby-config.js and replace content/assets/catalyst-site-logo.png with a new image, keeping the same file name.

catalyst-site-logo is used as the logo on the actual web pages. You can write your own custom GraphQL query inside the branding component to replace this entirely if you want.

catalyst-site-icon is used as the icon for the browser and offline mode. If you change this file make sure you update the options for gatsby-plugin-manifest as well or your will get an error.

catalyst-site-social is used as a fallback social media image if there is not a featured image in a blog post or on a page.

Create some content

By default content is authored using MDX. Go to content/pages/index.mdx to modify your home page. Note the Seo component on the top of the page which allows you to customize the metadata for each page.

Try pasting the following code into index.mdx:

<Seo title="Home" description="My Home Page"/>
# I am awesome
Yes you are!

Experiment with theme options

Gatsby Theme Catalyst uses theme options extensively as feature flags for the various themes. Take a look at the plugin array in gatsby-config.js and try changing some of the options to see how it affects the theme.

resolve: `gatsby-theme-catalyst-core`,
options: {
//Default options are:
// contentPath: `content/pages`,
// assetPath: `content/assets`,
// remarkImagesWidth: 1440,
// imageQuality: 50,
// useAlertBanner: false,
resolve: `gatsby-theme-catalyst-header-top`,
options: {
// Default options are
// useStickyHeader: true,
// useHeaderSocialLinks: true,
// useColorMode: true
resolve: `gatsby-theme-catalyst-footer`,
options: {
// Default options are
// useFooterSocialLinks: true,
// footerContentLocation: "left", // "left", "right", "center"

Experiment with Theme-UI

Open src/gatsby-plugin-theme-ui/index.js.

This is where you modify and change the theming for your site. You can read more about the integration with Theme-UI in the docs.

Try copy and pasting the following code into your theme file to see what happens.

import { merge } from "theme-ui"
import { BaseTheme } from "gatsby-theme-catalyst-core"
export default merge(BaseTheme, {
// Modifications to the base theme go here. This is an example changing colors and using variants to change your navigation links. Uncomment the code below to see what happens.
colors: {
background: "pink",
modes: {
dark: {
background: "purple",
variants: {
navLinks: {
border: "5px solid red",

Experiment with switching headers by switching themes

An integrated set of themes enables the power to dramatically change whole aspects of the design by just swapping out themes.

Install an alternate header theme.

yarn add gatsby-theme-catalyst-header-side

Goto gatsby-config.js and change your header just by changing the plugins array.

plugins: [
// Remove gatsby-theme-catalyst-header-top and replace with
resolve: `gatsby-theme-catalyst-header-side`,
options: {
// Default options are
// useStickyHeader: true,
// useHeaderSocialLinks: true,
// useColorMode: true

Get building

This should begin to give you an idea of what is possible with Gatsby Theme Catalyst and the launching pad it provides for developing your own Gatsby projects.

For an example of a complete site check out gatsby-theme-catalyst-bery which adds a both a data layer ( and a presentation layer on top of the boilerplate starter covered here.

You can read more detail in the documentation about further customizing your themes and site.

© 2021 Gatsby Theme Catalyst