Storybook Open Graph Tags: Add OG Meta to Your Component Library Site

Storybook and OG tags

Storybook generates a static site that designers, developers, and stakeholders share constantly — "here's the Button component" links in Slack, PR review links on GitHub, design handoff URLs in Linear. Without OG tags, those links show a blank card.

Storybook doesn't have native per-story OG support, but you can add site-level OG defaults and per-component OG metadata using the .storybook/preview-head.htmlfile and manager customization.

Site-wide OG defaults in preview-head.html

Add default OG tags to all Storybook pages via .storybook/preview-head.html:

<!-- .storybook/preview-head.html -->
<meta property="og:title" content="Acme UI Component Library" />
<meta property="og:description" content="The official design system and component library for Acme products." />
<meta property="og:image" content="https://storybook.acme.com/og-default.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://storybook.acme.com" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@acme" />

Per-story OG metadata with a decorator

For per-story or per-component OG meta, use a decorator that injects tags dynamically:

// .storybook/preview.ts
import type { Preview } from "@storybook/react";

const preview: Preview = {
  decorators: [
    (Story, context) => {
      const storyName = context.story;
      const componentName = context.title;
      const ogTitle = `${componentName} — ${storyName} | Acme UI`;
      const ogDescription =
        context.parameters?.docs?.description?.story ||
        context.parameters?.docs?.description?.component ||
        "Acme UI component library";

      // Update OG meta tags for this story
      const updateMeta = (property: string, content: string) => {
        let el = document.querySelector(`meta[property="${property}"]`) as HTMLMetaElement;
        if (!el) {
          el = document.createElement("meta");
          el.setAttribute("property", property);
          document.head.appendChild(el);
        }
        el.content = content;
      };

      updateMeta("og:title", ogTitle);
      updateMeta("og:description", ogDescription);
      updateMeta(
        "og:url",
        `https://storybook.acme.com/?path=/story/${context.id}`
      );

      return <Story />;
    },
  ],
};

export default preview;

Custom OG image for your Storybook deploy

Create a branded OG image for your Storybook site to use as the default. Include:

• Your company/product logo
• Text: "[Product Name] Design System" or "Component Library"
• Brand colors matching your design system
• Subtitle: "Built with Storybook" (optional, adds credibility)

Place the image in .storybook/public/og-default.png (or your static assets folder) at 1200×630px.

Adding OG to a Next.js Storybook companion site

If you have a companion marketing/documentation site for your design system (e.g., built with Next.js), add proper OG metadata there:

// app/components/[slug]/page.tsx — design system component docs
export async function generateMetadata({
  params,
}: {
  params: { slug: string };
}): Promise<Metadata> {
  const component = await getComponent(params.slug);
  
  return {
    title: `${component.name} — Acme UI`,
    description: component.description,
    openGraph: {
      title: `${component.name} — Acme UI Component`,
      description: component.description,
      type: "website",
      images: [
        {
          url: `/api/og?component=${encodeURIComponent(component.name)}`,
          width: 1200,
          height: 630,
        },
      ],
    },
  };
}

Common Storybook OG issues

• Iframe crawling: Storybook renders stories inside iframes — crawlers may not see the iframe content. The preview-head.html approach adds tags to the iframe document, not the manager shell.
• SPA routing: Storybook uses hash-based routing, which isn't SEO/OG friendly. Story URLs (?path=/story/button--primary) may not unfurl cleanly on all platforms.
• Chromatic links: If sharing Chromatic review links, those have their own OG implementation.