How to Add Custom OG Images to Your Gatsby Site
Gatsby has gone through several approaches to head management over the years. If you are on Gatsby 5, you use the built-in Head API. On older versions, gatsby-plugin-react-helmet handles it. Either way, the goal is the same: every page should have a unique og:image tag with an absolute URL. Here is how to get there.
Gatsby 5: export a Head component from your page
Gatsby 5 introduced a built-in Head API. From any page file, export a named `Head` component and put your meta tags inside it. For OG images, return `<meta property="og:image" content={data.post.ogImageUrl} />` using data from the page's GraphQL query. The Head component receives the same `data` prop as the page component, so any field you query is available. This approach requires no plugin and is fully server-rendered, meaning crawlers see the tags without JavaScript.
Older Gatsby: gatsby-plugin-react-helmet
If your project uses Gatsby 4 or earlier, `gatsby-plugin-react-helmet` combined with the `react-helmet` package is the standard pattern. Create an SEO component that wraps `<Helmet>` and accepts an `ogImage` prop. Pass the URL through your page templates using GraphQL query results. Most Gatsby starters ship with this already set up. You only need to pass the correct image URL into the SEO component from each page or template.
Use siteMetadata as a fallback in gatsby-config
In `gatsby-config.js`, define a `siteMetadata` block with a `defaultOgImage` field pointing to a site-wide fallback image URL. Your SEO component can query this via the `site.siteMetadata` GraphQL node and use it whenever a specific page does not supply its own OG image. This ensures no page is ever missing a social card, even if you forget to set one explicitly.
StaticImage is not the right tool for OG images
`StaticImage` from `gatsby-plugin-image` optimizes images for rendering in the browser, not for OG meta tags. For OG images you need a hosted URL string, not a React component. Upload your generated OG images to your CDN or Cloudflare R2, then reference them by URL in your meta tags. You can store the URL in your CMS or Markdown frontmatter and pull it into your GraphQL query alongside the post content.
Generate your OG image in seconds
Paste a title, pick a brand color, and get production-ready social cards for every platform — with framework-specific meta tag snippets included.
Generate an OG image for your Gatsby site