Cookie Compliance Agent Manual
All pages and this page's sections

Add a cookie consent banner to a Gatsby site

Cookbook · platform Last verified View raw markdown (for agents)

In short: paste the live snippet as the first two entries of setHeadComponents([...]) in gatsby-ssr.js, or as the first thing in <head> of a custom src/html.js. Place it above your analytics entry.

Confirmed on a Gatsby site: with setHeadComponents (snippet first), the banner tags are the first scripts in the built page's <head>.

You need #

Where it goes #

  1. Copy the live snippet (see above).

  2. In gatsby-ssr.js, put the two banner tags first in the array you pass to setHeadComponents:

    const React = require("react")

exports.onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    // Cookie Compliance: first entries (use the live snippet's values)
    <script key="hu-options" dangerouslySetInnerHTML={{ __html:
      'var huOptions = { "appID": "YOUR_APP_ID", "currentLanguage": "en", "blocking": true, "globalCookie": false };' }} />,
    <script key="hu-banner" src="https://cdn.hu-manity.co/v2/hu-banner.min.js"
      type="text/javascript" charSet="utf-8" />,
    // your existing tags stay after them
    <script key="ga" async src="https://www.googletagmanager.com/gtag/js?id=G-XXXX" />,
  ])
}

    Gatsby writes its own meta tags first and then your array, so the snippet is the first script in <head>. Keep the banner tags synchronous (no async or defer).

  3. Alternative: eject the HTML shell (copy node_modules/gatsby/cache-dir/default-html.js to src/html.js) and put the two script tags as the first thing inside <head>.

  4. Run gatsby build.

Use setHeadComponents (not setPostBodyComponents) and keep the banner entries first in the array; Gatsby keeps array order.

What the order controls #

The banner holds recognised trackers that load after it until the visitor chooses, in regions whose rule requires consent first. A script placed above the snippet runs straight away, and a script you mark data-hu-category="1" is treated as essential. What runs before consent is your decision, so keep analytics and pixels below the snippet.

Confirm the result #

Build or render the site, then view the page source of the output (not the browser's Elements panel): the huOptions script and hu-banner.min.js are the first two <script> tags in <head> of public/index.html, with no async or defer, and your analytics tag comes after them.

Then run the browser checks in plain-html in a private window (banner shows, no tracking cookies before the visitor chooses in a region whose rule requires consent first, trackers start after Allow) and, for the full procedure, verify-install. Test from a region your strictest rule covers (for example the EU), or confirm region rules are off.

Gotchas #

More help #