Humble Head

Gatsby Month of Gatsby / 2 min read

Populating the <head> tag might not be the most scintillating component of building a web site, but it’s an important one to get right. Gatsby’s Head API provides a flexible mechanism for doing this and supersedes the functionality from React Helmet.

Implementation is very simple: all you need to do is export a suitable Head() function. We’ll take a look at three approaches to doing this:

  • embedding Head() into each page;
  • importing a centralised definition of Head(); or
  • defining Head() in a template.

📢 The Head API was implemented in Gatsby 4.19.0, so make sure that you are using that version or higher.

🚀 TL;DR Show me the code. Look at the 23-head-api branch. This site is deployed here.

Page

The first option is to implement Head() directly in the code for the page.

export const Head = ({ data }) => {
  return (
    <>
      <html lang="fr" dir="ltr" />
      <title>WhimsyWeb</title>
    </>
  );
}

Of course, you can make this substantially more flexible by using attributes from data to populate the components of the <head> tag.

➡️ See the implementation in src/pages/home.js.

This is the simplest way to implement the Head API but it will become laborious if you have lots of pages to update.

💡 Note: By including an <html> tag in the definition of Head() you can also affect the attributes of this top-level tag.

Import

A more flexible alternative is to define Head() in a separate module and then import it into the pages.

For example, define Head() in src/components/head.js. Then from a page import and re-export like this:

import { Head } from "../components/head";

export { Head };

or, alternatively:

export { Head } from "../components/head";

➡️ You can find a slightly enhanced example of this in src/pages/404.js.

Template

Both of the above approaches require you to amend individual pages. There is a third option that allows you to quickly implement Head() for a collection of pages.

If you use a template to construct the page content (using, for example, AsciiDoc) then you simply need to update the template.

➡️ See the implementation in src/templates/article.js.

Conclusion

🚀 TL;DR Show me the code. Look at the 23-head-api branch. This site is deployed here.