How to Use og:image:alt for Accessible Link Previews

To describe an Open Graph preview image, add an og:image:alt meta property in the document <head>, alongside og:image. Write a concise description of the meaningful visual content. It describes the image; it is not a caption, preview title, or promotional message.

The Open Graph Protocol recommends specifying og:image:alt whenever a page specifies og:image. The tag is good metadata practice, but it does not guarantee that every sharing platform will show the description or expose it to assistive technology. Open Graph Protocol

1. Add the image and description to the document head

Use an absolute URL for the image and make the description match the image actually selected for that page. This complete example includes the common Open Graph fields and the image description:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta property="og:title" content="Spring cycling routes">
  <meta property="og:description" content="Three scenic routes for a weekend ride.">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/routes">
  <meta property="og:image" content="https://example.com/images/cycling-route.jpg">
  <meta property="og:image:alt" content="A red bicycle leaning against a brick wall beside a tree-lined road">
  <title>Spring cycling routes</title>
</head>
<body>
  <h1>Spring cycling routes</h1>
</body>
</html>

The example URLs and image are illustrative. Replace them with the real canonical page URL, image URL, and a description that accurately represents the chosen image. The protocol defines og:image:alt as “A description of what is in the image (not a caption).” Its example is “A shiny red apple with a bite taken out.”

2. Write useful image alt metadata

Describe what a person would need to know about the visual, in plain and concise language. Keep the description tied to the image itself:

• Describe the meaningful content: “A red bicycle leaning against a brick wall beside a tree-lined road.”
• Do not use it as link copy: avoid repeating the page title, a call to action, or promotional wording that does not describe the image.
• Keep it accurate when images vary: if the Open Graph image changes by page, locale, or content variant, select a matching description too.
• Do not describe irrelevant decoration: focus on the visual information the image contributes to the preview.

The first two recommendations follow the protocol’s definition and example. Matching descriptions to page-specific images is practical guidance inferred from the field’s purpose.

3. Render the metadata where preview crawlers can find it

Put the properties in the HTML document head. If your site uses a framework, CMS, or server-side template, set them in the page metadata that produces the response HTML. Check the rendered document, not only the component configuration: the final HTML should contain both properties and the correct values.

For pages with a shared layout, make the image URL and alt description page data so they can change together. Keep one source of truth for each page’s selected preview image and its description; this reduces mismatches when editorial images are updated.

4. Understand what the tag does—and what it does not promise

og:image:alt supplies a description associated with the Open Graph image. It is separate from the preview’s title and description, and it is not a guarantee that a platform will make the image description available to people.

Apple documents that websites can use Open Graph metadata to provide images and meaningful captions in Messages previews. That guidance does not specifically say how Messages handles og:image:alt. The available sources do not establish a current platform-by-platform support matrix or guarantee screen-reader announcements. Do not treat this one property as proof that a link preview is accessible everywhere.

5. Verify the page and the image description

1. Fetch the page and inspect the returned HTML head for og:image and og:image:alt.
2. Confirm that the image URL is absolute, reachable, and the image intended for that page.
3. Compare the description with the actual image. Update both together whenever the image changes.
4. Check the rendered preview in the sharing destinations that matter to your audience. Platform behavior can differ.
5. Where assistive-technology behavior matters, evaluate the actual destination and its preview experience; the metadata alone cannot establish what users will hear or see.

Open Graph data can contribute to rich link previews. Apple describes using it to provide images and meaningful captions in Messages previews, but that is not evidence of a universal treatment for og:image:alt. Apple Developer Documentation: Create rich previews for Messages

6. Troubleshoot common problems

Symptom	Likely cause	What to check or fix
The preview has an image but no visible description	The platform may not expose og:image:alt in its preview UI, or its behavior may differ.	Confirm the property is present in the response HTML. Do not assume the tag guarantees a visible or spoken description.
The metadata is missing from the page source	The property was added only in client-side code or to a template that does not render for this route.	Inspect the HTML returned for the actual URL and configure the page head output so the properties appear there.
The description does not match the preview image	The image was changed without updating its associated description, or page and locale metadata are out of sync.	Derive both values from the same page or locale data and verify the selected image.
The preview uses a different image than expected	The page’s selected og:image value may not be the intended asset.	Inspect the rendered og:image URL, confirm it points to the intended absolute URL, and then make its alt description match.
The description reads like a caption or advertisement	The field was written as link copy instead of image content.	Rewrite it to describe the meaningful visual content, following the protocol’s image-description definition.

7. Capture a preview image when you need to inspect one

If you need a visual review of a page’s rendered appearance, a browser screenshot can help you inspect the selected preview artwork or surrounding page. A screenshot does not verify how a sharing platform interprets og:image:alt; inspect the page metadata and the actual destination behavior separately.

DIY browser capture with Playwright

This runnable Node.js example captures a page screenshot with Playwright. It is for visual inspection; it does not validate social-platform support for the metadata.

npm install playwright
npx playwright install chromium

// save as capture.mjs
import { chromium } from 'playwright';

const url = process.argv[2] ?? 'https://example.com/routes';
const browser = await chromium.launch({ headless: true });
try {
  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
  const response = await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
  if (!response || !response.ok()) {
    throw new Error(`Page request failed: ${response?.status() ?? 'no response'}`);
  }
  await page.screenshot({ path: 'page.png', fullPage: true });
  console.log(`Saved page.png for ${url}`);
} finally {
  await browser.close();
}

node capture.mjs https://example.com/routes

For a quick HTML check without a browser, use cURL and inspect the response:

curl -L --fail --show-error https://example.com/routes

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. One GET request returns an image or PDF. For example, request a WebP screenshot of the page you are reviewing:

ScreenshotNeo API documentation

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com/routes"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/routes' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. A screenshot helps with visual inspection; it does not determine whether a platform exposes the alt description.

Sign up for ScreenshotNeo’s free plan.

8. Performance, reliability, and maintenance

og:image:alt is a small piece of head metadata. Keep it with the image metadata in your page-generation path so it is rendered consistently. The main reliability concern for this property is content accuracy: stale or mismatched descriptions undermine its purpose. Verify the generated head after changes to image selection, localization, or templates.

Do not build accessibility claims around presumed behavior by a particular sharing client unless you have verified that client. The cited protocol gives the property definition and recommendation; the cited Apple guidance covers Open Graph metadata in Messages generally, not this property’s exact treatment.

FAQ

Is og:image:alt the same as the HTML alt attribute?

No. It is an Open Graph meta property in the document head, associated with og:image. The sources here define its Open Graph role and do not claim that it replaces an image’s HTML alternative text.

Should every page with og:image include it?

The Open Graph Protocol says a page specifying og:image should also specify og:image:alt.

Does it make every social preview accessible?

No universal outcome is established by the available sources. The property provides the description, while each platform determines whether and how it is exposed.

Should the field repeat the page title?

Only if those words also accurately describe the image. Its purpose is to describe the image, not to provide a second title or caption.