DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan Now×
FREEDOM251

Freedom251 › Blog › Gatsby

How to Add Open Graph Images to Pages in a Gatsby Site

By Freedom251 Team · · 6 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Export a named Head function from the Gatsby page or page template and add an og:image meta tag whose content is the image’s absolute, publicly deployed URL. For a site-wide preview image, put the file in static and build its URL from your production site origin. Generate images during the build only when individual pages need their own artwork or title cards.

Check that your Gatsby version supports the Head API

Gatsby’s built-in Head API is available from [email protected]. Check the Gatsby version installed in your project before using the examples below. Head must be a named export from a page or page template—including a template used with createPage—not an export from an ordinary reusable component.

As an Amazon Associate I earn from qualifying purchases.

Gatsby renders Head tags into the page’s generated static HTML. A page’s Head export can access its GraphQL data and pageContext, so it can use either site-wide defaults or page-specific values.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Add one static image to a page

For a shared preview image, add the file to Gatsby’s static folder. For example, static/social/default-share.png is served at /social/default-share.png. Set the production origin in siteMetadata.siteUrl, then construct the absolute image URL in the page’s Head export.

// gatsby-config.js
module.exports = {
  siteMetadata: {
    siteUrl: "https://www.example.com",
  },
};
// src/pages/about.js
export function Head() {
  const siteUrl = "https://www.example.com";
  const imageUrl = `${siteUrl}/social/default-share.png`;

  return (
    <>
      <meta property="og:image" content={imageUrl} />
    </>
  );
}

Replace the example origin with the deployed site’s origin and make sure the path and extension match the actual file in static. The image URL should be absolute rather than a relative path, so the tag points to the intended public location when a page is shared.

Use page data with a site-wide fallback

If a content page has its own share-image path, use its GraphQL result or page context to supply that value. Keep a fallback so pages without an override do not render an undefined URL. Gatsby’s SEO guide recommends keeping stable site information in siteMetadata and using siteUrl to construct absolute metadata URLs.

export function Head({ data }) {
  const siteUrl = "https://www.example.com";
  const imagePath = data?.article?.shareImage || "/social/default-share.png";
  const imageUrl = new URL(imagePath, siteUrl).href;

  return <meta property="og:image" content={imageUrl} />;
}

This is an illustrative pattern: adapt data?.article?.shareImage to the actual shape of the page query, and ensure the resulting path identifies a publicly served image. A reusable SEO component can centralize metadata logic, but the page or template still needs to export Head for Gatsby to use it.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Generate a separate image for each page

When each article needs a title card or other page-specific artwork, a community plugin can generate images as Gatsby creates pages. The documented workflow for the dynamic Open Graph image plugin is:

  1. Add the plugin to gatsby-config.js and confirm its compatibility with the Gatsby version used by the site.
  2. In gatsby-node.js, call createOpenGraphImage() while creating each page. Supply the React component and page data used to compose the image.
  3. Pass the generated image metadata in that page’s pageContext. The plugin requires an id in the context to distinguish generated images.
  4. In the page template’s named Head export, read ogImage.imagePath from pageContext, make it an absolute URL using the deployed site origin, and use it as the value of og:image.
  5. Inspect the generated file and page HTML after the build. If sitemap tooling would enumerate the generated image directory, exclude it where appropriate.

The plugin documents a default canvas size of 1200 × 630 pixels. Treat that as the plugin’s documented default, not as a universal requirement for every social platform. Check the image dimensions and any platform-specific requirements relevant to your site separately.

A related gatsby-plugin-open-graph-images entry also documents build-time image generation and a 1200 × 630 default. Its example repeats the og:image:width property where separate dimensions appear to be intended; do not copy that apparent typo. The dynamic plugin’s sample for dimension tags also repeats the width property. If you add dimensions, use the correct property names and the actual generated image’s values.

Choose static or generated images

Approach Best fit Data flow Build and maintenance considerations
Static file One default image or a small set of manually prepared images Use a known public path and combine it with the production site origin. No image-generation plugin is needed. The referenced file must exist in static.
Build-generated image Many pages whose images include page-specific content, such as a title Generate an image during page creation, pass its metadata through pageContext, then use its path in Head. Add and maintain a community plugin; check compatibility and generated output. Sitemap tooling may need to exclude the output directory.

These workflows document different implementation paths; the plugin documentation does not establish a quantitative performance or maintenance-cost comparison.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Verify the deployed metadata and image

  1. Build the site and inspect the generated HTML for the page. Confirm that it contains the intended <meta property="og:image" ...> tag and that its content is the final absolute URL.
  2. Open that image URL from the deployed site and confirm that the expected image is served without authentication. Gatsby’s metadata guidance supports constructing absolute URLs for the deployed site; checking public accessibility is an implementation check.
  3. For generated images, confirm the expected file was written and that the page’s pageContext supplied the right path.
  4. If using a sitemap plugin, check whether it includes the generated image directory and exclude that directory if needed.

Gatsby documents Head tags in generated HTML and tag deduplication by id; it does not establish how a particular social service refreshes cached previews. Do not assume changing the HTML immediately refreshes an already cached share preview.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshoot common implementation errors

  • No Open Graph tag appears: Confirm the installed Gatsby version is 4.19.0 or later and that Head is a named export from the page or page template, not just a reusable component.
  • The image URL is relative or points at the wrong origin: Build it from the production siteUrl, and verify that the configured origin and image path match the deployed site.
  • The URL returns no image: Check that the referenced static file exists with the same name and extension, or that the generation step wrote the expected output. Confirm the deployed URL is publicly reachable.
  • A page-specific image is missing: Check that page creation passes the generated image metadata through pageContext, and that the template reads the same property path.
  • Generated images appear in the sitemap: Configure the sitemap tooling to exclude the generated output directory if it would otherwise enumerate that directory.
  • Dimension metadata is wrong: Do not copy the repeated width-property examples noted above. Emit the appropriate width and height properties using the dimensions of the actual image.

Or skip the browser setup

You can use a screenshot to visually inspect the deployed page, but a screenshot is not a substitute for checking the generated HTML and image URL. With ScreenshotNeo, one GET request returns a screenshot or PDF. Its capture flow accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Only clean shots are billed: bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://www.example.com/about -o shot.webp

Replace the example target with your deployed Gatsby page. See the ScreenshotNeo API documentation for request options. ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Sign up for free.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

GatsbyOpen GraphSEOWeb development

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.