Meta block example with of prop
Example: import { Meta } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} />
Storybook · API · all subjects
doc-blocks
124 notes in this subject, read out of this brain and free to use. This is page 2 of 3.
Meta block example with title prop
Example: import { Meta } from '@storybook/addon-docs/blocks'; <Meta title="path/to/Introduction" />
Primary block usage example
import { Meta, Primary } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Primary /> This example shows how to import and use the Primary block in a docs file (ButtonDocs.mdx), passing CSF file exports to Meta and rendering Primary to display the first story.
Primary block displays first story
The Primary block displays the primary (first defined in the stories file) story, rendered in a Story block. It is typically rendered immediately under the title in a docs entry.
Primary block import path
Import Primary from '@storybook/addon-docs/blocks'.
Primary block 'of' prop
The Primary block accepts an 'of' prop of type CSF file exports. This prop specifies which CSF file is used to find the first story, which is then rendered by the block. Pass the full set of exports from the CSF file, not the default export.
Stories block renders full collection of stories
The Stories block renders the full collection of stories in a stories file. It is imported from '@storybook/addon-docs/blocks'.
Stories block example usage
Example of Stories block usage in a doc file: ```mdx title="ButtonDocs.mdx" import { Meta, Stories } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Stories /> ```
Stories block includePrimary prop
The includePrimary prop is of type boolean with a default value of true. It determines if the collection of stories includes the primary (first) story. Set includePrimary={false} to omit the primary story from the rendered collection. If the primary story is the only story in the file, the Stories block will render nothing when includePrimary is false.
Stories block title prop
The title prop is of type string with a default value of 'Stories'. It sets the heading content preceding the collection of stories.
Source block prop: type
The 'type' prop specifies how the source code is rendered. Valid values are: 'auto', 'code', or 'dynamic'. Default value is parameters.docs.source.type or 'auto'. 'auto' behaves same as 'dynamic' if the story's render function accepts args inputs and dynamic is supported by the framework, otherwise same as 'code'. 'code' renders the code prop value or static story source. 'dynamic' renders story source with dynamically updated arg values.
Source block import
The Source block is imported from '@storybook/addon-docs/blocks'.
Source block usage - render story source code
The Source block is used to render a snippet of source code directly in documentation. It can display either static source code from a story or dynamically updated code based on story arguments.
Source block prop: dark
The 'dark' prop accepts a boolean type and determines if the snippet is rendered in dark mode. Its default value is parameters.docs.source.dark. Light mode is only supported when the Source block is rendered independently; when rendered as part of a Canvas block or in autodocs, it always uses dark mode.
Source block prop: code
The 'code' prop accepts a string type and provides the source code to be rendered. Its default value is parameters.docs.source.code. If specified, it takes precedence and renders custom source instead of story source.
Source block prop: excludeDecorators
The 'excludeDecorators' prop accepts a boolean type and determines if decorators are rendered in the source code snippet. Its default value is parameters.docs.source.excludeDecorators. This prop is supported for Angular, React, HTML, and Web Components renderers.
Source block prop: language
The 'language' prop specifies the language used for syntax highlighting. Valid values are: 'jsextra', 'jsx', 'json', 'yml', 'md', 'bash', 'css', 'html', 'tsx', 'typescript', or 'graphql'. Default value is parameters.docs.source.language or 'jsx'.
Source block prop: of
The 'of' prop accepts a Story export and specifies which story's source is rendered.
Source block parameters namespace
Source block props derive default values from corresponding parameters in the 'parameters.docs.source' namespace. These parameters can be applied at story level, component (meta) level, or project level.
Source block React sortProps option
For React-based frameworks, dynamic snippets automatically sort props alphabetically by default. Set the 'sortProps' option to false to preserve the original order of props as defined in the story. This can be configured at project level in .storybook/preview.* file, component level in meta definition, or in the story itself.
Source block dynamic snippets requirement
Dynamic snippets will only work if the story uses args and the Story block for that story is rendered along with the Source block.
Source block prop: transform
The 'transform' prop accepts an async function with signature (code: string, storyContext: StoryContext) => string | Promise<string>. It dynamically transforms the source before rendering, based on the original source and story context. Its default value is parameters.docs.source.transform. If both 'code' and 'transform' are specified, 'transform' is ignored.
Story block with autoplay prop example
To enable autoplay for a story in the Story block, use: <Story of={ButtonStories.Basic} autoplay />. This is equivalent to setting parameters.docs.story.autoplay at the story, component, or project level.
Story block import
The Story block is imported from @storybook/addon-docs/blocks: import { Story } from '@storybook/addon-docs/blocks';
Story block renders stories in MDX
The Story block renders any stories from CSF files in the context of an MDX file with all annotations applied, including parameters, args, loaders, decorators, and play functions.
Story block autoplay property
The autoplay property is of type boolean with default value parameters.docs.story.autoplay. It determines whether a story's play function runs. By default, stories do not run play functions in docs mode. If a story uses mount in its play function, it will not render in docs unless autoplay is set to true.
Story block height property
The height property is of type string with default value parameters.docs.story.height. It sets a minimum height when rendering a story in an iframe or inline. This overrides parameters.docs.story.iframeHeight for iframes.
Story block inline property
The inline property is of type boolean with default value parameters.docs.story.inline or true for supported frameworks. It determines whether the story is rendered inline (in the same browser frame as other docs content) or in an iframe. Setting inline to false will prevent associated controls from updating the story within the documentation page.
Story block meta property
The meta property is of type CSF file exports. It specifies the CSF file to which the story is associated. You can render a story from a CSF file that you haven't attached to the MDX file by using the meta prop, passing the full set of exports from the CSF file (not the default export).
Story block of property
The of property is of type Story export. It specifies which story is rendered by the Story block. If no of is defined and the MDX file is attached, the primary (first) story will be rendered.
Story block basic usage example
To use the Story block, import it along with Meta from @storybook/addon-docs/blocks, import the CSF file as a namespace, attach it with Meta, then render a story: import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; <Meta of={ButtonStories} /> <Story of={ButtonStories.Primary} />
Story block with different CSF file example
To render a story from a different CSF file than the one attached via Meta, use the meta prop: import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; import * as HeaderStories from './Header.stories'; <Meta of={ButtonStories} /> <Story of={HeaderStories.LoggedIn} meta={HeaderStories} />
Subtitle block children prop
The Subtitle block accepts a children prop of type JSX.Element or string. This prop provides the content. The default value is parameters.docs.subtitle.
Subtitle block usage example
The Subtitle block can be used in MDX files like this: import { Subtitle } from '@storybook/addon-docs/blocks'; <Subtitle>This is the subtitle</Subtitle>
Subtitle block of prop
The Subtitle block accepts an 'of' prop that takes CSF file exports. This prop specifies which meta's subtitle is displayed.
Subtitle block import
The Subtitle block is imported from @storybook/addon-docs/blocks.
Title block children prop
The Title block accepts a 'children' prop of type JSX.Element or string that provides the content. If not specified, it falls back to the value of 'title' in an attached CSF file (or value derived from autotitle), trimmed to the last segment. For example, if the title value is 'path/to/components/Button', the default content displayed is 'Button'.
Title block import and basic usage
The Title block is imported from '@storybook/addon-docs/blocks' and serves as the primary heading for a docs entry, typically providing the component or page name. It is used with JSX syntax: <Title>This is the title</Title>
Title block 'of' prop
The Title block accepts an 'of' prop that takes CSF file exports as its type. This prop specifies which meta's title is displayed.
TableOfContents enabled via docs.toc parameter
The table of contents is enabled and configured via the docs.toc parameter rather than being added directly to MDX files. When enabled, it is automatically rendered alongside the page content by Storybook's docs container.
TableOfContents doc-block overview
The TableOfContents block renders a table of contents for the current documentation page, allowing users to navigate between sections quickly. It appears as a fixed sidebar on the right side of the documentation page and is hidden on smaller screens (below 768px).
Typeset doc-block example
Example usage of the Typeset doc-block: ```mdx title="Typography.mdx" import { Meta, Typeset } from '@storybook/addon-docs/blocks'; <Meta title="Typography" /> export const typography = { type: { primary: '"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif', }, weight: { regular: '400', bold: '700', extrabold: '800', black: '900', }, size: { s1: 12, s2: 14, s3: 16, m1: 20, m2: 24, m3: 28, l1: 32, l2: 40, l3: 48, }, }; export const SampleText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'; <Typeset fontSizes={[ Number(typography.size.s1), Number(typography.size.s2), Number(typography.size.s3), Number(typography.size.m1), Number(typography.size.m2), Number(typography.size.m3), Number(typography.size.l1), Number(typography.size.l2), Number(typography.size.l3), ]} fontWeight={typography.weight.black} sampleText={SampleText} fontFamily={typography.type.primary} /> ```
Typeset doc-block import
The Typeset block is imported from '@storybook/addon-docs/blocks' with the syntax: import { Typeset } from '@storybook/addon-docs/blocks';
Typeset doc-block purpose
The Typeset block helps document the fonts used throughout a project. It displays typography samples with configurable fonts, weights, and sizes.
Typeset fontFamily prop
The fontFamily prop accepts a string value and provides a font family to be displayed in the Typeset block.
Typeset fontSizes prop
The fontSizes prop accepts an array of strings or numbers and provides a list of available font sizes in pixels (px).
Typeset fontWeight prop
The fontWeight prop accepts a number value and specifies the weight of the font to be displayed.
Typeset sampleText prop
The sampleText prop accepts a string value and sets the text to be displayed in the Typeset block.
Unstyled block placement best practice
Due to how CSS inheritance works, it is best to always add the Unstyled block to the root of your MDX, and not nested into other elements. Nesting the Unstyled block inside other elements will cause some Storybook styles like color to be inherited into child components because they are applied to the root div.
Unstyled block import
The Unstyled block is imported from '@storybook/addon-docs/blocks'. Import statement: import { Unstyled } from '@storybook/addon-docs/blocks';
Unstyled block example in MDX
Example showing Unstyled block usage in MDX: ```mdx import { Meta, Unstyled } from '@storybook/addon-docs/blocks'; import { Header } from './Header.tsx'; <Meta title="Unstyled" /> > This block quote will be styled ... and so will this paragraph. <Unstyled> > This block quote will not be styled ... neither will this paragraph, nor the following component (which contains an <h1>): <Header /> </Unstyled> ```
Unstyled block purpose
The Unstyled block is a special block that disables Storybook's default styling in MDX docs wherever it is added. Most elements like h1 and p have default styles applied to ensure docs look good, but wrapping content with the Unstyled block removes these default styles.
Unstyled children prop
The Unstyled block accepts a 'children' prop of type React.ReactNode. This prop provides the content to which you do not want to apply default docs styles.
Unstyled block with imported components
The Story and Canvas blocks are already unstyled, so there is no need to wrap those in the Unstyled block. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block.
Doc Blocks documentation location
Doc Blocks documentation is found in the Storybook API reference at the Doc Blocks page, which is ordered fifth in the sidebar navigation.
Doc blocks purpose
Storybook offers several doc blocks to help document your components and other aspects of your project.
useOf return type for component
When useOf returns a component, it returns { type: 'component', component: Component, projectAnnotations: NormalizedProjectAnnotations }. The component is returned along with project annotations but no meta or story annotations. The hook behaves like an unknown type since it is often impossible to determine if a component is passed in or any other object.
useOf hook purpose and usage
The useOf hook allows custom doc blocks to interface with annotations from Storybook by accepting a module export of a story, meta, or component and returning its annotated form with applied parameters, args, loaders, decorators, and play function. Most existing blocks like Description and Canvas use useOf under the hood.
Custom doc block using useOf example
Here is an example custom block that displays the story name or title: ```jsx import { useOf } from '@storybook/addon-docs/blocks'; export const StoryName = ({ of }) => { const resolvedOf = useOf(of || 'story', ['story', 'meta']); switch (resolvedOf.type) { case 'story': { return <h1>{resolvedOf.story.name}</h1>; } case 'meta': { return <h1>{resolvedOf.preparedMeta.title}</h1>; } } return null; }; ``` When used with <StoryName of={ButtonStories.Secondary} />, it renders the story name. When used as <StoryName />, it defaults to the primary story. When used with <StoryName of={ButtonStories} />, it renders the meta title.
useOf moduleExportOrType parameter
The moduleExportOrType parameter (required) accepts a ModuleExport | 'story' | 'meta' | 'component'. It provides the story export, meta export, component export, or CSF file exports from which annotations are obtained. In attached doc mode, passing a string ('story', 'meta', or 'component') returns the primary (first) item; in unattached mode this results in an error. The pattern useOf(props.of || 'story') is common to fall back to the primary story if no of prop is defined.