Doc Blocks and Code Panel

Storybook documentation is composed from two complementary surfaces: authored documentation pages and generated source-aware displays. Doc blocks are reusable documentation building blocks that authors place in MDX pages or in docs page templates to show stories, controls, primary examples, prop tables, and source snippets. The Code panel is the canvas-side source display for an individual story. Together, these features help teams move from isolated component examples to readable, inspectable documentation without duplicating the same story code in a second documentation system.

Sources: docs/writing-docs/code-panel.mdx

Purpose and Scope

Use this page when you need to decide how Storybook should expose story source code to readers. The main distinction is location. Doc blocks are used inside documentation pages, especially MDX and Autodocs-style pages, where the author controls the surrounding explanation and layout. The Code panel appears while viewing a story in the canvas and is meant for quick inspection of the rendered story's source. The repository documentation states that the Code panel renders a story's source code in the canvas view, and that args defined in the story are substituted with their actual values in the output.

Sources: docs/writing-docs/code-panel.mdx

The Code panel is also the modern replacement for the old Storysource workflow. The docs explicitly call out that Storysource was discontinued in Storybook 9 and that Code Panel replaces it. That matters during upgrades because teams that previously relied on a separate addon for source inspection should now configure the built-in docs surface instead of searching for an addon-level migration. In practice, the replacement model is simpler: source display belongs under docs parameters, and the same generated snippet machinery is shared with the Source docs block and Autodocs pages.

Sources: docs/writing-docs/code-panel.mdx

Relevant Source Files

• docs/writing-docs/code-panel.mdx - Defines the public Code panel documentation page, including the Storysource replacement note, the canvas-source behavior, the enablement parameter, supported configuration levels, and the relationship to the Source docs block.

Core Primitives

The first primitive is a story. A story is an authored example of a component state, usually with args that describe input values. The Code panel reads that story-oriented representation and displays source code for the selected story in the canvas. Because args are substituted with their values, the output is intended to be closer to what a reader wants to copy or inspect than a raw template with unresolved story metadata. This makes Code panel most useful when a consumer asks, “How is the component invoked in this state?” rather than “How is the documentation page assembled?”

Sources: docs/writing-docs/code-panel.mdx

The second primitive is a docs parameter. Storybook parameters are hierarchical configuration values that can be applied globally, at the component level, or at the story level. The Code panel is enabled through the docs namespace by setting parameters.docs.codePanel to true. The documentation recommends doing this in the project preview file for most projects so that it applies to every story. If only selected components or examples should expose source inspection, the same setting can be moved down to the component or story scope.

Sources: docs/writing-docs/code-panel.mdx

The third primitive is the Source docs block. The Code panel renders the same snippet as the Source block, and the documentation says it reuses Source configuration parameters. This shared contract is important because customization is not split between unrelated APIs. If a team changes how source snippets are transformed, displayed, or controlled for documentation pages, the Code panel should be considered part of that same source-display family. Treat Source block configuration as the reference point for advanced tuning, and treat the Code panel flag as the canvas placement switch.

Sources: docs/writing-docs/code-panel.mdx

Execution Flow

A typical project-wide setup starts in the preview configuration file. The author enables the Code panel once, then restarts or refreshes Storybook and opens a story in the canvas. When the story is selected, Storybook can show the panel containing the rendered source snippet. The docs emphasize that the displayed snippet includes args replacement, so the resulting source reflects the current story values rather than merely echoing the story file's declared structure. That is especially useful for component libraries where props are the primary learning surface for consumers.

Sources: docs/writing-docs/code-panel.mdx

// .storybook/preview.ts
import type { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    docs: {
      codePanel: true,
    },
  },
};
 
export default preview;

For more selective rollout, configure the same parameter beside a component's stories or beside a single story export. Component-level enablement is useful when only certain components have polished, stable examples that should be advertised as copyable source. Story-level enablement is useful when one scenario is especially educational, such as a complex composition or a recommended integration path. The documentation explicitly allows component and story-level enablement, so teams do not have to choose between all-or-nothing global behavior and abandoning the feature.

