Skip to content
Adding global script and stylesheets to Gatsby head
Photo by Cesar Aloy on Unsplash
  • Gatsby

Adding global script and stylesheets to Gatsby head

February 16, 2021 1 Min

Adding a global script or stylesheet to your <head> element in Gatsby can feel a bit tricky. You can’t just copy and paste into an html template from days of yore. The final html document structure is composed by Gatsby at build time which means we need a couple of extra steps to get this done.

The best way to do this globally is via the onRenderBody API in gatsby-ssr.js. This hooks into the build process and allows you to globally customize the head elements of your entire website.

If you want to customize script and style tags in the head element on a per-page basis this is best handled with gatsby-plugin-react-helmet which allows you to tweak what goes into the head element on the page level.

Here is an example of how I added Fathom analytics globally to a Gatsby site. Other common use cases would be inserting other SaaS trackers, global css style sheets, icon sets, etc. You should consider site performance when adding script and style tags globally to your head element as too many scripts can negatively affect performance.

// gatsby-ssr.js
const headComponents = [
export const onRenderBody = ({ setHeadComponents }) => {

Here is an example of adding a custom stylesheet on a per-page basis using react-helmet. In this example this we are loading the css stylesheet for LeafletJS which is something I only want to do on the specific pages that require it for performance reasons.

// map-page.js
import { Helmet } from "react-helmet"
const MapPage = () => {
return (
export default MapPage

← Previous Post

Illustrations by Diana Valeanu
© 2022 Eric Howey -

In the spirit of reconciliation, I acknowledge that I live, work and play on the traditional territories of the Blackfoot Confederacy (Siksika, Kainai, Piikani), the Tsuut’ina, the Îyâxe Nakoda Nations, the Métis Nation (Region 3), and all people who make their homes in the Treaty 7 region of Southern Alberta.