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:
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, 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
- 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.
- Using the Head API and react-helmet in the same page is not supported as it can generate unexpected results.
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
The scope of Gatsby Head is to modify the
<head> portion of your pages. To edit other parts like
<body>, please use the Gatsby Server Rendering APIs.
One common use case is to modify the
<html> element to e.g. add a
lang attribute. You can achieve this the following way: