mirror of
https://github.com/storybookjs/storybook.git
synced 2025-03-18 05:02:24 +08:00
Merge branch '6.0-docs' into configure_section_updates
This commit is contained in:
jonniebigodes
GitHub
commit
0fc75fef9f
@ -34,7 +34,7 @@ Storybook ships with time-saving tools built in. The **toolbar** contains tools
|
||||
/>
|
||||
</video>
|
||||
|
||||
The [“Docs”](../writing-docs/introduction) tab shows auto-generated documentation about components (inferred from the source code). Usage docs are helpful when sharing reusable components with your team. For example, in a design system or component library.
|
||||
The [“Docs”](../writing-docs/introduction.md) tab shows auto-generated documentation about components (inferred from the source code). Usage docs are helpful when sharing reusable components with your team. For example, in a design system or component library.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -43,7 +43,7 @@ The [“Docs”](../writing-docs/introduction) tab shows auto-generated document
|
||||
/>
|
||||
</video>
|
||||
|
||||
The toolbar is customizable. You can use [globals](../essentials/toolbars-and-globals) to quickly toggle themes and languages. Or install Storybook toolbar [addons](../configure/user-interface#addons-description) from the community to enable advanced workflows.
|
||||
The toolbar is customizable. You can use [globals](../essentials/toolbars-and-globals.md) to quickly toggle themes and languages. Or install Storybook toolbar [addons](../configure/storybook-addons.md) from the community to enable advanced workflows.
|
||||
|
||||
### Addons
|
||||
|
||||
@ -62,6 +62,6 @@ Addons are plugins that extend Storybook's core functionality. You can find them
|
||||
/>
|
||||
</video>
|
||||
|
||||
Storybook is extensible. Our rich ecosystem of addons helps you test, document, and optimize your stories. You can also create an addon to satisfy your workflow requirements. Read more in the [addons section](../api/addons).
|
||||
Storybook is extensible. Our rich ecosystem of addons helps you test, document, and optimize your stories. You can also create an addon to satisfy your workflow requirements. Read more in the [addons section](../api/addons.md).
|
||||
|
||||
In the next chapter, we'll get your components rendering in Storybook so you can use it to supercharge component development.
|
||||
|
||||
@ -8,5 +8,5 @@ If you’d like to learn workflows for building app UIs with Storybook, check ou
|
||||
|
||||
What to learn next:
|
||||
|
||||
- [Write stories](../writing-stories/introduction)
|
||||
- [Write component docs](../writing-docs/introduction)
|
||||
- [Write stories](../writing-stories/introduction.md)
|
||||
- [Write component docs](../writing-docs/introduction.md)
|
||||
|
||||
@ -31,7 +31,7 @@ Depending on your technology stack, you also might need to configure the Storybo
|
||||
|
||||
### Configure Storybook for your stack
|
||||
|
||||
Storybook comes with a permissive [default configuration](../configure/overview). It attempts to customize itself to fit your setup. But it’s not foolproof.
|
||||
Storybook comes with a permissive [default configuration](../configure/overview.md). It attempts to customize itself to fit your setup. But it’s not foolproof.
|
||||
|
||||
Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.
|
||||
|
||||
@ -40,9 +40,9 @@ Your project may have additional requirements before components can be rendered
|
||||
|
||||
If you see errors on the CLI when you run the `yarn storybook` command. It’s likely you need to make changes to Storybook’s build configuration. Here are some things to try:
|
||||
|
||||
- [Presets](../api/addons#addon-presets) bundle common configurations for various technologies into Storybook. In particular presets exist for Create React App, SCSS and Ant Design.
|
||||
- Specify a custom [Babel configuration](../configure/integration#custom-babel-config) for Storybook. Storybook automatically tries to use your project’s config if it can.
|
||||
- Adjust the [webpack configuration](../configure/integration#webpack) that Storybook uses. Try patching in your own configuration if needed.
|
||||
- [Presets](../api/presets.md) bundle common configurations for various technologies into Storybook. In particular presets exist for Create React App, SCSS and Ant Design.
|
||||
- Specify a custom [Babel configuration](../configure/integration.md#custom-babel-config) for Storybook. Storybook automatically tries to use your project’s config if it can.
|
||||
- Adjust the [webpack configuration](../configure/integration.md#webpack) that Storybook uses. Try patching in your own configuration if needed.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
@ -58,7 +58,7 @@ If a particular story has a problem rendering, often it means your component exp
|
||||
|
||||
A common frontend pattern is for components to assume that they render in a certain “context” with parent components higher up the rendering hierarchy (for instance theme providers)
|
||||
|
||||
Use [decorators](../writing-stories/decorators) to “wrap” every story in the necessary context providers. [`.storybook/preview.js`](../configure/overview#configure-story-rendering) allows you to customize how components render in Canvas, the preview iframe. In this decorator example, we wrap every component rendered in Storybook with `ThemeProvider`.
|
||||
Use [decorators](../writing-stories/decorators.md) to “wrap” every story in the necessary context providers. [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) allows you to customize how components render in Canvas, the preview iframe. In this decorator example, we wrap every component rendered in Storybook with `ThemeProvider`.
|
||||
|
||||
```js
|
||||
// .storybook/preview.js
|
||||
@ -90,21 +90,21 @@ Theme users may need to add a decorator to `.storybook/preview.js`, [see above](
|
||||
<details>
|
||||
<summary>@import CSS into components</summary>
|
||||
|
||||
Storybook allows you to import CSS files in your components directly. But in some cases you may need to [tweak the webpack config](../configure/integration#webpack). Angular components require [a special import](../configure/integration#importing-css-files).
|
||||
Storybook allows you to import CSS files in your components directly. But in some cases you may need to [tweak the webpack config](../configure/integration.md#webpack). Angular components require [a special import](../configure/integration.md#importing-css-files).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Global imported styles</summary>
|
||||
|
||||
If you have global imported styles, create a file called [`.storybook/preview.js`](../configure/overview#configure-story-rendering) and import the styles there. The styles will be added by Storybook automatically for all stories.
|
||||
If you have global imported styles, create a file called [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) and import the styles there. The styles will be added by Storybook automatically for all stories.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Add external CSS or fonts in the <head></summary>
|
||||
|
||||
Alternatively if you want to inject a CSS link tag to the `<head>` directly (or some other resource like a font link), you can use [`.storybook/preview-head.html`](/configure/story-rendering#adding-to-<head>) to add arbitrary HTML.
|
||||
Alternatively if you want to inject a CSS link tag to the `<head>` directly (or some other resource like a font link), you can use [`.storybook/preview-head.html`](../configure/story-rendering.md#adding-to-<head>) to add arbitrary HTML.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ export const Primary = () => <Button primary>Button</Button>;
|
||||
|
||||
View the rendered `Button` by clicking on it in the Storybook sidebar.
|
||||
|
||||
The above story definition can be further improved to take advantage of [Storybook’s “args”](../writing-stories/args) concept. Args describes the arguments to Button in a machine readable way. This unlocks Storybook’s superpower of altering and composing arguments dynamically.
|
||||
The above story definition can be further improved to take advantage of [Storybook’s “args”](../writing-stories/args.md) concept. Args describes the arguments to Button in a machine readable way. This unlocks Storybook’s superpower of altering and composing arguments dynamically.
|
||||
|
||||
```js
|
||||
// We create a “template” of how args map to rendering
|
||||
@ -75,6 +75,6 @@ Stories are also useful for checking that UI continues to look correct as you ma
|
||||
/>
|
||||
</video>
|
||||
|
||||
Checking a component’s stories as you develop helps prevent accidental regressions. Tools that integrate with Storybook can also [automate](..workflows/testing-with-storybook) this for you.
|
||||
Checking a component’s stories as you develop helps prevent accidental regressions. Tools that integrate with Storybook can also [automate](..workflows/testing-with-storybook.md) this for you.
|
||||
|
||||
Now we’ve seen the basic anatomy of a story, let’s see how we use Storybook’s UI to develop stories
|
||||
331
docs/toc.js
331
docs/toc.js
@ -2,66 +2,301 @@ module.exports = {
|
||||
toc: [
|
||||
{
|
||||
title: 'Get Started',
|
||||
prefix: 'get-started',
|
||||
pages: ['introduction', 'install', 'whats-a-story', 'browse-stories', 'setup', 'conclusion'],
|
||||
pathSegment: 'get-started',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'introduction',
|
||||
title: 'Introduction',
|
||||
type: 'bullet-link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'install',
|
||||
title: 'Install',
|
||||
type: 'bullet-link',
|
||||
// DOCSTODO: Update the description
|
||||
description: 'Install the Storybook package in your project',
|
||||
},
|
||||
{
|
||||
pathSegment: 'whats-a-story',
|
||||
title: "What's a story?",
|
||||
type: 'bullet-link',
|
||||
// DOCSTODO: Update the description
|
||||
description: 'Learn the base construct of stories within Storybook',
|
||||
},
|
||||
{
|
||||
pathSegment: 'browse-stories',
|
||||
title: 'Browse stories',
|
||||
type: 'bullet-link',
|
||||
// DOCSTODO: Update the description
|
||||
description: 'Learn how to explore your stories within Storybook',
|
||||
},
|
||||
{
|
||||
pathSegment: 'setup',
|
||||
title: 'Setup',
|
||||
type: 'bullet-link',
|
||||
// DOCSTODO: Update the description
|
||||
description:
|
||||
'Write your first story & adjust Storybook configuration for your environment',
|
||||
},
|
||||
{
|
||||
pathSegment: 'conclusion',
|
||||
title: 'Conclusion',
|
||||
type: 'bullet-link',
|
||||
// DOCSTODO: Update the description
|
||||
description: 'Take your Storybook skills to the next level',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Writing Stories',
|
||||
prefix: 'writing-stories',
|
||||
pages: [
|
||||
'introduction',
|
||||
'args',
|
||||
'parameters',
|
||||
'decorators',
|
||||
'naming-components-and-hierarchy',
|
||||
pathSegment: 'writing-stories',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'introduction',
|
||||
title: 'Introduction',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'args',
|
||||
title: 'Args',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'parameters',
|
||||
title: 'Parameters',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'decorators',
|
||||
title: 'Decorators',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'naming-components-and-hierarchy',
|
||||
title: 'Naming components and hierarchy',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Writing Docs',
|
||||
prefix: 'writing-docs',
|
||||
pages: ['introduction', 'docs-page', 'mdx', 'doc-blocks'],
|
||||
},
|
||||
{
|
||||
title: 'Essentials',
|
||||
prefix:'essentials',
|
||||
pages:['introduction','controls','actions','viewports','backgrounds','toolbars-and-globals']
|
||||
},
|
||||
{
|
||||
title: 'Configure',
|
||||
prefix: 'configure',
|
||||
pages: [
|
||||
'overview',
|
||||
'integration',
|
||||
'story-rendering',
|
||||
'user-interface',
|
||||
'features-and-behavior',
|
||||
'theming',
|
||||
'sidebar-and-urls',
|
||||
'storybook-addons',
|
||||
'environment-variables'
|
||||
pathSegment: 'writing-docs',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'introduction',
|
||||
title: 'Introduction',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'docs-page',
|
||||
title: 'Docs Page',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'mdx',
|
||||
title: 'MDX',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'doc-blocks',
|
||||
title: 'Docs Blocks',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'build-documentation',
|
||||
title: 'Preview and build Storybook documentation',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title:'Workflows',
|
||||
prefix:'workflows',
|
||||
pages:[
|
||||
'publish-storybook',
|
||||
'build-pages-with-storybook',
|
||||
'stories-for-multiple-components',
|
||||
'testing-with-storybook',
|
||||
'unit-testing',
|
||||
'visual-testing',
|
||||
'interaction-testing',
|
||||
'snapshot-testing',
|
||||
'storybook-composition',
|
||||
'package-composition'
|
||||
]
|
||||
title: 'Essentials',
|
||||
pathSegment: 'essentials',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'introduction',
|
||||
title: 'Introduction',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'controls',
|
||||
title: 'Controls',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'actions',
|
||||
title: 'Actions',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'viewports',
|
||||
title: 'Viewports',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'backgrounds',
|
||||
title: 'Backgrounds',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'toolbars-and-globals',
|
||||
title: 'Toolbars & globals',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Configure',
|
||||
pathSegment: 'configure',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'overview',
|
||||
title: 'Overview',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'integration',
|
||||
title: 'Integration',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'story-rendering',
|
||||
title: 'Story rendering',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'user-interface',
|
||||
title: 'User interface',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'features-and-behavior',
|
||||
title: 'Features and behavior',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'theming',
|
||||
title: 'Theming',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'sidebar-and-urls',
|
||||
title: 'Sidebar & URLS',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'storybook-addons',
|
||||
title: 'Storybook Addons',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'environment-variables',
|
||||
title: 'Environment variables',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Workflows',
|
||||
pathSegment: 'workflows',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'publish-storybook',
|
||||
title: 'Publish Storybook',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'build-pages-with-storybook',
|
||||
title: 'Building pages with Storybook',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'stories-for-multiple-components',
|
||||
title: 'Stories for multiple components',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
title: 'Testing with Storybook',
|
||||
// Despite having a child menu, this does not currently affect the path
|
||||
pathSegment: '',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'testing-with-storybook',
|
||||
title: 'Introduction',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'unit-testing',
|
||||
title: 'Unit testing',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'visual-testing',
|
||||
title: 'Visual testing',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'interaction-testing',
|
||||
title: 'Interaction testing',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'snapshot-testing',
|
||||
title: 'Snapshot testing',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
pathSegment: 'storybook-composition',
|
||||
title: 'Storybook Composition',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'package-composition',
|
||||
title: 'Package Composition',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
title: 'API',
|
||||
prefix:'api',
|
||||
pages:['stories','addons','new-frameworks','cli-options','frameworks-feature-support']
|
||||
pathSegment: 'api',
|
||||
type: 'menu',
|
||||
children: [
|
||||
{
|
||||
pathSegment: 'stories',
|
||||
title: 'Stories',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'addons',
|
||||
title: 'Addons',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'new-frameworks',
|
||||
title: 'Frameworks',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'cli-options',
|
||||
title: 'CLI Options',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'frameworks-feature-support',
|
||||
title: 'Feature support for frameworks',
|
||||
type: 'link',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
@ -18,6 +18,16 @@ Storybook will create a static web application at the path you specify. This can
|
||||
npx http-server ./path/to/build
|
||||
```
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Asides from the `-o` flag, you can also include other flags to build Storybook, for instance if you're using [Docs](../writing-docs/introduction.md), you can append the `--docs` flag and Storybook will build your [MDX](../writing-docs/mdx.md) and [CSF](../writing-stories/introduction.md#component-story-format) stories into a rich and interactive documentation.
|
||||
|
||||
You can learn more about these flag options [here](../api/cli-options.md).
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
### Publish Storybook online
|
||||
|
||||
Once your Storybook is built as a static web app it can be deployed to any static site hosting services. The Storybook team uses [Chromatic](https://www.chromatic.com/), a free publishing service made by Storybook maintainers that documents, versions, and indexes your UI components securely in the cloud.
|
||||
|
||||
56
docs/writing-docs/build-documentation.md
Normal file
56
docs/writing-docs/build-documentation.md
Normal file
@ -0,0 +1,56 @@
|
||||
---
|
||||
title: 'Preview and build Storybook documentation'
|
||||
---
|
||||
|
||||
Storybook allows you to create rich and extensive [documentation](./introduction.md) that will help you and any other stakeholder involved in the development process. Out of the box you have the tooling required to not only write it but also to preview it and build it.
|
||||
|
||||
### Preview Storybook's documentation
|
||||
|
||||
At any point during your development, you can preview the documentation you've written. Storybook allows you to generate a preview of the final documentation when you use the `--docs` flag. We recommend including it in your `package.json` as a new script:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"storybook-docs": "start-storybook --docs",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Depending on your configuration, when you execute the `storybook-docs` script. Storybook will be put into documentation mode and will generate a different build.
|
||||
|
||||
It will look for any stories available either in [MDX](./mdx.md) or[CSF](../writing-stories/introduction.md#component-story-format) and based on the documentation you've added it will display it...
|
||||
|
||||
|
||||
|
||||
|
||||
There's some caveats to this build mode, as to the normal Storybook build:
|
||||
|
||||
- The top level item refers to the primary story for your component.
|
||||
- Each individual story is now in a flattened display mode, with a different set of icons. This allows focus on the documentation itself.
|
||||
- Storybook's layout is rendered differently. The toolbar will not be displayed.
|
||||
|
||||
|
||||
### Publish Storybook's documentation
|
||||
|
||||
You can also publish your documentation, the same you would [publish](../workflows/publish-storybook.md) your Storybook. You can use the `--docs` flag with `build-storybook` command. We recommend as well including it as a script in your `package.json` file:
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build-storybook-docs": "build-storybook --docs",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Based on the configuration you have, when the `build-storybook-docs` script is executed, Storybook once again will be put into documentation mode and will generate a different build and output the documentation into the `storybook-static` folder.
|
||||
|
||||
The same caveats mentioned above will apply.
|
||||
|
||||
|
||||
You can use any hosting provider to deploy your documentation, for instance:
|
||||
|
||||
- [Vercel](https://vercel.com/)
|
||||
- [Netlify](https://www.netlify.com/)
|
||||
- [S3](https://aws.amazon.com/en/s3/)
|
||||
@ -2,13 +2,17 @@
|
||||
title: 'Doc Blocks'
|
||||
---
|
||||
|
||||
Doc Blocks are the building blocks of Storybook documentation pages. By default, [DocsPage](./docs-page) uses a combination of the blocks below to build a page for each of your components automatically.
|
||||
<div>
|
||||
TODO: vet the canvas changes. Originally it was Preview and now it's Canvas (associated issue https://github.com/storybookjs/storybook/issues/11696)
|
||||
</div>
|
||||
|
||||
Custom [addons](../configure/user-interface#storybook-addons) can also provide their own doc blocks.
|
||||
Doc Blocks are the building blocks of Storybook documentation pages. By default, [DocsPage](./docs-page.md) uses a combination of the blocks below to build a page for each of your components automatically.
|
||||
|
||||
Custom [addons](../configure/user-interface.md#storybook-addons) can also provide their own doc blocks.
|
||||
|
||||
### ArgsTable
|
||||
|
||||
Storybook Docs automatically generates component props tables for components in supported frameworks. These tables list the arguments ([args for short](../writing-stories/args)) of the component, and even integrate with [controls](../essentials/controls) to allow you to change the args of the currently rendered story.
|
||||
Storybook Docs automatically generates component args tables for components in supported frameworks. These tables list the arguments ([args for short](../writing-stories/args.md)) of the component, and even integrate with [controls](../essentials/controls.md) to allow you to change the args of the currently rendered story.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -17,9 +21,39 @@ Storybook Docs automatically generates component props tables for components in
|
||||
/>
|
||||
</video>
|
||||
|
||||
This is extremely useful, but it can be further expanded. Additional information can be added to the component to better document it:
|
||||
|
||||
```js
|
||||
// Button.js
|
||||
|
||||
import React from 'react';
|
||||
import PropTypes from 'prop-types';
|
||||
|
||||
export default function Button({isDisabled,content}) {
|
||||
return (
|
||||
<button disabled={isDisabled}>{content}</button>
|
||||
);
|
||||
}
|
||||
|
||||
Button.propTypes = {
|
||||
/**
|
||||
Checks if the button should be disable
|
||||
*/
|
||||
isDisabled: PropTypes.bool.isRequired,
|
||||
/**
|
||||
The display content of the button
|
||||
*/
|
||||
content: PropTypes.string.isRequired,
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
By including the additional information, the args table will be updated. Offering a richer experience for any stakeholders involved.
|
||||
|
||||
|
||||
#### DocsPage
|
||||
|
||||
To use the ArgsTable in [DocsPage](./docspage#component-parameter), export a component property on your stories metadata:
|
||||
To use the `ArgsTable` in [DocsPage](./docs-page.md#component-parameter), export a component property on your stories metadata:
|
||||
|
||||
```js
|
||||
// MyComponent.stories.js
|
||||
@ -35,7 +69,7 @@ export default {
|
||||
|
||||
#### MDX
|
||||
|
||||
To use the ArgsTable in MDX, use the Props block:
|
||||
To use the `ArgsTable` in MDX, use the Props block:
|
||||
|
||||
```js
|
||||
// MyComponent.stories.mdx
|
||||
@ -50,11 +84,11 @@ import { MyComponent } from './MyComponent';
|
||||
|
||||
#### Customizing
|
||||
|
||||
ArgsTables are automatically inferred from your components and stories, but sometimes it's useful to customize the results.
|
||||
`ArgsTables` are automatically inferred from your components and stories, but sometimes it's useful to customize the results.
|
||||
|
||||
ArgsTables are rendered from an internal data structure called [ArgTypes](../api/stories#argtypes). When you declare a story's component metadata, Docs automatically extracts ArgTypes based on the component's properties.
|
||||
`ArgsTables` are rendered from an internal data structure called [ArgTypes](../api/mdx.md#argtypes). When you declare a story's component metadata, Docs automatically extracts ArgTypes based on the component's properties.
|
||||
|
||||
You can customize what's shown in the ArgsTable by customizing the ArgTypes data. This is currently available for [DocsPage](./docs-page) and `<Props story="xxx">` construct, but not for the `<Props of={component} />` construct.
|
||||
You can customize what's shown in the `ArgsTable` by customizing the `ArgTypes` data. This is currently available for [DocsPage](./docs-page.md) and `<Props story="xxx">` construct, but not for the `<Props of={component} />` construct.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
@ -62,7 +96,7 @@ NOTE: This API is experimental and may change outside of the typical semver rele
|
||||
|
||||
</div>
|
||||
|
||||
The API documentation of ArgTypes is detailed in a [separate section](../api/stories#argtypes), but to control the description and default values, use the following fields:
|
||||
The API documentation of `ArgTypes` is detailed in a [separate section](../api/mdx.md#argtypes), but to control the description and default values, use the following fields:
|
||||
|
||||
| Field | Description |
|
||||
|:-----------------------------|:----------------------------------------------------------------------------------------------:|
|
||||
@ -110,7 +144,7 @@ For instance you can use:
|
||||
|
||||
##### MDX
|
||||
|
||||
To customize argTypes in MDX, you can set an `mdx` prop on the `Meta` or `Story` components:
|
||||
To customize `argTypes` in MDX, you can set an `mdx` prop on the `Meta` or `Story` components:
|
||||
|
||||
```js
|
||||
|
||||
@ -137,7 +171,7 @@ To customize argTypes in MDX, you can set an `mdx` prop on the `Meta` or `Story`
|
||||
|
||||
#### Controls
|
||||
|
||||
The controls inside an ArgsTable are configured in exactly the same way as the [controls](../essentials/controls) addon pane. In fact you’ll probably notice the table is very similar! It uses the same component and mechanism behind the scenes.
|
||||
The controls inside an `ArgsTable` are configured in exactly the same way as the [controls](../essentials/controls.md) addon pane. In fact you’ll probably notice the table is very similar! It uses the same component and mechanism behind the scenes.
|
||||
|
||||
### Source
|
||||
|
||||
@ -147,7 +181,7 @@ Storybook Docs displays a story’s source code using the `Source` block. The sn
|
||||
|
||||
#### DocsPage
|
||||
|
||||
In DocsPage, the `Source` block appears automatically within each story’s [Preview] block.
|
||||
In DocsPage, the `Source` block appears automatically within each story’s [Canvas](#canvas) block.
|
||||
|
||||
To customize the source snippet that’s displayed for a story, set the `docs.source.code` parameter:
|
||||
|
||||
@ -241,11 +275,11 @@ Stories (component examples) are the basic building blocks in Storybook. In Stor
|
||||
|
||||
#### DocsPage
|
||||
|
||||
In DocsPage, a `Story` block is generated for each story in your [CSF] file, it's wrapped with a `Preview` wrapper that gives it a toolbar on top (in the case of the first “primary” story) and a source code preview underneath.
|
||||
In DocsPage, a `Story` block is generated for each story in your [CSF](../api/csf.md) file, it's wrapped with a `Canvas` wrapper that gives it a toolbar on top (in the case of the first “primary” story) and a source code preview underneath.
|
||||
|
||||
#### MDX
|
||||
|
||||
In MDX, the `Story` block is not only a way of displaying stories, but also the primary way to define them. Storybook looks for `Story` instances with the `name` prop, either defined at the top level of the document, or directly beneath a [Preview](#preview) block defined at the top level:
|
||||
In MDX, the `Story` block is not only a way of displaying stories, but also the primary way to define them. Storybook looks for `Story` instances with the `name` prop, either defined at the top level of the document, or directly beneath a [Canvas](#canvas) block defined at the top level:
|
||||
|
||||
```js
|
||||
import { Story } from '@storybook/addon-docs/blocks';
|
||||
@ -269,29 +303,27 @@ import { Story } from '@storybook/addon-docs/blocks';
|
||||
|
||||
#### Inline rendering
|
||||
|
||||
In Storybook’s Canvas, all stories are rendered in the [Preview iframe] for isolated development. In Storybook Docs, when [inline rendering is supported by your framework](./docs-page#inline-stories-vs-iframe-stories), inline rendering is used by default for performance and convenience. However, you can force iframe rendering with `docs: { inlineStories: false }` parameter, or `inline={false}` in MDX.
|
||||
In Storybook’s Canvas, all stories are rendered in the Preview iframe for isolated development. In Storybook Docs, when [inline rendering is supported by your framework](./docs-page.md#inline-stories-vs-iframe-stories), inline rendering is used by default for performance and convenience. However, you can force iframe rendering with `docs: { inlineStories: false }` parameter, or `inline={false}` in MDX.
|
||||
|
||||
|
||||
### Preview
|
||||
### Canvas
|
||||
|
||||
Storybook Docs’ `Preview` block is a wrapper that provides a toolbar for interacting with its contents, and also also provides [Source](#Source) snippets automatically.
|
||||
Storybook Docs’ `Canvas` block is a wrapper that provides a toolbar for interacting with its contents, and also also provides [Source](#source) snippets automatically.
|
||||
|
||||
|
||||
|
||||
#### DocsPage
|
||||
|
||||
In DocsPage, every story is wrapped in a `Preview` block. The first story on the page is called the _primary_, and it has a toolbar. The other stories are also wrapped with `Previews`, but there is no toolbar by default.
|
||||
In DocsPage, every story is wrapped in a `Canvas` block. The first story on the page is called the _primary_, and it has a toolbar. The other stories are also wrapped with `Canvas`, but there is no toolbar by default.
|
||||
|
||||
|
||||
|
||||
#### MDX
|
||||
|
||||
In MDX, `Preview` is more flexible: in addition to the DocsPage behavior, it can show multiple stories in one, and even show non-story content.
|
||||
|
||||
When you
|
||||
In MDX, `Canvas` is more flexible: in addition to the DocsPage behavior, it can show multiple stories in one:
|
||||
|
||||
```js
|
||||
import { Preview } from '@storybook/addon-docs/blocks';
|
||||
import { Canvas } from '@storybook/addon-docs/blocks';
|
||||
|
||||
export const Template = (args) => <Badge {...args } />
|
||||
|
||||
@ -308,10 +340,10 @@ export const Template = (args) => <Badge {...args } />
|
||||
</Preview>
|
||||
```
|
||||
|
||||
You can also place non-story content inside a `Preview` block:
|
||||
You can also place non-story content inside a `Canvas` block:
|
||||
|
||||
```js
|
||||
import { Preview } from '@storybook/addon-docs/blocks';
|
||||
import { Canvas } from '@storybook/addon-docs/blocks';
|
||||
import { MyComponent } from './MyComponent';
|
||||
<Preview>
|
||||
<h2>Some here</h2>
|
||||
|
||||
@ -22,25 +22,26 @@ export default {
|
||||
|
||||
### Subcomponents parameter
|
||||
|
||||
Sometimes it's useful to document multiple components together. For example, a component library’s List and ListItem components might not make sense without one another.
|
||||
Sometimes it's useful to document multiple components together. For example, a component library’s ButtonGroup and Button components might not make sense without one another.
|
||||
|
||||
DocsPage has the concept of a "primary" component that is defined by the `component` parameter. It also accepts one or more `subcomponents`.
|
||||
|
||||
|
||||
```js
|
||||
// List.stories.js
|
||||
import { List, ListHeading, ListItem } from './List';
|
||||
// ButtonGroup.stories.js
|
||||
|
||||
import { Button, ButtonGroup } from './ButtonGroup';
|
||||
|
||||
export default {
|
||||
title: 'Path/to/List',
|
||||
component: List,
|
||||
subcomponents: { ListHeading, ListItem },
|
||||
title: 'Path/to/ButtonGroup',
|
||||
component: ButtonGroup,
|
||||
subcomponents: { Button},
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
Subcomponent ArgsTables will show up in a tabbed interface along with the primary component. The tab titles will correspond to the keys of the subcomponents object.
|
||||
Subcomponent `ArgsTables` will show up in a tabbed interface along with the primary component. The tab titles will correspond to the keys of the subcomponents object.
|
||||
|
||||
If you want to organize your documentation differently for component groups, we recommend using MDX. It gives you complete control over display and supports any configuration.
|
||||
|
||||
@ -49,7 +50,7 @@ If you want to organize your documentation differently for component groups, we
|
||||
|
||||
Replace DocsPage template with your own for the entire Storybook, a specific component, or a specific story.
|
||||
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters):
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters.md):
|
||||
|
||||
- With null to remove docs.
|
||||
- With MDX docs.
|
||||
@ -57,7 +58,7 @@ Override the `docs.page` [parameter](../writing-stories/parameters):
|
||||
|
||||
#### Story-level
|
||||
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters#story-parameters) in the story definition.
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters.md#story-parameters) in the story definition.
|
||||
|
||||
```js
|
||||
// Button.stories.js
|
||||
@ -68,7 +69,7 @@ Primary.parameters = { docs: { page: null } }
|
||||
|
||||
#### Component-level
|
||||
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters#component-parameters) in the default export of the story file.
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters.md#component-parameters) in the default export of the story file.
|
||||
|
||||
```js
|
||||
// Button.stories.js
|
||||
@ -87,7 +88,7 @@ export default {
|
||||
|
||||
#### Global-level
|
||||
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters#global-parameters) in [`.storybook/preview.js`](../configure/overview#configure-story-rendering).
|
||||
Override the `docs.page` [parameter](../writing-stories/parameters.md#global-parameters) in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
|
||||
|
||||
```js
|
||||
// .storybook/preview.js
|
||||
@ -141,7 +142,7 @@ export default {
|
||||
|
||||
Apply a similar technique to remix the DocsPage at the [story](#story-level), [component](#component-level), or [global](#global-level) level.
|
||||
|
||||
In addition, you can interleave your own components to customize the auto-generated contents of the page, or pass in different options to the blocks to customize their appearance. Read more about [Doc Blocks](./docs-blocks).
|
||||
In addition, you can interleave your own components to customize the auto-generated contents of the page, or pass in different options to the blocks to customize their appearance. Read more about [Doc Blocks](./doc-blocks.md).
|
||||
|
||||
### Story file names
|
||||
|
||||
|
||||
@ -13,11 +13,11 @@ Storybook gives you tools to expand this basic documentation with prose and layo
|
||||
/>
|
||||
</video>
|
||||
|
||||
Out of the box, Storybook ships with [DocsPage](./docs-page), a documentation template that lists all the stories for a component and associated metadata. It infers metadata values based on source code, types and JSDoc comments. [Customize](./docs-page#replacing-docspage) this page to create a new template if you have specific requirements.
|
||||
Out of the box, Storybook ships with [DocsPage](./docs-page.md), a documentation template that lists all the stories for a component and associated metadata. It infers metadata values based on source code, types and JSDoc comments. [Customize](./docs-page.md#replacing-docspage) this page to create a new template if you have specific requirements.
|
||||
|
||||
You can also create free-form pages for each component using [MDX](./mdx), a format for simultaneously documenting components and writing stories.
|
||||
You can also create free-form pages for each component using [MDX](./mdx.md), a format for simultaneously documenting components and writing stories.
|
||||
|
||||
In both cases, you’ll use [Doc Blocks](./docs-blocks) as the building blocks to create full featured documentation.
|
||||
In both cases, you’ll use [Doc Blocks](./doc-blocks.md) as the building blocks to create full featured documentation.
|
||||
|
||||
Docs is autoconfigured to work out of the box in most use cases. In some cases you may need or want to tweak the configuration. Read more about it in the [ADVANCED README](../../addons/docs/ADVANCED-README.md).
|
||||
|
||||
|
||||
@ -58,7 +58,7 @@ Let's break it down.
|
||||
|
||||
### MDX-flavored CSF
|
||||
|
||||
MDX-flavored [Component Story Format (CSF)](../formats/component-story-format/) includes a collection of components called ["Doc Blocks"](./docs-blocks), that allow Storybook to translate MDX files into Storybook stories. MDX-defined stories are identical to regular Storybook stories, so they can be used with Storybook's entire ecosystem of addons and view layers.
|
||||
MDX-flavored [Component Story Format (CSF)](../api/csf.md) includes a collection of components called ["Doc Blocks"](./doc-blocks.md), that allow Storybook to translate MDX files into Storybook stories. MDX-defined stories are identical to regular Storybook stories, so they can be used with Storybook's entire ecosystem of addons and view layers.
|
||||
|
||||
For example, here's the first story from the Checkbox example above, rewritten in CSF:
|
||||
|
||||
@ -206,10 +206,10 @@ To get a "documentation-only story", in your UI, define a `<Meta>` as you normal
|
||||
|
||||
### MDX file names
|
||||
|
||||
Unless you use a custom [webpack configuration](../configure/integration#extending-storybooks-webpack-config), all of your MDX files should have the suffix `*.stories.mdx`. This tells Storybook to apply its special processing to the `<Meta>` and `<Story>` elements in the file.
|
||||
Unless you use a custom [webpack configuration](../configure/integration.md#extending-storybooks-webpack-config), all of your MDX files should have the suffix `*.stories.mdx`. This tells Storybook to apply its special processing to the `<Meta>` and `<Story>` elements in the file.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Be sure to update [.storybook/main.js](../configure/overview#configure-story-rendering) file to load `.stories.mdx` stories, as per the addon-docs installation instructions.
|
||||
Be sure to update [.storybook/main.js](../configure/overview.md#configure-story-rendering) file to load `.stories.mdx` stories, as per the addon-docs installation instructions.
|
||||
|
||||
</div>
|
||||
BIN
docs/writing-docs/storybook-docs-build.png
Normal file
BIN
docs/writing-docs/storybook-docs-build.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 88 KiB |
@ -7,7 +7,7 @@ A story is a component with a set of arguments (props, slots, inputs, etc). “A
|
||||
When an arg’s value is changed, the component re-renders, allowing you to interact with components in Storybook’s UI via addons that affect args.
|
||||
|
||||
|
||||
Learn how and why to write stories with args [here](./introduction#using-args) section. For details on how args work, read on.
|
||||
Learn how and why to write stories with args [here](./introduction.md#using-args) section. For details on how args work, read on.
|
||||
|
||||
|
||||
### Args object
|
||||
@ -19,6 +19,8 @@ The args object can be defined at the story and component level (see below). It
|
||||
To define the args of a single story, use the `args` CSF story key:
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
export const Primary = Template.bind({});
|
||||
|
||||
Primary.args = {
|
||||
@ -27,9 +29,11 @@ Primary.args = {
|
||||
}
|
||||
```
|
||||
|
||||
These args will only apply to the story for which they are attached, although you can [reuse](../workflows/build-pages-with-storybook#args-composition-for-presentational-screens) them via JavaScript object reuse:
|
||||
These args will only apply to the story for which they are attached, although you can [reuse](../workflows/build-pages-with-storybook.md#args-composition-for-presentational-screens) them via JavaScript object reuse:
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
export const PrimaryLongName = Template.bind({});
|
||||
|
||||
PrimaryLongName.args = {
|
||||
@ -46,6 +50,8 @@ In the above example, we use the [object spread](https://developer.mozilla.org/e
|
||||
You can also define args at the component level; such args will apply to all stories of the component unless they are overwritten. To do so, use the `args` key of the `default` CSF export:
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
import Button from './Button';
|
||||
export default {
|
||||
title: "Button",
|
||||
@ -62,6 +68,8 @@ export default {
|
||||
You can separate the arguments to a story to compose in other stories. Here’s how args can be used in multiple stories for the same component.
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
|
||||
const Primary = ButtonStory.bind({});
|
||||
Primary.args = {
|
||||
@ -104,10 +112,10 @@ LoggedIn.args = {
|
||||
<details>
|
||||
<summary>Using args in addons</summary>
|
||||
|
||||
If you are [writing an addon](../api/addons#getting-started) that wants to read or update args, use the `useArgs` hook exported by `@storybook/api`:
|
||||
If you are [writing an addon](../api/addons.md) that wants to read or update args, use the `useArgs` hook exported by `@storybook/api`:
|
||||
|
||||
```js
|
||||
|
||||
// your-addon/register.js
|
||||
import { useArgs } from '@storybook/api';
|
||||
|
||||
const [args, updateArgs,resetArgs] = useArgs();
|
||||
@ -131,9 +139,11 @@ LoggedIn.args = {
|
||||
|
||||
In Storybook 6+, we pass the args as the first argument to the story function. The second argument is the “context” which contains things like the story parameters etc.
|
||||
|
||||
In Storybook 5 and before we passed the context as the first argument. If you’d like to revert to that functionality set the `parameters.passArgsFirst` parameter in [`.storybook/preview.js`](../configure/overview#configure-story-rendering):
|
||||
In Storybook 5 and before we passed the context as the first argument. If you’d like to revert to that functionality set the `parameters.passArgsFirst` parameter in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
|
||||
```js
|
||||
// .storybook/preview.js
|
||||
|
||||
export const parameter = { passArgsFirst : false }.
|
||||
```
|
||||
|
||||
|
||||
@ -13,6 +13,8 @@ Some components require a “harness” to render in a useful way. For instance
|
||||
|
||||
|
||||
```js
|
||||
// your-component.story.js
|
||||
|
||||
export default {
|
||||
component: TextComponent,
|
||||
decorators: [(Story) => <div style={{ margin: '3em' }}><Story/></div>]
|
||||
@ -25,7 +27,7 @@ export default {
|
||||
|
||||
### “Context” for mocking
|
||||
|
||||
Some libraries require components higher up in the component hierarchy to render properly. For example in Styled Components, a `ThemeProvider` is required if your components make use of themes. Add a single global decorator that add this context to to all stories in [`.storybook/preview.js`](../configure/overview#configure-story-rendering):
|
||||
Some libraries require components higher up in the component hierarchy to render properly. For example in Styled Components, a `ThemeProvider` is required if your components make use of themes. Add a single global decorator that add this context to to all stories in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
|
||||
```js
|
||||
// .storybook/preview.js
|
||||
@ -42,12 +44,12 @@ The second argument to a decorator function is the **story context** which in pa
|
||||
|
||||
- `args` - the story arguments. You can use some args in your decorators and drop them in the story implementation itself.
|
||||
|
||||
- `globals` - the Storybook-wide [globals](../essentials/toolbars-and-globals#globals). In particular you can use the [toolbars feature](../essentials/toolbars-and-globals#global-types-toolbar-annotations) to allow you to change these values using Storybook’s UI.
|
||||
- `globals` - the Storybook-wide [globals](../essentials/toolbars-and-globals.md#globals). In particular you can use the [toolbars feature](../essentials/toolbars-and-globals.md#global-types-toolbar-annotations) to allow you to change these values using Storybook’s UI.
|
||||
|
||||
|
||||
#### Using decorators to provide data
|
||||
|
||||
If your components are “connected” and require side-loaded data to render, you can use decorators to provide that data in a mocked way, without having to refactor your components to take that data as an arg. There are several techniques to achieve this, depending on exactly how you are loading that data -- read more in the [building pages in Storybook](../workflows/build-pages-with-storybook) section.
|
||||
If your components are “connected” and require side-loaded data to render, you can use decorators to provide that data in a mocked way, without having to refactor your components to take that data as an arg. There are several techniques to achieve this, depending on exactly how you are loading that data -- read more in the [building pages in Storybook](../workflows/build-pages-with-storybook.md) section.
|
||||
|
||||
### Story decorators
|
||||
|
||||
@ -58,7 +60,7 @@ export const Primary = …
|
||||
Primary.decorators = [(Story) => <div style={{ margin: '3em' }}><Story/></div>]
|
||||
```
|
||||
|
||||
This is useful to ensure that the story remains a “pure” rendering of the component under test and any extra HTML or components you need to add don’t pollute that. In particular the [Source](../writing-docs/docs-blocks#source) docblock works best when you do this.
|
||||
This is useful to ensure that the story remains a “pure” rendering of the component under test and any extra HTML or components you need to add don’t pollute that. In particular the [Source](../writing-docs/doc-blocks.md#source) docblock works best when you do this.
|
||||
|
||||
|
||||
### Component decorators
|
||||
@ -76,7 +78,7 @@ export default {
|
||||
|
||||
### Global decorators
|
||||
|
||||
We can also set a decorator for **all stories** via the `decorators` export of your [`.storybook/preview.js`](../configure/overview#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
We can also set a decorator for **all stories** via the `decorators` export of your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering.md) file (this is the file where you configure all stories):
|
||||
|
||||
```js
|
||||
export const decorators = [(Story) => <div style={{ margin: '3em' }}><Story/></div>]
|
||||
|
||||
@ -17,7 +17,7 @@ Button.stories.js | ts
|
||||
|
||||
### Component Story Format
|
||||
|
||||
We define stories according to the [Component Story Format](../formats/component-story-format) (CSF), an ES6 module-based standard that is portable between tools and easy to write.
|
||||
We define stories according to the [Component Story Format](../api/csf.md) (CSF), an ES6 module-based standard that is portable between tools and easy to write.
|
||||
|
||||
The key ingredients are the [**`default` export**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export) that describes the component, and [**named exports**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_named_exports) that describe the stories.
|
||||
|
||||
@ -52,6 +52,21 @@ export const Primary = () => <Button primary label="Button" />;
|
||||
|
||||
```
|
||||
|
||||
#### Rename stories
|
||||
|
||||
You can rename any particular story you need. For instance to give it a more clearer name. Here's how you can change the name of the `Primary` story:
|
||||
|
||||
```js
|
||||
import { Button } from './Button';
|
||||
|
||||
export const Primary=()=><Button primary label="Button"/>;
|
||||
|
||||
Primary.storyName='I am the primary';
|
||||
|
||||
```
|
||||
|
||||
Your story will now be show in the sidebar with the text supplied.
|
||||
|
||||
### How to write stories
|
||||
|
||||
A story is a function that describes how to render a component. You can have multiple stories per component. The simplest way to create stories is to render a component with different arguments multiple times.
|
||||
@ -108,7 +123,7 @@ Pair.args = {
|
||||
```
|
||||
When Button’s signature changes, you only need to change Button’s stories to reflect the new schema. ButtonGroup’s stories will automatically be updated. This pattern allows you to reuse your data definitions up and down your component hierarchy, making your stories more maintainable.
|
||||
|
||||
That’s not all! Each of the args from the story function are live editable using Storybook’s [controls](../essentials/controls) panel. This means your team can dynamically change components in Storybook to stress test and find edge cases.
|
||||
That’s not all! Each of the args from the story function are live editable using Storybook’s [controls](../essentials/controls.md) panel. This means your team can dynamically change components in Storybook to stress test and find edge cases.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -117,7 +132,7 @@ That’s not all! Each of the args from the story function are live editable usi
|
||||
/>
|
||||
</video>
|
||||
|
||||
Addons can enhance args. For instance, [Actions](../essentials/actions) auto detects which args are callbacks and appends a logging function to them. That way interactions (like clicks) get logged in the actions panel.
|
||||
Addons can enhance args. For instance, [Actions](../essentials/actions.md) auto detects which args are callbacks and appends a logging function to them. That way interactions (like clicks) get logged in the actions panel.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -153,7 +168,7 @@ export default {
|
||||
|
||||
|
||||
|
||||
This parameter would instruct the backgrounds addon to reconfigure itself whenever a Button story is selected. Most addons are configured via a parameter-based API and can be influenced at a [global](./parameters#global-parameters), [component](./parameters#component-parameters) and [story](./parameters#story-parameters) level.
|
||||
This parameter would instruct the backgrounds addon to reconfigure itself whenever a Button story is selected. Most addons are configured via a parameter-based API and can be influenced at a [global](./parameters.md#global-parameters), [component](./parameters.md#component-parameters) and [story](./parameters.md#story-parameters) level.
|
||||
|
||||
|
||||
#### Using decorators
|
||||
@ -173,7 +188,7 @@ export default {
|
||||
}
|
||||
```
|
||||
|
||||
Decorators [can be more complex](./decorators#context-for-mocking) and are often provided by [addons](../configure/user-interface#storybook-addons). You can also configure decorators at the [story](./decorators#story-decorators), [component](./decorators#component-decorators) and [global](./decorators#global-decorators) level.
|
||||
Decorators [can be more complex](./decorators.md#context-for-mocking) and are often provided by [addons](../configure/storybook-addons.md). You can also configure decorators at the [story](./decorators.md#story-decorators), [component](./decorators.md#component-decorators) and [global](./decorators.md#global-decorators) level.
|
||||
|
||||
|
||||
### Stories for two or more components
|
||||
@ -233,7 +248,7 @@ export const ManyItems = (args) => (
|
||||
|
||||
<div class="aside">
|
||||
|
||||
Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build more complex composite components. For more discussion, set the [multi component stories](../workflows/stories-for-multiple-components) workflow article.
|
||||
Note that there are disadvantages in writing stories like this as you cannot take full advantage of the args mechanism and composing args as you build more complex composite components. For more discussion, set the [multi component stories](../workflows/stories-for-multiple-components.md) workflow article.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
@ -43,7 +43,7 @@ Yields this:
|
||||
|
||||
### Roots
|
||||
|
||||
By default the top-level grouping will be displayed as a “root” in the UI (the all-caps, non expandable grouping in the screenshot above). If you prefer, you can [configure Storybook](../configure/user-interface#roots) to not show roots.
|
||||
By default the top-level grouping will be displayed as a “root” in the UI (the all-caps, non expandable grouping in the screenshot above). If you prefer, you can [configure Storybook](..configure/sidebar-and-urls.md#roots) to not show roots.
|
||||
|
||||
We recommend naming components according to the file hierarchy.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: 'Parameters'
|
||||
---
|
||||
|
||||
**Parameters** are a set of static, named metadata about a story, typically used to control the behaviour of Storybook features and addons.
|
||||
**Parameters** are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.
|
||||
|
||||
For example, let’s customize the backgrounds addon via a parameter. We’ll use `parameters.backgrounds` to define which backgrounds appear in the backgrounds toolbar when a story is selected.
|
||||
|
||||
@ -11,6 +11,8 @@ For example, let’s customize the backgrounds addon via a parameter. We’ll us
|
||||
We can set a parameter for a single story with the `parameters` key on a CSF export:
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
export const Primary = Template.bind({});
|
||||
Primary.args ={
|
||||
primary: true,
|
||||
@ -31,6 +33,8 @@ Primary.parameters = {
|
||||
We can set the parameters for all stories of a component using the `parameters` key on the default CSF export:
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
import Button from './';
|
||||
|
||||
export default {
|
||||
@ -49,9 +53,11 @@ export default {
|
||||
|
||||
### Global parameters
|
||||
|
||||
We can also set the parameters for **all stories** via the `parameters` export of your [`.storybook/preview.js`](../configure/overview#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
We can also set the parameters for **all stories** via the `parameters` export of your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) file (this is the file where you configure all stories):
|
||||
|
||||
```js
|
||||
// Button.story.js
|
||||
|
||||
export const parameters = {
|
||||
backgrounds: {
|
||||
values: [
|
||||
@ -73,4 +79,4 @@ The way the global, component and story parameters are combined is:
|
||||
|
||||
The merging of parameters is important. It means it is possible to override a single specific sub-parameter on a per-story basis but still retain the majority of the parameters defined globally.
|
||||
|
||||
If you are defining an API that relies on parameters (e..g an [__addon__](../api/addons#geting-started)) it is a good idea to take this behaviour into account.
|
||||
If you are defining an API that relies on parameters (e..g an [__addon__](../api/addons.md)) it is a good idea to take this behavior into account.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user