Show code blocks by default in preview.js
To display code blocks open by default, add to preview.js: export const parameters = { docs: { canvas: { sourceState: 'shown' } } };
Storybook · Setup · all subjects
addons/docs
57 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
DocsPage supports all major Storybook frameworks
DocsPage supports React, Vue 3, Angular, and many other frameworks that Storybook supports, generating framework-agnostic documentation that can be used as a standalone docs site.
DocsPage is successor to addon-info
DocsPage replaces the deprecated addon-info addon, providing similar sensible defaults for documentation while bringing improvements in framework support, documentation quality, configuration options, and MDX integration.
DocsPage is the default zero-config documentation
When Storybook Docs is installed, DocsPage is automatically provided as the default documentation for all stories without requiring additional configuration. It aggregates stories, text descriptions, docgen comments, props tables, and code examples into a single page for each component.
Remix DocsPage using doc blocks
DocsPage can be rebuilt using individual doc blocks like Title, Subtitle, Description, Primary, ArgsTable, and Stories. Set docs.page to a function that returns JSX containing these blocks in any order, allowing customization while keeping auto-generated content.
Inline stories vs iframe stories in DocsPage
By default, stories render within an <iframe> element for framework isolation. The docs configuration provides inlineStories and prepareForInline options to render stories inline without iframes. Setting inlineStories to true removes the iframe, but requires prepareForInline to transform framework-specific story content into React-renderable form.
Vue inline stories default configuration
For @storybook/vue, inline stories are configured by default using @egoist/vue-to-react. The prepareForInline function transforms Vue story functions into React components: const Story = toReact(storyFn()); return <Story {...args} />;
Control code block visibility in DocsPage
By default, code blocks in DocsPage are collapsed and require clicking 'Show code' to reveal. Set docs.canvas.sourceState to 'shown' in preview.js to display all code blocks open by default.
Default iframe height in Docs is 60px
In the common setup, Storybook Docs renders stories inside iframes with a default height of 60px.
MDX Story component example
MDX files can be created using Meta, Story, and ArgsTable components from @storybook/addon-docs. Example: import { Meta, Story, ArgsTable } from '@storybook/addon-docs'; <Meta title='App Component' /> # App Component Some **markdown** description, or whatever you want. <Story name='basic' height='400px'>{() => { return { ... }; // should match the typical story format for your framework }}</Story>
MDX peer dependency on React
Docs has a peer dependency on react. If you want to write stories in MDX, you may need to add react as a dependency by running yarn add -D react.
Props table setup requires ember-cli-storybook addon
Getting Props tables for Ember components requires the @storybook/ember-cli-storybook addon, which extracts documentation comments from component source files. This addon should already be installed with Storybook for Ember.
Ember component documentation comment generation
For details on documenting Ember components with documentation comments, refer to the ember-cli-addon-docs-yuidoc addon documentation at https://github.com/ember-learn/ember-cli-addon-docs-yuidoc#documenting-components.
MDX example for Ember component documentation
Example MDX file for Ember Storybook: import { Meta, Story, ArgsTable } from '@storybook/addon-docs'; import { hbs } from 'ember-cli-htmlbars'; <Meta title='App Component' component='AppComponent' /> # App Component Some **markdown** description, or whatever you want. <Story name='basic' height='400px'>{{ template: hbs`<AppComponent @title={{title}} />`, context: { title: "Title" } }}</Story> ## ArgsTable <ArgsTable of='AppComponent' />
MDX peer dependency on React for Ember
To write Ember stories in MDX format, Docs has a peer dependency on react. Install it with: yarn add -D react
Set component field in Ember story metadata
When using Props tables with Ember, fill in the component field in story metadata with a string matching the @class name used in source comments: export default { title: 'App Component', component: 'AppComponent' };
ember-cli-storybook generates documentation JSON
When ember-cli-storybook addon docs integration is enabled, running the ember-cli server generates a JSON documentation file at /storybook-docgen/index.json. This file is regenerated every time component files are saved.
DocsPage automatically generated for Ember stories
When @storybook/addon-docs is installed, DocsPage documentation is automatically generated for all Ember stories and is available in the Docs tab of the Storybook UI.
Configure MDX file loading in main.js
To load MDX files for documentation, update .storybook/main.js stories configuration to include MDX files. Example: stories: ['../src/stories/**/*.stories.@(js|mdx)']
MDX example with Storybook React components
Example MDX file structure for React documentation: import { Meta, Story, ArgsTable } from '@storybook/addon-docs'; import { Button } from './Button'; <Meta title='Button' component={Button} /> # Button Some **markdown** description, or whatever you want. <Story name='basic' height='400px'> <Button>Label</Button> </Story> ## ArgsTable <ArgsTable of={Button} />
React stories render inline by default
Storybook Docs renders all React stories inline by default.
Configure component field for Props tables
To show props tables for your components, fill in the component field in your story metadata. For example: export default { title: 'Button', component: Button };
Props tables generation for React
Storybook Docs automatically generates Props tables for React components based on either PropTypes or TypeScript types.
DocsPage automatically available after addon-docs installation
When you install addon-docs, basic DocsPage documentation is automatically generated for all stories and available in the Docs tab of the Storybook UI.
MDX documentation components for React
MDX allows documenting React components in Markdown and embedding documentation components such as stories and props tables inline using imports like: import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
Configure MDX files in stories glob pattern
To enable MDX files in Vue Storybook, update the stories glob pattern in .storybook/main.js to include .mdx files, for example: stories: ['../src/stories/**/*.stories.@(js|mdx)']
Vue addon-docs uses vue-docgen-loader
Docs for Vue relies on vue-docgen-loader to extract component information. It supports props, events, and slots as first class prop types.
MDX support in Vue Storybook requires React
To write stories in MDX for Vue projects, React must be installed as a peer dependency. Install it with yarn add -D react.
Props tables for Vue support props, events, and slots
Storybook Docs for Vue uses vue-docgen-loader to generate props tables. It supports props, events, and slots as first class prop types.
MDX requires react as peer dependency for Vue 3
Storybook Docs has peer dependencies on react. If you want to write Vue 3 stories in MDX, you may need to add react as a dependency using yarn add -D react.
Vue 3 stories render inline in Docs by default
Storybook Docs renders all Vue 3 stories inline by default.
Configure iframe rendering for Vue 3 stories in Docs
To render Vue 3 stories in an iframe instead of inline, use the docs.story.inline parameter set to false. The default iframe height is 60px, configurable using the docs.story.iframeHeight parameter. To apply this to all stories, update .storybook/preview.js: export const parameters = { docs: { story: { inline: false } } };
MDX example for Vue 3 component documentation
Example MDX file for Vue 3: import { Meta, Story, ArgsTable } from '@storybook/addon-docs'; import { InfoButton } from './InfoButton.vue'; <Meta title='InfoButton' component={InfoButton} /> # InfoButton Some **markdown** description, or whatever you want. <Story name='basic' height='400px'>{{ components: { InfoButton }, template: '<info-button label="I\'m a button!"/>' }}</Story> ## ArgsTable <ArgsTable of={InfoButton} />
DocsPage auto-generated for Vue 3 stories
When the addon-docs is installed for Vue 3, basic DocsPage documentation is automatically generated for all stories and is available in the Docs tab of the Storybook UI.
Props tables require component field in story metadata
To get Props tables for Vue components in Storybook Docs, you must fill in the component field in your story metadata. Example: export default { title: 'InfoButton', component: InfoButton };
How to run story tests
Run the story testing tool after every component or story change. This is the only way to run story tests and should never be replaced by running package.json test scripts like npm run test:stories.
Story testing workflow and best practices
Run story tests after every component or story change, including creating, modifying, or refactoring components, stories, or their dependencies. The workflow is: make your change, run story tests with related stories for focused feedback, analyze and fix failures, then repeat until all tests pass. Do not skip tests, ignore failures, or move on with failing tests.
Focused vs full-suite story test runs
Prefer focused runs by providing specific stories during development to validate changed parts quickly. Run all tests by omitting the stories input before final handoff, after broad or refactor changes, or when impact is unclear and project-wide verification is needed.
Pass full context to play function when invoking from another story
When invoking the play function from another story, pass the full context as an argument to it. The context that Storybook provides to the play function contains internal functionality necessary for interactions to work correctly.
Incorrect: Calling play function without context
Do not call another story's play function without passing any context argument. For example, await MyOtherStory.play() without arguments will not work correctly.
Incorrect: Calling play function with only canvasElement
Do not call another story's play function by passing only the canvasElement property. For example, await MyOtherStory.play({ canvasElement }) is incomplete because the context needs the full context object, not just one property.
Correct: Pass full context to play function invocation
The correct way to invoke another story's play function is to pass the full context object: await MyOtherStory.play(context).
context-in-play-function ESLint rule included in configurations
The context-in-play-function ESLint rule is included in these configurations: recommended, flat/recommended, addon-interactions, and flat/addon-interactions.
Do not apply context-in-play-function rule to test files
The context-in-play-function ESLint rule should not be applied in test files. Ensure Storybook rules are defined only for story files.
DocsPage props table with controls setup
In DocsPage, to display controls in the props table, write your story to consume args. The auto-generated props table will display controls in the right-most column. Example: export const WithControls = (args) => <MyComponent {...args} />;
ArgsTable has built-in Controls for editing stories dynamically
Starting in Storybook 6.0, the ArgsTable block has built-in Controls (formerly known as 'knobs') for editing stories dynamically. Controls appear automatically in the props table when your story accepts Storybook Args as its input.
MDX ArgsTable block usage
To use the props table in MDX, use the ArgsTable block imported from '@storybook/addon-docs' with the syntax '<ArgsTable of={MyComponent} />'.
DocsPage props table setup
To use the props table in DocsPage, export a component property on your stories metadata. Simply declare the component in the story default export with 'component: MyComponent'.
Storybook Docs automatically generates props tables for components
Storybook Docs automatically generates props tables for components in supported frameworks including React, Vue3, Angular, Web Components, and Ember.
ArgTypes control property specifies control type
The control property in ArgTypes specifies what type of control component to use for editing a property. It can be set to null to disable the control, or configured with a type like 'text', 'radio', etc.
ArgTypes customization merging behavior
When you customize ArgTypes in story configuration, the values you specify get merged over the defaults that are extracted by Storybook. Custom values override the automatically extracted ones.
Props table generation dependencies by framework
Props table generation relies on underlying libraries per framework: React uses 'react-docgen' and 'react-docgen-typescript', Vue 3 uses 'vue-docgen-api', Angular uses 'compodoc', Web-components uses 'custom-elements.json', and Ember uses 'yui-doc'.
ArgTypes shorthand notation
ArgTypes support shorthand notation: 'type: "number"' is shorthand for 'type: { name: "number" }' and 'control: "radio"' is shorthand for 'control: { type: "radio" }'.
ArgTypes customization fields and their purposes
ArgTypes can be customized using these fields: name (property name), type.required (whether property is required), description (markdown description), table.type.summary (short type version), table.type.detail (longer type version for complex types), table.defaultValue.summary (short default value version), table.defaultValue.detail (longer default value version for complex values), and control (addon-controls configuration).
ArgTypes customization available for DocsPage and ArgsTable story construct
You can customize props tables by customizing the ArgTypes data. This is currently available for DocsPage and the '<ArgsTable story="xxx" />' construct in MDX, but not for the '<ArgsTable of={component} />' construct.
ArgTypes data structure
Props tables are rendered from an internal data structure called ArgTypes. When you declare a story's component metadata, Docs automatically extracts ArgTypes based on the component's properties. ArgTypes contains fields: name (property name), type (with name and required), defaultValue, description, table (with type and defaultValue summaries/details), and control (with type specification).
MDX ArgsTable with controls configuration
In MDX, the ArgsTable controls are more configurable than in DocsPage. To show controls, ArgsTable must be a function of a story, not a component. Use the syntax '<ArgsTable story="Controls" />' after defining a story with '<Story name="WithControls">{args => <MyComponent {...args} />}</Story>'.