Sources: docs/writing-docs/code-panel.mdx

// Button.stories.ts
const meta = {
  component: Button,
  parameters: {
    docs: {
      codePanel: true,
    },
  },
};
 
export default meta;
 
export const Primary = {
  args: {
    label: 'Save changes',
    variant: 'primary',
  },
};

System-to-Code Mapping

The implementation-facing map for this page is intentionally small because the requested source is a documentation entry rather than a TypeScript module. The public behavior is concentrated in the Code panel documentation file. Its frontmatter names the page, its opening callout defines the migration context from Storysource, the introductory paragraph defines what appears in the panel, the usage section defines the enabling parameter, and the configuration section connects Code panel output to the Source docs block. That arrangement mirrors the user journey: understand why the feature exists, enable it, then customize the source snippet through the shared Source configuration contract.

Sources: docs/writing-docs/code-panel.mdx

Configuration Reference

The key option is parameters.docs.codePanel. Set it to true to show the Code panel. The recommended default is project-wide configuration in .storybook/preview.*, because that gives every story a consistent source inspection affordance. Use component or story-level configuration when global source display is too broad, when only a subset of examples should be copyable, or when a documentation author wants to limit the panel to the examples that have been curated for external readers.

Sources: docs/writing-docs/code-panel.mdx

The customization surface is not a separate Code panel-specific object in the supplied documentation. Instead, Code panel output is described as the same snippet used by the Source docs block and Autodocs. That means source formatting and display decisions should be reasoned about as docs source-snippet configuration. A useful mental model is that Source controls the snippet and Code panel controls one place where that snippet appears. When diagnosing an unexpected source snippet, check the story args first, then check Source block parameters, then check whether the Code panel has been enabled at the intended scope.

Sources: docs/writing-docs/code-panel.mdx

Doc Blocks Relationship

Doc blocks are the author-facing composition layer for documentation pages. In MDX, blocks such as metadata, primary story display, controls, story embeds, and source-oriented blocks let authors combine narrative text with live examples. Autodocs can also use docs page templates that are assembled from blocks. The Code panel should not be confused with an MDX block that authors place directly in a page; it is a panel attached to the canvas story view. However, its source output is aligned with the Source block, so both surfaces can show consistent code for the same story.

When designing documentation, choose the surface based on the reader task. If a reader is learning the concept, an MDX page with doc blocks provides sequence, explanation, and examples in context. If a reader is already inspecting a component state, the Code panel gives immediate access to source without leaving the canvas. Strong Storybook documentation often uses both: an authored page explains the component contract and shows curated examples, while the Code panel lets readers inspect the exact invocation for any selected story.

Edge Cases and Practical Guidance

The most common surprise is that the displayed code is generated from the story and its args, not necessarily a byte-for-byte excerpt of the original story file. That is a feature for consumers because it resolves args into concrete values, but it can differ from what maintainers see in source control. Another common migration issue is expecting the old Storysource addon to remain the primary integration point. The repository documentation's callout points readers away from that path and toward the built-in Code panel configuration.

Sources: docs/writing-docs/code-panel.mdx

For teams with many packages or many framework renderers, prefer a global default only after confirming the generated snippets are useful across the whole catalog. Some stories are written as tests, edge cases, or internal fixtures; those may not produce source snippets that are appropriate for external consumers. In those situations, component or story-level enablement keeps the panel focused. Conversely, public design systems often benefit from global enablement because every story becomes a teaching artifact and consumers can copy the rendered invocation while browsing.

Sources: docs/writing-docs/code-panel.mdx

Next Steps

After enabling the Code panel, review a representative set of stories in the canvas and compare the generated snippets with the examples in your MDX or Autodocs pages. If the same story appears in both places, keep the source display consistent by tuning Source docs block configuration rather than inventing a separate convention. Then decide whether project-wide, component-level, or story-level enablement best matches your documentation quality bar. For broader documentation composition, read the MDX, Autodocs, and API Doc Blocks pages next; for source-display tuning, follow the Source docs block configuration path referenced by the Code panel documentation.

Sources: docs/writing-docs/code-panel.mdx