og-image-explorer

@elements/og-image-explorer

Open in Open in Tree

OG Image Explorer

12 routes across 2 categories

Docs

9

View 5 more

Documentation/docs

Brand Logos/docs/logos

Clerk/docs/clerk

Polar/docs/polar

Pages

3

Home/

Contributors/contributors

Sponsor/sponsor

Overview

A visual gallery to audit Open Graph images across all routes in your application. Catch broken or missing OG images before deployment by scanning your entire app's social sharing images in one view.

Installation

bunx shadcn@latest add @elements/og-image-explorer

Usage

import { OgImageExplorer } from "@/components/elements/devtools/og-image-explorer";

const routes = [
  { path: "/", title: "Home", ogImageUrl: "/opengraph-image.png" },
  { path: "/blog", title: "Blog", ogImageUrl: "/blog/opengraph-image.png" },
  { path: "/blog/post-1", title: "First Post", ogImageUrl: "/blog/post-1/opengraph-image.png" },
  { path: "/docs", title: "Documentation", ogImageUrl: "/docs/opengraph-image.png" },
];

export function OgAuditPage() {
  return <OgImageExplorer routes={routes} maxPerCategory={8} />;
}

Props

OgRoute Interface

interface OgRoute {
  path: string;       // Route path (e.g., "/blog/post-1")
  title?: string;     // Display title
  ogImageUrl: string; // Full URL or relative path to OG image
  category?: string;  // Optional category override
}

Features

Status Indicators

Each image card shows a colored border indicating load status:

• Green border - Image loaded successfully
• Red border - Image failed to load (404 or broken)
• Gray border - Image is loading

Auto-Grouping

Routes are automatically grouped by their first path segment:

• /blog/post-1 → "blog" category
• /docs/api → "docs" category
• / → "root" category

Override with the category prop on individual routes.

View More Pagination

Categories with more items than maxPerCategory show a "View more" button that expands to reveal all items.

Click to Inspect

Click any image card to open the full-size OG image in a new tab. Useful for checking image quality and dimensions.

Recommended Workflow

1. Create a dedicated route in your app (e.g., /dev/og-audit)
2. Configure all your routes with their OG image URLs
3. Scan the grid for red borders (broken images)
4. Click to inspect individual images
5. Fix issues before deploying

Route Discovery Script

Generate routes automatically from your Next.js app structure:

bun run scripts/generate-og-routes.ts
bun run scripts/generate-og-routes.ts --base-url https://your-site.com

The script scans:

• src/content/providers/*.mdx for provider pages
• src/content/components/**/*.mdx for component pages
• Extracts titles from MDX frontmatter
• Auto-assigns categories: pages for root, providers for provider index, provider slug for components

Example: Dogfooding tryelements.dev

This component audits OG images on tryelements.dev using auto-generated routes:

// Auto-generated by scripts/generate-og-routes.ts
const BASE_URL = "https://tryelements.dev";

const ROUTES = [
  { path: "/", title: "Home", category: "pages" },
  { path: "/docs", title: "Documentation", category: "providers" },
  { path: "/docs/clerk", title: "Clerk", category: "providers" },
  { path: "/docs/theme", title: "Theme", category: "providers" },
  { path: "/docs/theme/theme-switcher-dropdown", title: "Theme Switcher Dropdown", category: "theme" },
  // ... 25 routes total
].map((route) => ({
  ...route,
  ogImageUrl: `${BASE_URL}${route.path}/opengraph-image`,
}));

Example: Manual Routes

const routes = [
  { path: "/", title: "Home", ogImageUrl: "/opengraph-image.png" },
  { path: "/about", title: "About", ogImageUrl: "/about/opengraph-image.png" },

  // Dynamic routes from CMS
  ...blogPosts.map(post => ({
    path: `/blog/${post.slug}`,
    title: post.title,
    ogImageUrl: `/blog/${post.slug}/opengraph-image.png`,
  })),
];

Troubleshooting

Images show red border but work on the actual page?

Check that your OG image URLs are absolute URLs or properly served from your dev server. Relative paths like /opengraph-image.png need to resolve correctly in your dev environment.

Category detection not working as expected?

Use the category prop to override auto-detection:

{ path: "/special-page", title: "Special", ogImageUrl: "...", category: "marketing" }