Publish and Embed Storybook

Purpose and Scope

Publishing Storybook turns the local component workshop into a static web application that designers, product managers, developers, and other stakeholders can review without cloning the project or running a development server. The sharing flow has two phases: first build and host the Storybook somewhere publicly reachable, then link to or embed individual stories and documentation pages in other collaboration surfaces. This page focuses on the embed-facing contract that Storybook documents in the repository and uses the official publish guidance for the build step.

Sources: docs/sharing/embed.mdx

A published Storybook is especially useful when the team wants component examples to travel outside the codebase. Instead of describing a state in prose or screenshots, a writer can embed the real rendered story in a design note, blog post, documentation site, or stakeholder update. The repository documentation is explicit that embeds require the Storybook to be published and publicly accessible, because the receiving platform needs a URL it can load in an iframe or resolve through oEmbed.

Sources: docs/sharing/embed.mdx

Relevant Source Files

• docs/sharing/embed.mdx - Defines the user-facing embedding guide, including toolbar embeds, plain canvas embeds, docs-page embeds, oEmbed examples, iframe examples, and platform notes for Medium, Notion, and Ghost.

Publishing Workflow

The publishing workflow begins by building Storybook as a static web application. In a project configured with standard Storybook scripts, the official flow is to run the build command from the project root:

npm run build-storybook

That command produces a static Storybook output suitable for deployment to a web host. The exact hosting target can vary by team: a generic static hosting provider, an internal documentation site, a CI artifact server, or Chromatic. The important constraint for embedding is not the host vendor but the accessibility of the resulting URL. If the destination platform cannot fetch the published Storybook, the iframe or oEmbed preview will not load for readers.

Chromatic is called out in the docs as a publishing option with additional embed convenience. Storybook supports iframe embeds out of the box for any public Storybook URL, while Chromatic-published Storybooks can also be embedded into platforms that understand the oEmbed standard. Treat iframe embedding as the portable baseline and oEmbed as an integration path for services such as Medium and Notion that prefer pasting a URL over writing raw HTML.

Sources: docs/sharing/embed.mdx

Embed Modes

Storybook documents two common story embed modes. The first keeps the Storybook chrome available by using the published story URL and adding query options that make the embedded experience focused. This is useful when the reader may benefit from Storybook’s context but the embed still needs to fit into a surrounding document. The example uses path=/story/shadowboxcta--default, then adds full=1, shortcuts=false, and singleStory=true to tune the embedded view.

Sources: docs/sharing/embed.mdx

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/?path=/story/shadowboxcta--default&full=1&shortcuts=false&singleStory=true"
  width="800"
  height="260"
></iframe>

The second mode embeds the plain canvas without Storybook’s toolbar. The documented workflow is to click the “open canvas in new tab” icon in the top-right corner of Storybook, copy the canvas URL, and use that URL in the embed. Canvas URLs load through iframe.html, identify the story with an id query parameter, and set viewMode=story. This mode is better for product docs and external pages where the component itself should be the entire embedded experience.

Sources: docs/sharing/embed.mdx

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--default&viewMode=story&shortcuts=false&singleStory=true"
  width="800"
  height="200"
></iframe>

Embedding Documentation Pages

Storybook embeds are not limited to interactive component states. The same canvas-style URL shape can embed generated documentation pages by changing the target entry and view mode. The repository guide describes replacing viewMode=story with viewMode=docs and using the uniquely generated documentation entry for the story, such as shadowboxcta--docs. This allows a team to place full component documentation, examples, and usage guidance inside an external documentation system while preserving Storybook as the source of truth.

Sources: docs/sharing/embed.mdx

<iframe
  src="https://5ccbc373887ca40020446347-wtuhidckxo.chromatic.com/iframe.html?id=shadowboxcta--docs&viewMode=docs&shortcuts=false&singleStory=true"
  width="800"
  height="400"
></iframe>

When choosing between a story embed and a docs embed, decide what the reader needs to accomplish. A story embed is strongest when the page is explaining one concrete state, such as a default button, an empty list, or an error screen. A docs embed is stronger when the surrounding page needs a richer reference surface, including generated documentation and examples. In both cases, the embed remains coupled to the published Storybook URL, so update deployment and cache behavior matter for downstream consumers.

Sources: docs/sharing/embed.mdx

Platform Integration Notes

Different publishing platforms support external content differently, so Storybook’s docs recommend checking the destination service’s embed rules. Medium accepts a pasted Storybook URL and automatically resizes the embed to fit the story height, though embeds are non-interactive while editing and become interactive after publishing. Notion uses its /embed block, where the author pastes the story URL and can resize the result. Ghost supports raw iframe usage through an /html block, including manual width and height settings.

Sources: docs/sharing/embed.mdx

These platform examples show why it is helpful to keep both URL styles available. Some tools want a clean URL and handle the embedding mechanics themselves through oEmbed or custom preview handling. Other tools expect the author to provide complete iframe markup. For maintainable external documentation, prefer stable story IDs, publish after meaningful UI changes, and verify the final page as a reader rather than only checking the Storybook instance in isolation.

Sources: docs/sharing/embed.mdx

Compact Reference

Next Steps

After publishing, test the exact URL that stakeholders will receive, then test at least one iframe embed and one platform-native embed if your team uses services such as Notion, Medium, or Ghost. If the embed is for a component API reference, consider embedding the docs page rather than a single story. If it is for design review or release notes, embed the narrowest story state that communicates the change clearly. Related topics include documentation authoring, composition, design integrations, and CI publishing workflows.