In the world of Gatsby themes, component shadowing is an extremely powerful way for developers to provide their own components for the theme to use over the defaults. You can shadow any file that is processed by webpack. This includes sass files, mdx files, and the react components themselves.

Caveats

If you completely shadow a file you won’t get future updates to that individual file. These are some golden rules to make sure you stay as close to the theme as possible and not forgo future updates.

Open a quick issue in the gatsby-theme-carbon repo to make sure we’re not working on your change.
Shadow as few files as you can to achieve your goal. If you can shadow just a single file, that’s ideal.
If you do end up shadowing a component, please tell us! We might use it to inform future development.

Shadowing basics

In order to shadow a component in the theme, all you need to do is place a directory in the src/gatsby-theme-carbon in your project. The directory should have the same name as the file you’re shadowing.

In order to place your own title in the Header component:

Create a directory the same name as the component you wish to shadow. Everything after src/gatsby-theme-carbon/ refers to the src directory of gatsby-theme-carbon.
Create a file inside of the directory that matches the component you want to shadow. For example: src/gatsby-theme-carbon/components/Header/index.js. If shadowing Footer or Header the file must be named index.js
Import the component you wish to shadow by providing the full url pointing at the component within the theme
Your component will receive the same props as the one you’re shadowing. You’ll can log those props to see if you’ll need any of them
Regardless, you should ALWAYS spread the extra props into the original component, this allows the core component to function as needed. Even if it doesn’t receive any props now, it might in the future.
Provide your new, custom component as the default export

import React from 'react';
import Header from 'gatsby-theme-carbon/src/components/Header';

const CustomHeader = (props) => (
  <Header {...props}>
    <span>Gatsby theme</span>&nbsp;Carbon
  </Header>
);

Copy to clipboard

Components you’ll need to shadow

We’ve already provided pre-shadowed, dummy components however these are the ones you’ll definitely need to shadow.

Component	Path	Description
ResourceLinks	`src/gatsby-theme-carbon/components/LeftNav/ResourceLinks.js`	The bottom links on the SideNav, pass `shouldOpenNewTabs` to open links externally
Footer	`src/gatsby-theme-carbon/components/Footer/index.js`	The links and content at the bottom of each page
Header	`src/gatsby-theme-carbon/components/Header/index.js`	The text in the top left corner of the UI Shell

Edit this page on GitHub

Page last updated: 24 June 2020

Guides: npm scripts

Guides: Styling