Gatsby Head API
Support for the Gatsby Head API was added in
Gatsby includes a built-in
Head export that allows you to add elements to the document head of your pages.
Compared to react-helmet or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features.
By exporting a named function called
Head you can set the metadata for a page:
The arrow function syntax is also valid:
When defining multiple metatags use React Fragments:
You can also re-export a
Head function in your page from another file:
Support for editing
<body>was added in
You can set
Gatsby will use provided attributes and inject them into resulting html.
To avoid duplicate tags in your
<head> you can use the
id property on your tags to make sure that only one is rendered. Given the following example:
In this case only the second
<link id="icon" rel="icon" href="icon-specific-for-this-page" /> is rendered. In a list of items with the same
id, the last item wins and is used in the HTML.
You’ll need to be aware of these things when using Gatsby Head:
- You can only define the
Headexport inside a page (that includes templates for
createPage), not in a component.
- The contents of Gatsby Head get cleared upon unmounting the page, so make sure that each page defines what it needs in its
Headfunction needs to return valid JSX.
- Valid tags inside the
bodytags defined in
Headoverwrite the attributes defined in
- Data block
<script>tags such as
<script type="application/ld+json">can go in the
Headfunction, but dynamic scripts are better loaded with the Gatsby Script Component in your pages or components.
- As of
Headcan access React Context that you defined in the
wrapRootElementAPI. It’s important to note that
wrapRootElementshould only be used to set up context providers. UI components should be defined in
Head function receives these properties:
location.pathname: Returns the Location object’s URL’s path
params: The URL parameters when the page has a
matchPath(when using client-only routes)
data: Data passed into the page via an exported GraphQL query
pageContext: A context object which is passed in during the creation of the page