Updated 2026-11-17
Astro Open Graph tags: one head component for every page
Astro puts nothing in your <head> that you don't write, so a page without Open Graph tags shares as a bare link on LinkedIn, Slack or X. Link previewers read the raw HTML and don't run JavaScript (why that matters); Astro renders the head to static HTML at build time, so tags written there are exactly what they see. This guide puts the tags in one component that every layout uses, with absolute URLs and a fallback image. Tested on Astro 7.4.
1. Set site in the config
Open Graph URLs must be absolute. Astro builds them from site (configuration reference):
// astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
site: "https://example.com",
});
Without it, Astro.site is undefined and the component below has nothing to build absolute URLs from.
2. A head component
Create src/components/SeoHead.astro:
---
interface Props {
title: string;
description?: string;
image?: string; // a path in public/ ("/og/pricing.png") or an absolute URL
imageAlt?: string;
type?: "website" | "article";
}
const { title, description, image = "/og-default.png", imageAlt, type = "website" } = Astro.props;
const siteName = "Example";
const url = new URL(Astro.url.pathname, Astro.site).href;
const imageUrl = new URL(image, Astro.site).href;
---
<title>{title}</title>
{description && <meta name="description" content={description} />}
<link rel="canonical" href={url} />
<meta property="og:type" content={type} />
<meta property="og:site_name" content={siteName} />
<meta property="og:title" content={title} />
{description && <meta property="og:description" content={description} />}
<meta property="og:url" content={url} />
<meta property="og:image" content={imageUrl} />
{imageAlt && <meta property="og:image:alt" content={imageAlt} />}
<meta name="twitter:card" content="summary_large_image" />
Notes:
- Attribute values are escaped by Astro, so a quote or
&in a title can't break the tag. Don't build the tags as a string and print it withset:html: that skips the escaping. new URL(image, Astro.site)turns a path into an absolute URL and leaves an absolute URL as it is. A relativeog:imageis the most common reason a card shows no image (more reasons).- The page URL is built from
Astro.url.pathnameonAstro.site, so it's the production address even in a preview build. If you setbase, the pathname already includes it. - X reads the Open Graph tags for title, description and image; it only needs
twitter:cardto show the large card. - The fallback image is
public/og-default.png, 1200×630, so a page without its own image still gets a card.
3. Use it in the layout
---
// src/layouts/Base.astro
import SeoHead from "../components/SeoHead.astro";
const { title, description, image, type } = Astro.props;
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<SeoHead title={title} description={description} image={image} type={type} />
</head>
<body><slot /></body>
</html>
For posts in a content collection, pass the entry's data from the page that renders it:
<Base title={post.data.title} description={post.data.description}
image={post.data.ogImage} type="article">
Remove any other <title> or og: tags from your layouts first. Two og:image tags on one page leave each network to pick one.
4. Images imported with astro:assets
If a post's image lives in src/ (an image() field in the collection schema), it has no fixed public path. Get one at build time with getImage and pass its src, which the component makes absolute (getImage):
---
import { getImage } from "astro:assets";
const og = post.data.cover
? await getImage({ src: post.data.cover, width: 1200, height: 630, format: "jpg" })
: undefined;
---
<Base title={post.data.title} description={post.data.description}
image={og?.src} type="article">
JPEG or PNG is the safe choice: not every previewer shows WebP or AVIF.
5. Check the build
List built pages with no og:image:
npx astro build && grep -rL --include='*.html' 'property="og:image"' dist
Then check a deployed page as previewers see it with the free SEO checker, which shows the LinkedIn, Slack and X cards from the raw HTML. The free site checker samples pages across a live site and lists which have no share image, no description or no structured data.
Common mistakes
- No
sitein the config, so image URLs come out relative or the build fails onnew URL. og:imagepointing at a file insrc/. Onlypublic/files andgetImageoutput exist at a fixed URL after the build.- One description on every page, from a default prop. A missing description is better than the same one repeated (why).
- Tags set from client-side scripts or a framework island. Previewers never run them.
Automating it with Headlark
The component prints what each page passes in, so every page still needs a title, description and image from somewhere. On a site with hundreds of pages, Headlark's build step for Astro runs after astro build and writes each page's title, description and Open Graph and X tags from its own content, adds JSON-LD and missing alt text, and keeps your canonical, robots and JSON-LD types as they are.
Try it
Try it free for 14 days on one site and up to 500 pages, no card needed. Add your site, copy its secret key, and your next build ships with SEO.