How to Add OG Images to Gatsby — Complete Guide

Since Gatsby 4.19, the Gatsby Head API is the recommended way to manage document head tags. Export a Head function from any page component to add meta tags:

// src/pages/index.tsx
import * as React from "react";

export function Head() {
  const title = "My Gatsby Site";
  const description = "A blazing fast site built with Gatsby";
  const ogImage = `https://ogimg.xyz/api/og?${new URLSearchParams({
    title,
    description,
    template: "gradient",
  }).toString()}`;

  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <meta property="og:type" content="website" />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:image" content={ogImage} />
      <meta property="og:image:width" content="1200" />
      <meta property="og:image:height" content="630" />
      <meta name="twitter:card" content="summary_large_image" />
    </>
  );
}

export default function IndexPage() {
  return <main><h1>Welcome</h1></main>;
}

The Head API runs at build time, so the meta tags are baked into the static HTML — exactly what social media crawlers expect.

Gatsby's data layer uses GraphQL, which makes it easy to pull page data for dynamic OG images. Here's an example for MDX blog posts:

// src/pages/blog/{mdx.frontmatter__slug}.tsx
import * as React from "react";
import { graphql, PageProps } from "gatsby";

export function Head({ data }: PageProps<Queries.BlogPostQuery>) {
  const post = data.mdx!;
  const title = post.frontmatter!.title!;
  const description = post.frontmatter!.description || "";
  const ogImage = `https://ogimg.xyz/api/og?${new URLSearchParams({
    title,
    description,
    template: "blog",
    pattern: "dots",
  }).toString()}`;

  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <meta property="og:type" content="article" />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:image" content={ogImage} />
      <meta property="og:image:width" content="1200" />
      <meta property="og:image:height" content="630" />
      <meta name="twitter:card" content="summary_large_image" />
    </>
  );
}

export const query = graphql`
  query BlogPost($id: String!) {
    mdx(id: { eq: $id }) {
      frontmatter {
        title
        description
        date
      }
    }
  }
`;

export default function BlogPost({ data, children }: PageProps<Queries.BlogPostQuery>) {
  return (
    <article>
      <h1>{data.mdx!.frontmatter!.title}</h1>
      {children}
    </article>
  );
}

Every blog post now gets a unique OG image generated from its title and description. No manual image creation needed, and the images are generated on-demand — they don't increase your Gatsby build time.

If you're on a Gatsby version older than 4.19 or prefer React Helmet, install the plugin:

npm install gatsby-plugin-react-helmet react-helmet

Add it to your gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: ["gatsby-plugin-react-helmet"],
};

Then use Helmet in your components:

import React from "react";
import { Helmet } from "react-helmet";

function SEO({ title, description }) {
  const ogImage = `https://ogimg.xyz/api/og?${new URLSearchParams({
    title,
    description,
    template: "gradient",
  }).toString()}`;

  return (
    <Helmet>
      <title>{title}</title>
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:image" content={ogImage} />
      <meta property="og:image:width" content="1200" />
      <meta property="og:image:height" content="630" />
      <meta name="twitter:card" content="summary_large_image" />
    </Helmet>
  );
}

Note: The Gatsby Head API is the officially recommended approach going forward. If you're starting a new Gatsby project, use the Head API instead of React Helmet.

Gatsby generates static HTML at build time, so you can verify your OG tags before deploying:

1. Build locally: Run gatsby build and check the generated HTML in public/. Open any HTML file and search for og:image.
2. Gatsby develop: During development, view source in your browser (Ctrl+U) and confirm the meta tags are present.
3. Facebook Debugger: After deploying, paste your URL at developers.facebook.com/tools/debug to see how Facebook renders your link preview.
4. Twitter Card Validator: Use cards-dev.twitter.com/validator to test Twitter card rendering.

Common issues to watch for:

• Missing tags in view source: Make sure you're using the Head API or React Helmet — not a useEffect that injects tags client-side.
• Stale previews: Social platforms cache link previews aggressively. Use the Facebook Debugger's "Scrape Again" button to force a refresh.
• Relative URLs: The og:image value must be an absolute URL starting with https://.