Adding an SEO Component
Adding metadata to pages (such as a title or description) is key in helping search engines like Google understand your content, and decide when to surface it in search results. This information also gets displayed when someone shares your website, e.g. on Twitter. Using the Gatsby Head API you can change the document head of your pages.
Gatsby automatically provides drop-in support for server rendering of metadata and it’ll be added to the static HTML pages that Gatsby produces. This helps your site rank and perform better in search engines.
By the end of this guide you’ll have a SEO component that you can use in your pages to define metadata.
- A Gatsby project set up with
firstname.lastname@example.org later. (Need help creating one? Follow the Quick Start)
siteMetadata section of the
gatsby-config file is available in the GraphQL datalayer. It’s considered best practice to place your site metadata there. The
siteUrl should be the URL of your deployed target (e.g. production domain) so that later metatags can point to absolute URLs.
Add the following keys to your configuration:
You can always extend the
siteMetadata object and subsequently customize the
<SEO /> component to your liking. When defining the
image like above, make sure that you have an image with the same name and file extension in the
Since you need to use the information that you just placed inside
siteMetadata with the SEO component, you can create a custom React hook called
useSiteMetadata to fetch that information. This way you can reference these values in other places, too.
Create a new file called
src/hooks. Query the information from the
site interface through a useStaticQuery hook:
You’ll be able to directly get
description, etc. from this hook.
Create a new file called
src/components. Your SEO component will receive things like
children, etc. as props and the information from your
useSiteMetadata hook is used as a fallback if no props are passed. For things that won’t change on a per-page basis (e.g. the Twitter username) the
useSiteMetadata hook data is directly used.
Here’s the complete SEO component:
All props are optional since each value has a default value or fallback. The
pathname prop will be the relative path of the page so you need to construct an absolute URL with
You can extend the
seo object with other keys, but it’s recommended to follow the pattern of
prop || fallback so that no value is
Usage in pages
When you just want to use the default values of your SEO component (e.g. on the homepage) you can import it and render it without any props:
To override individual values use the defined props on the SEO component:
To add one-off metatags to a page, provide
children to the SEO component:
<script> tags such as
<script type="application/ld+json"> can go in the
Head function, but dynamic scripts are better loaded with the Gatsby Script Component in your pages or components.
If you want to edit the
<body>, please read the Gatsby Head reference guide.
Google uses structured data that it finds on the web to understand the content of the page, as well as to gather information about the web and the world in general.
You can use the Rich Results Test from Google during local development to check if you pass valid information.
After deployment, their Rich result status reports may help to monitor the health of your pages and mitigate any templating or serving issues.
- Using Gatsby Head with TypeScript
- Gatsby Head Reference Guide
- Gatsby Script Component
- Blog posts about SEO in Gatsby
- Audit with Lighthouse