GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-05 16:11:33 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '6.0-docs' into chore_add_essential-snippets

Browse Source
This commit is contained in:
jonniebigodes 2020-08-09 21:51:22 +01:00 committed by GitHub
commit 55c00b9646
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
57 changed files with 871 additions and 1165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/api/addons-api.md
View File

@ -10,8 +10,6 @@ This is the core addon API. This is how to get the addon API:
import { addons } from '@storybook/addons';
```
Have a look at the API methods for more details:
### addons.getChannel()
Get an instance to the channel where you can communicate with the manager and the preview. You can find this in both the addon register code and in your addon’s wrapper component (where used inside a story).
@ -29,7 +27,7 @@ See how we can use this:
import { addons } from '@storybook/addons';
// Register the addon with a unique name.
addons.register('my-organisation/my-addon', api => {});
addons.register('my-organisation/my-addon', (api) => {});
```
Now you'll get an instance to our StorybookAPI. See the [api docs](#storybook-api) for Storybook API regarding using that.
@ -114,7 +112,7 @@ export const Panel = () => {
const state = useStorybookState();
return <div>do something with storybook's state</div>;
}
};
```
Allows full access to the entire storybook state.
@ -125,14 +123,13 @@ If you use this, remember your component wil be re-rendered a lot, and you may n
### useStorybookApi
```js
// my-addon/register.js
export const Panel = () => {
const state = useStorybookApi();
return <div>do something with storybook's api</div>;
}
};
```
Allows full access to the storybook API.
@ -155,7 +152,7 @@ export const Panel = () => {
clicking this will emit an event
</button>
);
}
};
```
Allows for both setting subscriptions to events and getting the emitter for emitting custom event unto the channel.
@ -170,21 +167,13 @@ The messages can be listened for on both the iframe and the manager side.
export const Panel = () => {
const [state, setState] = useAddonState('my/addon-id', 'initial state');
return (
<button onClick={() => setState('a new value')}>
the state = "{state}"
</button>
);
}
return <button onClick={() => setState('a new value')}>the state = "{state}"</button>;
};
export const Tool = () => {
const [state, setState] = useAddonState('my/addon-id', 'initial state');
return (
<button onClick={() => setState('a new value')}>
the state = "{state}"
</button>
);
}
return <button onClick={() => setState('a new value')}>the state = "{state}"</button>;
};
```
Extremely useful for addons that need to persist some state.
@ -209,7 +198,7 @@ export const Panel = () => {
{value}
</div>
);
}
};
```
This hook gets you the current story's parameter.
@ -247,7 +236,7 @@ This is how you can select the above story:
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.selectStory('heading', 'withText');
});
```
@ -259,7 +248,7 @@ Same as `selectStory`, but accepts a story inside current kind as the only param
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.selectInCurrentKind('withText');
});
```
@ -271,7 +260,7 @@ This method allows you to set query string parameters. You can use that as tempo
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.setQueryParams({
abc: 'this is abc',
bbc: 'this is bbc',
@ -285,11 +274,10 @@ If you need to remove a query param, use `null` for that. For an example, let's
</div>
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.setQueryParams({
bbc: null,
});
@ -301,7 +289,7 @@ addons.register('my-organisation/my-addon', api => {
This method allows you to get a query param set by above API `setQueryParams`. For example, let's say we need to get the bbc query param. Then this how we do it:
```jsx
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.getQueryParam('bbc');
});
```
@ -313,7 +301,7 @@ This method allows you to get application url state with some changed params. Fo
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
const href = api.getUrlState({
selectedKind: 'kind',
selectedStory: 'story',
@ -328,7 +316,7 @@ This method allows you to register a handler function which will be called whene
```js
// my-addon/register.js
addons.register('my-organisation/my-addon', api => {
addons.register('my-organisation/my-addon', (api) => {
api.on('some-event', (eventData) => console.log(eventData));
});
```

60
docs/api/addons.md
View File

@ -2,8 +2,8 @@
title: 'Addons'
---
Addons extend Storybook with features and integrations that are not built into the core. Most Storybook features are implemented as addons. For instance: documentation, accessibility testing, interactive controls, and design previews.
The addon API makes it easy for you to configure and customize Storybook in new ways. There are countless addons made by the community that unlock time-saving workflows. What addons can do:
Addons extend Storybook with features and integrations that are not built into the core. Most Storybook features are implemented as addons. For instance: documentation, accessibility testing, interactive controls, and design previews.
The addon API makes it easy for you to configure and customize Storybook in new ways. There are countless addons made by the community that unlock time-saving workflows. What addons can do:
- [Add a panel to Storybook (like Action Logger).](../essentials/actions.md)
- [Add a tool to Storybook’s toolbar (like zoom or grid).](../essentials/toolbars-and-globals.md)
@ -11,7 +11,7 @@ The addon API makes it easy for you to configure and customize Storybook in new
Browse the [Addon gallery](/addons) to install an existing addon or as inspiration for your own addon. Read on to learn how to make an addon yourself.
### Storybook basics
## Storybook basics
Before writing your first addon, let’s take a look at the basics of Storybook’s architecture. While Storybook presents a unified user interface, under the hood it’s divided down the middle into **Manager** and **Preview**.
@ -23,7 +23,7 @@ Because Manager and Preview run in separate iframes, they communicate across a c
Many of the addon APIs you’ll read about below are abstractions to help make this communication transparent.
### Getting started
## Getting started
Let’s write a simple addon for Storybook which:
@ -31,7 +31,7 @@ Let’s write a simple addon for Storybook which:
- Retrieves a custom “myAddon” parameter from stories
- Displays the parameter data in the panel
#### Add story parameters
### Add story parameters
Let’s start by writing a story for our addon that exposes a custom parameter. The idea is that our addon will show this parameter in the addon panel.
@ -53,7 +53,7 @@ export const Basic = () => <Button>hello</Button>;
Because we added the story at the component level, the `myAddon` parameter is associated with all stories defined in the file.
#### Add a panel
### Add a panel
Now let’s add a panel to Storybook in a file called `register.js`, which is the entry point for addons to register themselves.
@ -68,7 +68,7 @@ const ADDON_ID = 'myaddon';
const PANEL_ID = `${ADDON_ID}/panel`;
const MyPanel = () => <div>MyAddon</div>;
addons.register(ADDON_ID, api => {
addons.register(ADDON_ID, (api) => {
addons.add(PANEL_ID, {
type: types.PANEL,
title: 'My Addon',
@ -76,14 +76,14 @@ addons.register(ADDON_ID, api => {
<AddonPanel active={active} key={key}>
<MyPanel />
</AddonPanel>
)
),
});
});
```
This is boilerplate code for any addon that adds a panel to Storybook, and there’s really not much going on here. In this case, we’re just adding a static div that renders when the panel is selected in Storybook’s UI.
#### Display story parameter
### Display story parameter
Next, let’s replace the `MyPanel` component from above to show the parameter.
@ -94,16 +94,16 @@ import { useParameter } from '@storybook/api';
const PARAM_KEY = 'myAddon';
const MyPanel = () => {
const value = useParameter(PARAM_KEY, null);
const item = value ? value.data : "";
const item = value ? value.data : '';
return <div>{item}</div>;
}
};
```
The new version is made smarter by `useParameter`, which is a [React hook](https://reactjs.org/docs/hooks-intro.html) that updates the parameter value and re-renders the panel every time the story changes.
The addon API provides hooks like this so all of that communication can happen behind the scenes. That means you can focus on your addon's functionality.
#### Register the addon
### Register the addon
Finally, let’s hook it all up. Addons are typically published as standalone packages, but they can also be written locally in an existing Storybook project. We’ll make our addon a local addon.
@ -113,8 +113,8 @@ Update your [`.storybook/main.js`](../configure/overview.md#configure-story-rend
// .storybook/main.js
module.exports = {
addons: ['path/to/register.js']
}
addons: ['path/to/register.js'],
};
```
The path can be an absolute location on your file system, or a path relative to your `.storybook` directory (e.g. `./my-addon/register.js` if you defined the addon inside your `.storybook` folder).
@ -135,25 +135,24 @@ You may need an appropriate loader to handle this file type.
It is likely because you do not have a `.babelrc` file or do not have it configured with the correct presets:
```json
{
"presets": ["@babel/preset-env", "@babel/preset-react"]
{
"presets": ["@babel/preset-env", "@babel/preset-react"]
}
```
Now restart/rebuild Storybook and your addon should appear in the addons panel. Furthermore, as you navigate between stories, the parameter displayed should update accordingly.
#### Next steps
### Next steps
In the previous example, we introduced the structure of an addon, but barely scratched the surface of what addons can do.
To dive deeper we recommend [Learn Storybook’s “creating addons”](https://www.learnstorybook.com/intro-to-storybook/react/en/creating-addons/) tutorial. It’s an excellent walkthrough that covers the same ground as the above introduction, but goes further and leads you through the full process of creating a realistic addon.
### Addon recipes
## Addon recipes
Once you understand the basics of writing an addons, there are a variety of common enhancements to make your addon better.
#### Disabling the addon panel
### Disabling the addon panel
It’s possible to disable the addon panel for a particular story.
@ -171,6 +170,7 @@ addons.register(ADDON_ID, () => {
});
});
```
Then when adding a story, you can then pass a disabled parameter.
```js
@ -185,14 +185,14 @@ export default {
};
```
#### Styling your addon
### Styling your addon
Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling, AND we provide a theme which can be set by the user!
We recommend you also use Emotion to style your addon’s UI components. That allows you to use the active Storybook theme to deliver a seamless developer experience.
If you don’t want to use Emotion, you can use inline styles or another css-in-js lib. You can receive the theme as a prop by using the `withTheme` hoc from Emotion. [Read more about theming](../configure/theming.md).
#### Storybook components
### Storybook components
Addon authors can develop their UIs using any React library. But we recommend using Storybook’s own UI components in `@storybook/components` to build addons faster. When you use Storybook components you get:
@ -200,9 +200,9 @@ Addon authors can develop their UIs using any React library. But we recommend us
- Storybook native look and feel
- Built-in support for Storybook theming
You can check them out in [Storybook’s own storybook](https://storybookjs.netlify.app/)
You can check them out in [Storybook’s own storybook](https://storybookjs.netlify.app/)
#### Packaging
### Packaging
In the example above, we showed how to write a local addon inside an existing Storybook project. To distribute your addon for others, package the addon into a standalone NPM module.
@ -212,7 +212,7 @@ It contains addon code similar to what we’ve written above. It also contains:
- A package.json file that declares the module
- Peer dependencies of `react` and `@storybook/addons`
-A `register.js` file at the root level written as an ES5 modules
-A `register.js` file at the root level written as an ES5 modules
- A `src` directory containing the ES6 addon code
- A `dist` directory containing transpiled ES5 code on publish
@ -228,7 +228,7 @@ When you are developing your addon as a package, you can’t use npm link to add
}
```
### Addon presets
## Addon presets
Storybook presets are collections of Storybook configurations that get applied automatically when you create a `/preset.js` entry point in your addon and then list that addon in your project’s [`.storybook/main.js`](../configure/overview.md#configure-story-rendering) addons field.
@ -263,10 +263,10 @@ export const parameters = {
For more information on presets, see the [presets docs](./presets.md).
### Writing presets
## Writing presets
If you want to learn more how you can write your own presets, read the [documentation](./writing-presets.md)
### Addons API
## Addons API
If you want to expand your knowledge on the Addons API, read the [documentation](./addons-api.md)
If you want to expand your knowledge on the Addons API, read the [documentation](./addons-api.md)

2
docs/api/argtypes.md
View File

@ -8,6 +8,8 @@ NOTE: This API is experimental and may change outside of the typical semver rele
</div>
<br/>
ArgTypes are a first-class feature in Storybook for specifying the behaviour of [Args](../writing-stories/args.md). By specifying the type of an arg you constrain the values that it can take and can also provide information about args that are not explicitly set (i.e. not required).
You can also use argTypes to “annotate” args with information that is used by addons that make use of those args, for instance to instruct the controls addons to render a color choose for a string-valued arg.

6
docs/api/cli-options.md
View File

@ -4,9 +4,9 @@ title: 'CLI options'
Storybook comes with two CLI utilities: `start-storybook` and `build-storybook`.
You can pass these commands the following options to alter Storybook's behavior.
Pass these commands the following options to alter Storybook's behavior.
## For start-storybook
## start-storybook
```plaintext
Usage: start-storybook [options]
@ -31,7 +31,7 @@ Usage: start-storybook [options]
| --debug-webpack | Display final webpack configurations for debugging purposes | `start-storybook --debug-webpack` |
| --docs | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation) | `start-storybook --docs` |
## For build-storybook
## build-storybook
```plaintext
Usage: build-storybook [options]

12
docs/api/csf.md
View File

@ -2,8 +2,6 @@
title: 'Component Story Format (CSF)'
---
### Component Story Format (CSF)
Storybook's Component Story Format (CSF) is the recommended way to [write stories](../writing-stories/introduction.md) since Storybook 5.2. [Read the announcement](https://medium.com/storybookjs/component-story-format-66f4c32366df) to learn more about how it came to be.
<div style="background-color:#F8FAFC">
@ -20,7 +18,7 @@ In CSF, stories and component metadata are defined as ES Modules. Every componen
CSF is supported in all frameworks except React Native, where you should use the [storiesOf API](./storiesof.md) instead.
#### Default export
## Default export
The default export defines metadata about your component, including the `component` itself, its `title` (where it will show up in the [navigation UI story hierarchy](../writing-stories/docs/writing-stories/naming-components-and-hierarchy.md#sorting-stories)), [decorators](../writing-stories/decorators.md), and [parameters](../writing-stories/parameters.md).
@ -40,7 +38,7 @@ export default {
For more examples, see [writing stories](../writing-stories/introduction.md).
#### Named story exports
## Named story exports
With CSF, every named export in the file represents a story function by default.
@ -83,7 +81,7 @@ Simple.decorators = [ ... ];
Simple.parameters = { ... };
```
#### Args story inputs
## Args story inputs
Starting in SB 6.0, stories accept named inputs called Args. Args are dynamic data that are provided (and possibly updated by) Storybook and its addons.
@ -128,7 +126,7 @@ Not only are these versions shorter and easier to write than their no-args count
For more information on setting up [Docs](../writing-docs/introduction.md) and [Actions](../essentials/actions.md), see their respective documentation.
#### Storybook export vs name handling
## Storybook export vs name handling
Storybook handles named exports and `story.name` slightly differently. When should you use one vs. the other?
@ -161,7 +159,7 @@ You should use the `story.name` option in the following cases:
1. You want the name to show up in the Storybook UI in a way that's not possible with a named export, e.g. reserved keywords like "default", special characters like emoji, spacing/capitalization other than what's provided by `storyNameFromExport`.
2. You want to preserve the Story ID independently from changing how it's displayed. Having stable Story ID's is useful for integration with third party tools.
#### Non-story exports
## Non-story exports
In some cases, you may want to export a mixture of story and non-stories. For example, it can be useful to export data that's used in your stories.

135
docs/api/frameworks-feature-support.md
View File

@ -2,78 +2,85 @@
title: 'Feature support for frameworks'
---
Storybook integrates with many popular frontend frameworks. We do our best to keep feature parity amongst frameworks, but it’s tricky for our modest team to support every framework.
Storybook integrates with many popular frontend frameworks. We do our best to keep feature parity amongst frameworks, but it’s tricky for our modest team to support every framework.
Below is a comprehensive table of what’s supported in which framework integration. If you’d like a certain feature supported in your framework, we welcome pull requests.
Below is a comprehensive table of what’s supported in which framework integration. If you’d like a certain feature supported in your framework, we welcome pull requests.
### Core frameworks
## Core frameworks
Core frameworks have dedicated maintainers or contributors who are responsible for maintaining the integration. As such, you can use most Storybook features in these frameworks.
| |[React](app/react)|[Vue](app/vue)| [Angular](app/angular) | [HTML](app/html) | [Ember](app/ember) |
|--------------------------------------------|:----------------:|:-------------:|:----------------------:|:------------------:|:-------------------:|
|Addons | | | | | |
| [a11y](addons/a11y) |+ |+ |+ |+ |+ |
| [actions](addons/actions) |+ |+ |+ |+ |+ |
| [backgrounds](addons/backgrounds) | + |+ |+ |+ |+ |
| [cssresources](addons/cssresources) | + |+ |+ |+ |+ |
| [design assets](addons/design-assets) | + |+ |+ |+ |+ |
| [docs](addons/docs) | + |+ |+ |+ |+ |
| [events](addons/events) | + |+ |+ |+ |+ |
| [google-analytics](addons/google-analytics)| + |+ |+ |+ |+ |
| [graphql](addons/graphql) | + | |+ | | |
| [jest](addons/jest) | + |+ |+ |+ |+ |
| [knobs](addons/knobs) | + |+ |+ |+ |+ |
| [links](addons/links) | + |+ |+ |+ |+ |
| [options](addons/options) | + |+ |+ |+ |+ |
| [query params](addons/queryparams) | + |+ |+ |+ |+ |
| [storyshots](addons/storyshots) | + |+ |+ |+ | |
| [storysource](addons/storysource) | + |+ |+ |+ |+ |
| [viewport](addons/viewport) | + |+ |+ |+ |+ |
| Docs | | | | | |
| MDX Stories | + |+ |+ |+ |+ |
| CSF Stories | + |+ |+ |+ |+ |
| StoriesOf Stories | + |+ |+ |+ |+ |
| Source | + |+ |+ |+ |+ |
| Notes/Info | + |+ |+ | |+ |
| Props table | + |+ |+ |+ |+ |
| Props controls | + |+ | | | |
| Description | + |+ |+ | |+ |
| Inline stories | + |+ | | | |
NEW:
<FrameworkSupportTable frameworks={['react', 'vue', 'angular', 'html', 'ember']} />
ORIGINAL:
| | [React](app/react) | [Vue](app/vue) | [Angular](app/angular) | [HTML](app/html) | [Ember](app/ember) |
| ------------------------------------------- | :----------------: | :------------: | :--------------------: | :--------------: | :----------------: |
| Addons | | | | | |
| [a11y](addons/a11y) | + | + | + | + | + |
| [actions](addons/actions) | + | + | + | + | + |
| [backgrounds](addons/backgrounds) | + | + | + | + | + |
| [cssresources](addons/cssresources) | + | + | + | + | + |
| [design assets](addons/design-assets) | + | + | + | + | + |
| [docs](addons/docs) | + | + | + | + | + |
| [events](addons/events) | + | + | + | + | + |
| [google-analytics](addons/google-analytics) | + | + | + | + | + |
| [graphql](addons/graphql) | + | | + | | |
| [jest](addons/jest) | + | + | + | + | + |
| [knobs](addons/knobs) | + | + | + | + | + |
| [links](addons/links) | + | + | + | + | + |
| [options](addons/options) | + | + | + | + | + |
| [query params](addons/queryparams) | + | + | + | + | + |
| [storyshots](addons/storyshots) | + | + | + | + | |
| [storysource](addons/storysource) | + | + | + | + | + |
| [viewport](addons/viewport) | + | + | + | + | + |
| Docs | | | | | |
| MDX Stories | + | + | + | + | + |
| CSF Stories | + | + | + | + | + |
| StoriesOf Stories | + | + | + | + | + |
| Source | + | + | + | + | + |
| Notes/Info | + | + | + | | + |
| Props table | + | + | + | + | + |
| Props controls | + | + | | | |
| Description | + | + | + | | + |
| Inline stories | + | + | | | |
## Community frameworks
### Community frameworks
Community frameworks have fewer contributors which means they may not be as up to date as core frameworks. If you use one of these frameworks for your job, please consider contributing to its integration with Storybook.
Community frameworks have fewer contributors which means they may not be as up to date as core frameworks. If you use one of these frameworks for your job, please consider contributing to its integration with Storybook.
NEW:
<FrameworkSupportTable frameworks={['mithril', 'marko', 'svelte', 'riot', 'preact', 'rax']} />
| |[Mithril](app/mithril)|[Marko](app/marko)|[Svelte](app/svelte)|[Riot](app/riot)|[Preact](app/preact)|[Rax](app/rax)
| -------------------------------------------|:---------------------:|:----------------:|:-----------------:|:---------------:|:-----------------:|-----|
| [a11y](addons/a11y) |+ |+ |+ |+ |+ |+ |
| [actions](addons/actions) |+ |+ |+ |+ |+ |+ |
| [backgrounds](addons/backgrounds) | + |+ |+ |+ |+ |+ |
| [cssresources](addons/cssresources) | + |+ |+ |+ |+ |+ |
| [design assets](addons/design-assets) | + |+ |+ |+ |+ |+ |
| [docs](addons/docs) | + |+ |+ |+ |+ |+ |
| [events](addons/events) | + |+ | | |+ |+ |
| [google-analytics](addons/google-analytics)| + |+ |+ |+ |+ |+ |
| [graphql](addons/graphql) | | | | | | |
| [jest](addons/jest) | + |+ |+ |+ |+ |+ |
| [knobs](addons/knobs) | + |+ |+ |+ |+ |+ |
| [links](addons/links) | + | |+ |+ |+ |+ |
| [options](addons/options) | + | |+ |+ |+ |+ |
| [query params](addons/queryparams) | + |+ |+ |+ |+ |+ |
| [storyshots](addons/storyshots) | | |+ |+ | |+ |
| [storysource](addons/storysource) | + |+ |+ |+ |+ |+ |
| [viewport](addons/viewport) | + |+ |+ |+ |+ |+ |
| Docs | | | | | | |
| MDX Stories | + |+ |+ |+ |+ |+ |
| CSF Stories | + |+ |+ |+ |+ |+ |
| StoriesOf Stories | + |+ |+ |+ |+ |+ |
| Source | + |+ |+ |+ |+ |+ |
| Notes/Info | + |+ |+ | |+ |+ |
| Props table | | | | | |+ |
| Props controls | | | | | |+ |
| Description | | | | | |+ |
| Inline stories | | | | | |+ |
ORIGINAL:
| | [Mithril](app/mithril) | [Marko](app/marko) | [Svelte](app/svelte) | [Riot](app/riot) | [Preact](app/preact) | [Rax](app/rax) |
| ------------------------------------------- | :--------------------: | :----------------: | :------------------: | :--------------: | :------------------: | -------------- |
| [a11y](addons/a11y) | + | + | + | + | + | + |
| [actions](addons/actions) | + | + | + | + | + | + |
| [backgrounds](addons/backgrounds) | + | + | + | + | + | + |
| [cssresources](addons/cssresources) | + | + | + | + | + | + |
| [design assets](addons/design-assets) | + | + | + | + | + | + |
| [docs](addons/docs) | + | + | + | + | + | + |
| [events](addons/events) | + | + | | | + | + |
| [google-analytics](addons/google-analytics) | + | + | + | + | + | + |
| [graphql](addons/graphql) | | | | | | |
| [jest](addons/jest) | + | + | + | + | + | + |
| [knobs](addons/knobs) | + | + | + | + | + | + |
| [links](addons/links) | + | | + | + | + | + |
| [options](addons/options) | + | | + | + | + | + |
| [query params](addons/queryparams) | + | + | + | + | + | + |
| [storyshots](addons/storyshots) | | | + | + | | + |
| [storysource](addons/storysource) | + | + | + | + | + | + |
| [viewport](addons/viewport) | + | + | + | + | + | + |
| Docs | | | | | | |
| MDX Stories | + | + | + | + | + | + |
| CSF Stories | + | + | + | + | + | + |
| StoriesOf Stories | + | + | + | + | + | + |
| Source | + | + | + | + | + | + |
| Notes/Info | + | + | + | | + | + |
| Props table | | | | | | + |
| Props controls | | | | | | + |
| Description | | | | | | + |
| Inline stories | | | | | | + |

15
docs/api/mdx.md
View File

@ -2,11 +2,9 @@
title: 'MDX Format'
---
### MDX format
`MDX` is the syntax [Storybook Docs](../writing-docs/introduction.md) uses to capture long-form Markdown documentation and stories in one file. You can also write pure documentation pages in `MDX` and add them to Storybook alongside your stories. [Read the announcement](https://medium.com/storybookjs/rich-docs-with-storybook-mdx-61bc145ae7bc) to learn more about how and why it came to be.
#### Basic example
## Basic example
Let's get started with an example that combines Markdown with a single story:
@ -30,6 +28,7 @@ With `MDX` we can define a story for `Checkbox` right in the middle of our Markd
</Story>
</Preview>
```
And here's how that's rendered in Storybook:
![Show a simple mdx example](./mdx-simple.png)
@ -38,7 +37,7 @@ As you can see there's a lot going on here. We're writing Markdown, we're writin
Let's break it down.
#### MDX-Flavored CSF
## MDX-Flavored CSF
[MDX](https://mdxjs.com/) is a standard file format that combines Markdown with JSX. This means you can use Markdown’s terse syntax (such as `# heading`) for your documentation, and freely embed JSX component blocks at any point in the file.
@ -61,7 +60,7 @@ export const allCheckboxes = () => (
There's a one-to-one mapping from the code in `MDX` to `CSF`, which in turn directly corresponds to Storybook's internal `storiesOf` API. As a user, this means your existing Storybook knowledge should translate between the three. And technically, this means that the transformations that happen under the hood are simple and predictable.
#### Writing stories
## Writing stories
Now let's look at a more realistic example to see a few more things we can do:
@ -158,7 +157,7 @@ addDecorator(...);
addParameters({ ... });
```
#### Documentation-only MDX
## Documentation-only MDX
Typically, when you use Storybook MDX, you define stories in the MDX documentation is automatically associated with those stories. But what if you want to write Markdown-style documentation and have it show up in your Storybook?
@ -168,11 +167,9 @@ If you don't define a `Meta`, you can write Markdown and associate with an exist
To get a "documentation-only story", in your UI, define a `<Meta>` as you normally would, but don't define any stories. It will show up in your UI as a documentation node:
![Show documentation](./mdx-documentation-only.png)
### MDX file names
## MDX file names
Unless you use a custom webpack configuration, 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.

56
docs/api/new-frameworks.md
View File

@ -4,7 +4,7 @@ title: 'Frameworks'
Storybook is architected to support diverse web frameworks including React, Vue, Angular, Web Components, Svelte and over a dozen others. This guide helps you get started on adding new framework support for Storybook.
### Scaffolding a new framework
## Scaffolding a new framework
The first thing to do is scaffold your framework support in its own repo.
@ -14,7 +14,7 @@ This may seem like a little more hierarchy than what’s necessary. But because
We recommend using `@storybook/html` as a starter framework since it’s the simplest one and doesn’t contain any framework-specific oddities. There is a boilerplate to get you started [here](https://github.com/CodeByAlex/storybook-framework-boilerplate):
### Framework architecture
## Framework architecture
Supporting a new framework in Storybook typically consists of two main aspects:
@ -22,22 +22,21 @@ Supporting a new framework in Storybook typically consists of two main aspects:
2. Configuring the client. The client is the code that runs in the browser. Configuring the client means providing a framework-specific story rendering function.
### Configuring the server
## Configuring the server
Storybook has the concept of [presets](./addons.md#addon-presets), which are typically babel/webpack configurations for file loading. If your framework has its own file format, e.g. “.vue,” you might need to transform these files into JS files at load time. If you expect every user of your framework to need this, you should add it to the framework. So far every framework added to Storybook has done this, because Storybook’s core configuration is very minimal.
#### Package structure
### Package structure
To add a framework preset, it’s useful to understand the package structure. Each framework typically exposes two executables in its `package.json`:
```json
{
"bin": {
"bin": {
"start-storybook": "./bin/index.js",
"build-storybook": "./bin/build.js",
},
"build-storybook": "./bin/build.js"
}
}
```
These scripts pass an `options` object to `@storybook/core/server`, a library that abstracts all of Storybook’s framework-independent code.
@ -53,7 +52,7 @@ buildDev(options);
Thus the meat of adding framework presets is filling in that options object.
#### Server options
### Server options
As described above, the server `options` object does the heavy lifting of configuring the server.
@ -73,12 +72,11 @@ The value of the `framework` option (in this case ‘vue’) is something that g
The real meat of this file is the framework presets, and these are standard [Storybook presets](./addons.md#addon-presets) -- you can look at framework packages in the Storybook monorepo (e.g. [react](https://github.com/storybookjs/storybook/blob/next/app/react/src/server/options.ts), [vue](https://github.com/storybookjs/storybook/blob/next/app/vue/src/server/options.ts), [web-components](https://github.com/storybookjs/storybook/blob/next/app/web-components/src/server/options.ts)) to see examples of framework-specific customizations.
### Configuring the client
## Configuring the client
To configure the client, you must provide a framework specific render function. Before diving into the details, it’s important to understand how user-written stories relate to what is finally rendered on the screen.
#### Renderable objects
### Renderable objects
Storybook stories are ES6 functions that return a “renderable object.”
@ -87,19 +85,17 @@ Consider the following React story:
```js
// Button.story.js
import { Button } from './Button';
export default {
title: 'Button',
component: Button
}
export default {
title: 'Button',
component: Button,
};
export const Sample = () => (
<Button label='hello button' />
);
export const Sample = () => <Button label="hello button" />;
```
In this case, the renderable object is the React element, `<Button .../>`.
In most other frameworks, the renderable object is actually a plain javascript object.
In most other frameworks, the renderable object is actually a plain javascript object.
Consider the following hypothetical example:
@ -107,37 +103,35 @@ Consider the following hypothetical example:
// Button.story.js
import { Button } from './Button';
export default {
title: 'Button',
component: Button
}
export default {
title: 'Button',
component: Button,
};
export const Sample = () => ({
template: '<button label=:label />',
data: {
label: 'hello button'
}
label: 'hello button',
},
});
```
The design of this “renderable object” is framework-specific, and should ideally match the idioms of that framework.
#### Render function
### Render function
The frameworks render function is the thing responsible for converting the renderable object into DOM nodes. This is typically of the form:
```js
const rootElement = document.getElementById('root');
export default function renderMain({
storyFn,
}: RenderMainArgs) {
export default function renderMain({ storyFn }: RenderMainArgs) {
const storyObj = storyFn();
const html = fn(storyObj);
rootElement.innerHTML = html;
}
```
#### Package structure
### Package structure
On the client side, the key file is [`src/client/preview.js`](../configure/overview.md#configure-story-rendering):

113
docs/configure/integration.md
View File

@ -2,7 +2,7 @@
title: 'Integration'
---
### Webpack
## Webpack
Storybook displays your components in a custom web application built using [webpack](https://webpack.js.org/). Webpack is a complex tool but our default configuration is intended to cover off the majority of use cases. There are also [addons](/addons) available that extend the configuration for other common use cases.
@ -10,27 +10,27 @@ You can customize Storybook's webpack setup by providing a `webpackFinal` field
The value should be an async function that receives a webpack config and eventually returns a webpack config.
#### Default configuration
### Default configuration
By default, Storybook's webpack configuration will allow you to:
- Import Images and other static files
You can import images and other local files and have them built into the Storybook:
You can import images and other local files and have them built into the Storybook:
```js
// This will include './static/image.png' in the bundle and return a path to be included in a src attribute
import imageFile from './static/image.png';
```
```js
// This will include './static/image.png' in the bundle and return a path to be included in a src attribute
import imageFile from './static/image.png';
```
- Import JSON as JavaScript
You can import `.json` files and have them expanded to a JavaScript object:
You can import `.json` files and have them expanded to a JavaScript object:
```js
// This will automatically be parsed to the contents of `data.json`
import data from './data.json';
```
```js
// This will automatically be parsed to the contents of `data.json`
import data from './data.json';
```
If you want to know the exact details of the webpack config, the best way is to run:
@ -38,7 +38,7 @@ If you want to know the exact details of the webpack config, the best way is to
yarn storybook --debug-webpack
```
#### Extending Storybook’s webpack config
### Extending Storybook’s webpack config
To extend the above configuration, use the `webpackFinal` field of [`.storybook/main.js`](./overview.md#configure-story-rendering).
@ -93,7 +93,7 @@ Finally, if your custom webpack config uses a loader that does not explicitly in
If you're using a non-standard Storybook config directory, you should put `main.js` there instead of `.storybook` and update the `include` path to make sure that it resolves to your project root.
#### Using your existing config
### Using your existing config
If you have an existing webpack config for your project and want to reuse this app's configuration, you can import your main webpack config into Storybook's [`.storybook/main.js`](./overview.md#configure-story-rendering) and merge both:
@ -113,13 +113,13 @@ module.exports = {
};
```
### Babel
## Babel
Storybook’s webpack config by [default](#default-configuration) sets up [Babel](https://babeljs.io/) for ES6 transpiling. Storybook works with evergreen browsers and IE11 by default.
Here are some key features of Storybook's Babel configurations.
#### Default configuration
### Default configuration
We have added ES2016 support with Babel for transpiling your JS code.
@ -127,18 +127,17 @@ In addition to that, we've added a few additional features, like object spreadin
Check out our [source](https://github.com/storybookjs/storybook/blob/master/lib/core/src/server/common/babel.js) to learn more about these plugins.
#### Custom configuration
### Custom configuration
If your project has a `.babelrc` file, we'll use that instead of the default config file.
You can also place a `.storybook/.babelrc` file to use a special configuration for Storybook only.
### TypeScript
## TypeScript
Storybook has built-in Typescript support, so your Typescript project should work with zero configuration needed.
#### Default configuration
### Default configuration
The base Typescript configuration uses [`babel-loader`](https://webpack.js.org/loaders/babel-loader/) for Typescript transpilation, and optionally [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) for checking.
@ -148,8 +147,7 @@ Each framework uses the base configuration unless otherwise specified:
- Vue ignores the base and uses `ts-loader` and applies it to both `.tsx` and `.vue` files.
- React adds `react-docgen-typescript-plugin` to the base.
#### Main.js configuration
### Main.js configuration
To make it easier to configure Typescript handling, use the `typescript` field in your [`.storybook/main.js`](./overview.md#configure-story-rendering).
@ -170,47 +168,44 @@ module.exports = {
};
```
|Field |Framework |Description |Type |
|:-------------------------------|:------------:|:---------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------:|
|**check** |All |optionally run fork-ts-checker-webpack-plugin |boolean |
|**checkOptions** |All |Options to pass to fork-ts-checker-webpack-plugin if it's enabled |[See docs](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) |
|**reactDocgen** |React |which variant docgen processor to run `'react-docgen-typescript' |N/A |
|**reactDocgenTypescriptOptions**|React |Options to pass to react-docgen-typescript-plugin if react-docgen-typescript is enabled. |[See docs](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) |
| Field | Framework | Description | Type |
| :------------------------------- | :-------: | :--------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------: |
| **check** | All | optionally run fork-ts-checker-webpack-plugin | boolean |
| **checkOptions** | All | Options to pass to fork-ts-checker-webpack-plugin if it's enabled | [See docs](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) |
| **reactDocgen** | React | which variant docgen processor to run `'react-docgen-typescript' |N/A |
| **reactDocgenTypescriptOptions** | React | Options to pass to react-docgen-typescript-plugin if react-docgen-typescript is enabled. | [See docs](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) |
### Styling and CSS
## Styling and CSS
There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually it is best to try and replicate what your application does with styling in Storybook’s configuration.
#### CSS-in-JS
### CSS-in-JS
CSS-in-JS libraries are designed to use basic JavaScript. They often work in Storybook without any extra configuration. Some libraries expect components to be rendered in a specific rendering “context” (for example, to provide themes) and you may need to add a [global decorator](../writing-stories/decorators.md#global-decorators) to supply it.
#### Importing CSS files
### Importing CSS files
If your component files import their own CSS, Storybook’s webpack config will work unmodified with some exceptions:
- If you are using a CSS precompiler, you may need to add a preset (such as the [SCSS preset](https://github.com/storybookjs/presets/tree/master/packages/preset-scss), or add a loader to Storybook’s webpack config).
- In Angular, you'll need to take special care how you handle CSS:
- Either [customize your webpack config](#extending-storybooks-webpack-config)
- Or use syntax to use a inline loader:
```js
import '!style-loader!css-loader!./styles.css';
```
- Either [customize your webpack config](#extending-storybooks-webpack-config)
- Or use syntax to use a inline loader:
```js
import '!style-loader!css-loader!./styles.css';
```
To use your CSS in all stories, you simply import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering)
#### Adding webfonts
### Adding webfonts
If you need webfonts to be available, you may need to add some code to the [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head) file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the [static file location](#serving-static-files-via-storybook).
### Images and assets
## Images and assets
Components often rely on images, videos, and other assets to render as the user expects. There are many ways to use these assets in your story files.
Components often rely on images, videos, and other assets to render as the user expects. There are many ways to use these assets in your story files.
#### Import assets into stories
### Import assets into stories
You can import any media assets by importing (or requiring) them. This works out of the box with our default config. But, if you are using a custom webpack config, you’ll need to add the file-loader to handle the required files.
@ -231,23 +226,20 @@ const image = {
alt: 'my image',
};
export const withAnImage = () => (
<img src={image.src} alt={image.alt} />
);
export const withAnImage = () => <img src={image.src} alt={image.alt} />;
```
### Serving static files via Storybook
#### Serving static files via Storybook
We recommend serving static files via Storybook to ensure that your components always have the assets they need to load.
We recommend serving static files via Storybook to ensure that your components always have the assets they need to load.
Configure a directory (or a list of directories) where your assets live when starting Storybook. Use the` -s` flag in your npm script like so:
Configure a directory (or a list of directories) where your assets live when starting Storybook. Use the`-s` flag in your npm script like so:
```json
{
"scripts": {
"start-storybook": "start-storybook -s ./public -p 9001"
}
"scripts": {
"start-storybook": "start-storybook -s ./public -p 9001"
}
}
```
@ -263,22 +255,20 @@ export default {
};
// assume image.png is located in the "public" directory.
export const withAnImage = () => (
<img src="/image.png" alt="my image" />
);
export const withAnImage = () => <img src="/image.png" alt="my image" />;
```
You can also pass a list of directories separated by commas without spaces instead of a single directory.
```json
{
"scripts": {
"start-storybook": "start-storybook -s ./public,./static -p 9001"
}
"scripts": {
"start-storybook": "start-storybook -s ./public,./static -p 9001"
}
}
```
#### Reference assets from a CDN
### Reference assets from a CDN
Upload your files to an online CDN and reference them. In this example we’re using a placeholder image service.
@ -297,8 +287,7 @@ export const withAnImage = () => (
);
```
#### Absolute versus relative paths
### Absolute versus relative paths
Sometimes, you may want to deploy your storybook into a subpath, like `https://example.com/storybook`.

21
docs/configure/overview.md
View File

@ -1,8 +1,8 @@
---
title: 'Overview'
title: 'Configure Storybook'
---
Storybook is configured via a folder, called `.storybook` which contains various configuration files.
Storybook is configured via a folder, called `.storybook` which contains various configuration files.
<div class="aside">
@ -10,8 +10,7 @@ Note you can change the folder that Storybook uses by setting the `-c` flag to y
</div>
### Configure your Storybook project
## Configure your Storybook project
The main configuration file is `main.js`. This file controls the behaviour of the Storybook server, and so you must restart Storybook’s process when you change it. It contains the following:
@ -20,8 +19,8 @@ The main configuration file is `main.js`. This file controls the behaviour of th
module.exports = {
stories: ['../src/**/*.stories.(js|mdx)'],
addons: ['@storybook/addon-essentials']
}
addons: ['@storybook/addon-essentials'],
};
```
The `main.js` configuration file is a [preset](../api/presets.md) and as such has a powerful interface, but the key fields within it are:
@ -31,7 +30,7 @@ The `main.js` configuration file is a [preset](../api/presets.md) and as such ha
- `webpackFinal` - custom [webpack configuration](./integration.md#extending-storybooks-webpack-config).
- `babel` - custom [babel configuration](./integration.md#babel).
### Configure story loading
## Configure story loading
By default, Storybook will load stories from your project based on a glob (pattern matching string) in `.storybook/main.js` that matches all files in your project with extension `.stories.js`. The intention is you colocate a story file with the component it documents.
@ -54,11 +53,11 @@ module.exports = {
};
```
### Configure story rendering
## Configure story rendering
To control the way stories are rendered and add global [decorators](../writing-stories/decorators.md#global-decorators) and [parameters](../writing-stories/parameters.md#global-parameters), create a `.storybook/preview.js` file. This is loaded in the Canvas tab, the “preview” iframe that renders your components in isolation. Use `preview.js` for global code (such as [CSS imports](../get-started/setup.md#render-component-styles) or JavaScript mocks) that applies to all stories.
To control the way stories are rendered and add global [decorators](../writing-stories/decorators.md#global-decorators) and [parameters](../writing-stories/parameters.md#global-parameters), create a `.storybook/preview.js` file. This is loaded in the Canvas tab, the “preview” iframe that renders your components in isolation. Use `preview.js` for global code (such as [CSS imports](../get-started/setup.md#render-component-styles) or JavaScript mocks) that applies to all stories.
The `preview.js` file can be an ES module and export the following keys:
The `preview.js` file can be an ES module and export the following keys:
- `decorators` - an array of global [decorators](../writing-stories/decorators.md#global-decorators)
- `parameters` - an object of global [parameters](..writing-stories/parameters.md#global-parameters)
@ -66,7 +65,7 @@ The `preview.js` file can be an ES module and export the following keys:
If you’re looking to change how your stories are ordered, read about [sorting stories](../writing-stories/naming-components-and-hierarchy.md#sorting-stories).
### Configure Storybook’s UI
## Configure Storybook’s UI
To control the behaviour of Storybook’s UI (the **“manager”**), you can create a `.storybook/manager.js` file.

14
docs/configure/sidebar-and-urls.md
View File

@ -8,13 +8,13 @@ Storybook’s sidebar lists all your stories grouped by component. When you have
We recommend using a nesting scheme that mirrors the filesystem path of the components. For example, if you have a file `components/modals/Alert.js` name the CSF file `components/modals/Alert.stories.js` and title it `Components/Modals/Alert`.
#### Roots
## Roots
By default, Storybook will treat your highest level of groups as “roots”--which are displayed in the UI as “sections” of the hierarchy. Lower level groups are displayed as expandable items in the hierarchy:
![Storybook sidebar story roots](./sidebar-roots.jpg)
If you’d prefer all groups to be expandable, you can set the `showRoots` option to `false` in [`./storybook/manager.js`](./overview.md#configure-story-rendering):
If you’d prefer all groups to be expandable, you can set the `showRoots` option to `false` in [`./storybook/manager.js`](./overview.md#configure-story-rendering):
```js
// ./storybook/manager.js
@ -23,18 +23,18 @@ import { addons } from `@storybook/addons`;
addons.setConfig({ showRoots: false });
```
#### Generating titles based on `__dirname`
## Generating titles based on `__dirname`
As a CSF file is a JavaScript file, the exports (including the default export) can be generated dynamically. In particular you can use the `__dirname` variable to generate the title based on the path name (this example uses the paths.macro):
```js
import base from 'paths.macro';
export default {
title: `${base}/Component`
}
title: `${base}/Component`,
};
```
#### Permalinking to stories
## Permalinking to stories
By default, Storybook generates an `id` for each story based on the component title and the story name. This `id` in particular is used in the URL for each story and that URL can serve as a permalink (especially when you [publish](../workflows/publish-storybook.md) your Storybook).
@ -66,4 +66,4 @@ export const Baz = () => BarStory.bind({});
Baz.storyName = 'Moo';
```
Storybook will prioritize the `id` over the title for ID generation, if provided, and will prioritize the `story.name` over the export key for display.
Storybook will prioritize the `id` over the title for ID generation, if provided, and will prioritize the `story.name` over the export key for display.

12
docs/configure/story-rendering.md
View File

@ -4,8 +4,7 @@ title: 'Story rendering'
In Storybook, your stories render in a special “preview” iframe (Canvas tab) inside the larger Storybook web application. The JavaScript build configuration of the preview is controlled by a [webpack](./integration.md#default-configuration) config, but you also may want to directly control the HTML that is rendered to help your stories render correctly.
### Adding to &#60;head&#62;
## Adding to &#60;head&#62;
If you need to add extra elements to the `head` of the preview iframe, for instance to load static stylesheets, font files, or similar, you can create a file called [`.storybook/preview-head.html`](./overview.md#configure-story-rendering) and add tags like this:
@ -16,7 +15,11 @@ If you need to add extra elements to the `head` of the preview iframe, for insta
<link rel=”preload” href=”your/font” />
<!-- Or you can load custom head-tag JavaScript: -->
<script src="https://use.typekit.net/xxxyyy.js"></script>
<script>try{ Typekit.load(); } catch(e){ }</script>
<script>
try {
Typekit.load();
} catch (e) {}
</script>
```
<div class="aside">
@ -25,7 +28,7 @@ Storybook will inject these tags into the _preview iframe_ where your components
</div>
### Adding to &#60;body&#62;
## Adding to &#60;body&#62;
Sometimes, you may need to add different tags to the `<body>`. This is useful for adding some custom content roots.
@ -51,4 +54,3 @@ If using relative sizing in your project (like `rem` or `em`), you may update th
Storybook will inject these tags into the _preview iframe_ where your components are rendered not the Storybook application UI.
</div>

13
docs/configure/storybook-addons.md
View File

@ -2,14 +2,13 @@
title: 'Storybook Addons'
---
A key strength of Storybook is its extensibility. Use addons to extend and customize Storybook to fit your team’s development workflow.
Addons are integral to the way Storybook works. Many of Storybook's core features are implemented as addons! These addons are installed out of the box with [essentials](../essentials/introduction.md).
Addons are integral to the way Storybook works. Many of Storybook's core features are implemented as addons! These addons are installed out of the box with [essentials](../essentials/introduction.md).
#### Addon features
## Addon features
The most obvious thing addons affect in Storybook is the UI of Storybook itself. Within the UI the **toolbar** and **addons panel** are the two chief places addons will appear.
The most obvious thing addons affect in Storybook is the UI of Storybook itself. Within the UI the **toolbar** and **addons panel** are the two chief places addons will appear.
![Storybook addons locations](./addon-locations.jpg)
@ -17,10 +16,10 @@ Addons can also hook into the rendering of your story in the preview pane via in
Finally, addons can affect the build setup of Storybook by injecting their own webpack configuration to allow the use of other tools in Storybook. Addons that do only this are often referred to as [presets](../api/presets.md).
### Essential, core and community addons
## Essential, core and community addons
There are many, many Storybook addons, but they can be roughly categorized into three areas:
- **Essential** addons are core-team developed addons that are considered a part of the out-of-the-box user experience. These ship by default with new Storybook installations.
- **Core** addons are developed by the core team. They are kept in sync with the development of Storybook itself and written in idiomatic ways as templates for other addons. They can be found within the [Storybook monorepo](https://github.com/storybookjs/storybook/tree/next/addons).
- **Community** addons are addons written by the massive Storybook community. They can be found on our [website](/addons), [GitHub](https://github.com/), and [npm](https://www.npmjs.com/).
- **Core** addons are developed by the core team. They are kept in sync with the development of Storybook itself and written in idiomatic ways as templates for other addons. They can be found within the [Storybook monorepo](https://github.com/storybookjs/storybook/tree/next/addons).
- **Community** addons are addons written by the massive Storybook community. They can be found on our [website](/addons), [GitHub](https://github.com/), and [npm](https://www.npmjs.com/).

19
docs/configure/theming.md
View File

@ -4,7 +4,7 @@ title: 'Theming'
Storybook is theme-able using a lightweight theming API.
#### Global theming
## Global theming
It's possible to theme Storybook globally.
@ -31,7 +31,7 @@ addons.setConfig({
When setting a theme, set a full theme object. The theme is replaced, not combined.
### Theming docs
## Theming docs
[Storybook Docs](../writing-docs) uses the same theme system as Storybook’s UI, but is themed independently from the main UI.
@ -64,7 +64,7 @@ export const parameters = {
Continue to read if you want to learn how to create your theme.
### Create a theme quickstart
## Create a theme quickstart
The easiest way to customize Storybook is to generate a new theme using the `create()` function from `storybook/theming`. This function includes shorthands for the most common theme variables. Here's how to use it:
@ -142,7 +142,7 @@ export default create({
});
```
### CSS escape hatches
## CSS escape hatches
The Storybook theme API is narrow by design. If you want to have fine-grained control over the CSS, all of the UI and Docs components are tagged with class names to make this possible. This is advanced usage: **use at your own risk**.
@ -157,10 +157,9 @@ Similar to changing the preview’s head tag, `.storybook/manager-head.html` all
WARNING: we don’t make any guarantees about the structure of Storybook’s HTML and it could change at any time. Consider yourself warned!
</div>
</div>
### MDX component overrides
## MDX component overrides
If you're using MDX for docs, there's one more level of themability. MDX allows you to completely override the components that are rendered from Markdown using a components parameter. This is an advanced usage that we don't officially support in Storybook, but it's a powerful mechanism if you need it.
@ -198,7 +197,7 @@ export const parameters = {
};
```
### Addons and theme creation
## Addons and theme creation
Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community, make sure to support the official API and other popular addons so your users have a consistent experience.
@ -213,7 +212,7 @@ addonActionsTheme: {
}
```
### Using the theme for addon authors
## Using the theme for addon authors
Reuse the theme variables above for a native Storybook developer experience. The theming engine relies on [emotion](https://emotion.sh/), a CSS-in-JS library.
@ -237,4 +236,4 @@ const Component = styled.div`
background: `${props => props.theme.background.app}`
width: 0;
`;
```
```

2
docs/essentials/introduction.md
View File

@ -1,5 +1,5 @@
---
title: 'Introduction'
title: 'Essential addons'
---
A major strength of Storybook are [addons](/addons/) that extend Storybook’s UI and behavior. There are many third-party addons as well as “official” addons developed by the Storybook core team. Storybook ships by default with a set of “essential” addons that add to the initial user experience.

34
docs/essentials/toolbars-and-globals.md
View File

@ -8,13 +8,11 @@ Storybook ships with toolbar items to control the [viewport](./viewport.md) and
Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`), but typically you use them in decorators which apply to all stories.
When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.
Let’s see how.
When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.
### Global types and the toolbar annotation
Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
<!-- prettier-ignore-start -->
@ -29,7 +27,7 @@ Storybook has a simple, declarative syntax for configuring toolbar menus. In you
<div class="aside">
As globals are *global* you can *only* set `globalTypes` in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
As globals are _global_ you can _only_ set `globalTypes` in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
</div>
@ -53,9 +51,9 @@ For example, suppose you are using `styled-components`. You can add a theme prov
### Advanced usage
So far we've managed to create and consume a global inside Storybook.
So far we've managed to create and consume a global inside Storybook.
Now let's take a look at a more complex example. Let's suppose we wanted to implement a new global called __locale__ for internationalization, which shows a flag on the right side of the toolbar.
Now let's take a look at a more complex example. Let's suppose we wanted to implement a new global called **locale** for internationalization, which shows a flag on the right side of the toolbar.
In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), add the following:
@ -73,21 +71,21 @@ By adding the the configuration element `right`, the text will displayed on the
Here's a list of the configuration options available.
| MenuItem | Type | Description | Required |
| ------------- |:-------------:|:------------------------------------------------------------:|:--------:|
| **value** | String |The string value of the menu that gets set in the globals |Yes |
| **title** | String |The main text of the title |Yes |
| **left** | String |A string that gets shown in left side of the menu |No |
| **right** | String |A string that gets shown in right side of the menu |No |
| **icon** | String |An icon that gets shown in the toolbar if this item is selected|No |
| MenuItem | Type | Description | Required |
| --------- | :----: | :-------------------------------------------------------------: | :------: |
| **value** | String | The string value of the menu that gets set in the globals | Yes |
| **title** | String | The main text of the title | Yes |
| **left** | String | A string that gets shown in left side of the menu | No |
| **right** | String | A string that gets shown in right side of the menu | No |
| **icon** | String | An icon that gets shown in the toolbar if this item is selected | No |
### Consuming globals from within a story
We recommend consuming globals from within a decorator and define a global setting for all stories.
We recommend consuming globals from within a decorator and define a global setting for all stories.
But we're aware that sometimes it's more useful to use toolbar options in a per-story basis.
Using the example above, you can modify any story to retrieve the __Locale__ `global` from the story context:
Using the example above, you can modify any story to retrieve the **Locale** `global` from the story context:
<!-- prettier-ignore-start -->
@ -115,11 +113,9 @@ In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwa
</div>
### Consuming globals from within an addon
If you're working on a Storybook addon and you need to retrieve globals. You can do so, The `@storybook/api` package provides a hook for this scenario, you can use the `useGlobals()` hook to retrieve any globals you want.
If you're working on a Storybook addon and you need to retrieve globals. You can do so, The `@storybook/api` package provides a hook for this scenario, you can use the `useGlobals()` hook to retrieve any globals you want.
Using the ThemeProvider example above, you could expand it to display which current theme is being shown inside a panel like so:

145
docs/frameworks.js Normal file
View File

@ -0,0 +1,145 @@
module.exports = {
frameworks: [
'react',
'vue',
'angular',
'html',
'mithril',
'marko',
'svelte',
'riot',
'preact',
'rax',
],
featureGroups: [
{
name: 'Essentials',
features: [
{
name: 'Actions',
unsupported: [],
path: 'essentials/actions',
},
{
name: 'Backgrounds',
unsupported: [],
path: 'essentials/backgrounds',
},
{
name: 'Docs',
unsupported: [],
path: 'writing-docs/introduction',
},
{
name: 'Viewport',
unsupported: [],
path: 'essentials/viewport',
},
{
name: 'Controls',
supported: ['react', 'vue', 'rax'],
path: 'essentials/controls',
},
],
},
{
name: 'Addons',
features: [
{
name: 'a11y',
unsupported: [],
},
{
name: 'cssresources',
unsupported: [],
},
{
name: 'design-assets',
unsupported: [],
},
{
name: 'events',
unsupported: ['svelte', 'riot'],
},
{
name: 'google-analytics',
unsupported: [],
},
{
name: 'graphql',
supported: ['react', 'angular'],
},
{
name: 'jest',
unsupported: [],
},
{
name: 'knobs',
unsupported: [],
},
{
name: 'links',
unsupported: ['marko'],
},
{
name: 'query-params',
unsupported: [],
},
{
name: 'Storyshots',
unsupported: ['ember', 'mithril', 'marko'],
path: 'workflows/unit-testing',
},
{
name: 'storysource',
unsupported: [],
},
],
},
{
name: 'Docs',
features: [
{
name: 'MDX Stories',
unsupported: [],
path: 'api/mdx',
},
{
name: 'CSF Stories',
unsupported: [],
path: 'api/csf',
},
{
name: 'storiesOf stories',
unsupported: [],
repoPath: 'lib/core/ADVANCED.md',
},
{
name: 'Source',
unsupported: [],
path: '?',
},
{
name: 'Notes/Info',
unsupported: ['html', 'riot'],
path: '?',
},
{
name: 'Args Table',
supported: ['react', 'vue', 'angular', 'html', 'ember', 'rax'],
path: 'writing-docs/doc-blocks#argstable',
},
{
name: 'Description',
supported: ['react', 'vue', 'angular', 'ember', 'rax'],
path: 'FIXME',
},
{
name: 'Inline stories',
supported: ['react', 'vue', 'rax'],
path: 'FIXME',
},
],
},
],
};

6
docs/get-started/browse-stories.md
View File

@ -4,7 +4,7 @@ title: 'Browse Stories'
Last chapter we learned that stories correspond with discrete component states. This chapter demonstrates how to use Storybook as a workshop for building components.
### Sidebar and Canvas
## Sidebar and Canvas
A `*.stories.js` file defines all the stories for a component. Each story has a corresponding sidebar item. When you click on a story it renders in the Canvas, an isolated preview iframe.
@ -17,7 +17,7 @@ A `*.stories.js` file defines all the stories for a component. Each story has a
Navigate between stories by clicking on them in the sidebar or use keyboard shortcuts (for instance use opt/alt + ◀️ ▶️). Try the sidebar search to find a story by name.
### Toolbar
## Toolbar
Storybook ships with time-saving tools built in. The **toolbar** contains tools that allow you to adjust how the story renders in the Canvas:
@ -45,7 +45,7 @@ The [“Docs”](../writing-docs/introduction.md) tab shows auto-generated docum
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
## Addons
Addons are plugins that extend Storybook's core functionality. You can find them in the addons panel, a reserved place in the Storybook UI below the Canvas. Each tab shows the generated metadata, logs, or static analysis for the selected story by the addon.

6
docs/get-started/conclusion.md
View File

@ -6,7 +6,5 @@ Congratulations! You learned the basics. Storybook is the most popular tool for
If you’d like to learn workflows for building app UIs with Storybook, check out the in-depth guides on [Learn Storybook](https://www.learnstorybook.com/). Continue reading for detailed information on how to use Storybook APIs.
What to learn next:
- [Write stories](../writing-stories/introduction.md)
- [Write component docs](../writing-docs/introduction.md)
- [How to write stories](../writing-stories/introduction.md)
- [How to document components and design systems](../writing-docs/introduction.md)

13
docs/get-started/install.md
View File

@ -1,5 +1,5 @@
---
title: 'Install'
title: 'Install Storybook'
---
Use the Storybook CLI to install it in a single command. Run this inside your existing project’s root directory:
@ -16,13 +16,12 @@ Storybook needs to be installed into a project that is already setup with a fram
- 📦 [Create React App](https://reactjs.org/docs/create-a-new-react-app.html)
- 📦 [Vue CLI](https://cli.vuejs.org/)
- Or any other tooling available.
- Or any other tooling available.
</details>
During its install process, Storybook will look into your project's dependencies and provide you with the best configuration available.
The command above will make the following changes to your local environment:
- 📦 Install the required dependencies.
@ -41,14 +40,13 @@ It will start Storybook locally and output the address. Depending on your system
- A collection of useful links for more in depth configuration and customization options you have at your disposal.
- A second set of links for you to expand your Storybook knowledge and get involved with the ever growing Storybook community.
- A few example stories to get you started.
![Storybook welcome screen](./example-welcome.png)
![Storybook welcome screen](./example-welcome.png)
<details>
<summary>Troubleshooting</summary>
You can also setup Storybook manually through the Storybook CLI.
You can also setup Storybook manually through the Storybook CLI.
You can use the `--type` flag to tell Storybook to configure itself based on the flag.
@ -64,5 +62,4 @@ If all else fails, try asking for [help](https://storybook.js.org/support/)
</details>
Now that you installed Storybook successfully, let’s take a look at a story that was written for us.
Now that you installed Storybook successfully, let’s take a look at a story that was written for us.

2
docs/get-started/introduction.md
View File

@ -1,5 +1,5 @@
---
title: 'Introduction'
title: 'Introduction to Storybook'
---
Storybook is a tool for UI development. It makes development faster and easier by isolating components. This allows you to work on one component at a time. You can develop entire UIs without needing to start up a complex dev stack, force certain data into your database or navigate around your application.

8
docs/get-started/setup.md
View File

@ -1,5 +1,5 @@
---
title: 'Setup'
title: 'Setup Storybook'
---
Now that you’ve learned what stories are and how to browse them, let’s demo working on one of your components. Pick a simple component from your project, like a Button, and write a `.stories.js` file to go along with it. It might look something like this:
@ -28,7 +28,7 @@ Go to your Storybook to view the rendered component. It’s OK if it looks a bit
Depending on your technology stack, you also might need to configure the Storybook environment further.
### Configure Storybook for your stack
## Configure Storybook for your stack
Storybook comes with a permissive [default configuration](../configure/overview.md). It attempts to customize itself to fit your setup. But it’s not foolproof.
@ -75,7 +75,7 @@ export const decorators = [
</details>
### Render component styles
## Render component styles
Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes things won’t “look right” out of the box.
@ -111,7 +111,7 @@ Alternatively if you want to inject a CSS link tag to the `<head>` directly (or
</details>
### Load assets and resources
## Load assets and resources
If you want to link to static files in your project or stories (e.g. `/fonts/XYZ.woff`), use the `-s path/to/folder` to specify a static folder to serve from when you start up Storybook. To do so, edit the `storybook` and `build-storybook` scripts in `package. json`.

2
docs/get-started/whats-a-story.md
View File

@ -2,7 +2,7 @@
title: "What's a Story"
---
**A story captures the rendered state of a UI component**. Developers write multiple stories per component that describe all the “interesting” states a component can support.
A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support.
The CLI created example components that demonstrate the types of components you can build with Storybook: Button, Header, and Page.

204
docs/testing/automated-visual-testing/index.md
View File

@ -1,204 +0,0 @@
---
id: 'automated-visual-testing'
title: 'Automated Visual Testing'
---
Automated Visual Testing is a quality assurance process meant to automatically verify that a UI visually appears as intended. There are many alternative names for this process, such as Visual Regression Testing, Visual Validation Testing, Visual UI Testing, or Visual Testing, but in all cases we're talking about confirming the thing your users will see—the actual pixels—without caring about how it's generated.
## Benefits
The largest benefit to Automated Visual Testing is that they can often supersede other, more brittle tests. Instead of asserting specific CSS rules, selectors, and HTML markup, you assert that something visually appears as expected. If you refactor style, markup, or state logic, but visually nothing changes, you wouldn't need to modify any tests or update visual baselines! In a majority of cases, what a user _sees_ is what you really care about, not how it was achieved.
Another potential benefit is with cross-browser testing. If you perform your visual tests against multiple browsers, they can potentially catch regressions a developer didn't because it appeared correct in their preferred development browser.
## Challenges
The biggest challenge with Automated Visual Testing is that humans and machines perceive pixels differently. Two screenshots of a UI could appear entirely identical to a human but 100% different to a 1:1, naive diffing algorithm.
For example, changes in [anti-aliasing](https://en.wikipedia.org/wiki/Spatial_anti-aliasing) are common, even if human eyes don't notice them.
![Menu before and after differences](../static/image-diff-1.png)
![Close-up of menu before and after differences](../static/image-diff-2.png)
Even though we didn't change any CSS and the menus appear visually the same to our eyes, if we compare their pixels 1:1 we find that lots of it has changed! This can happen between browser versions, underlying hardware changes on your cloud platform, and more.
Similar situations happen all the time, such as how images, drop shadows, etc are rendered.
Some more robust libraries and services solve this by using a combination of [Machine Learning](https://wikipedia.org/wiki/Machine_learning) and [heuristics](https://wikipedia.org/wiki/Heuristic_(computer_science)). The machine is trained what is and is not an acceptable variation.
For example, every graphics card renders text and images differently at the pixel level. Your machine will likely have a different graphics card than the testing server and the other developers. While the naked eye can't tell the difference, a machine needs to be trained to "see" them like we do.
Another issue is that these tests are often slow compared to more lightweight unit tests that don't require a full browser. So you might only run them when you commit, push, and/or on your Continuous Integration (CI) server.
## Libraries and Services with Storybook Integration
There are many libraries and services that have Storybook integrations out-of-box, with varying levels of sophistication. Some even use complex Machine Learning instead of 1:1 pixel comparison.
Storybook uses [Chromatic](https://www.chromaticqa.com), a visual testing service made by Storybook maintainers, to prevent UI bugs in our [application](https://www.chromaticqa.com/library?appId=5a375b97f4b14f0020b0cda3), [design system](https://www.chromaticqa.com/library?appId=5ccbc373887ca40020446347), and [website](https://www.chromaticqa.com/library?appId=5be26744d2f6250024a9117d).
Here are some in alphabetical order:
- [Applitools](https://applitools.com/storybook)
- [Chromatic](https://www.chromaticqa.com) made by Storybook maintainers
- [Creevey](https://github.com/wKich/creevey)
- [Happo](https://happo.io)
- [Loki](https://loki.js.org/)
- [Percy](https://docs.percy.io/docs/storybook)
- [Screener](https://screener.io/v2/docs)
- [StoryShots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots) with its [seamless integration](https://github.com/storybookjs/storybook/tree/master/addons/storyshots#configure-storyshots-for-image-snapshots) with [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot)
## Custom Solutions
There are a number of popular libraries that don't offer out-of-box integration with Storybook, but still can be used to visual test it. [BackstopJS](https://github.com/garris/BackstopJS) and [Gemini](https://github.com/gemini-testing/gemini), for example, but there are quite a few!
Storybook's web server supports the ability to render a component story standalone, in any particular state, without any of the Storybook layout elements. With these special URLs you can either create your own screenshots and diff them, or use a library which does that work for you.
Let's take a look at an example, in this case using [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot)—but the idea is similar for most of them.
> Most custom solutions, including jest-image-snapshot, do 1:1 pixel comparisons which may suffer from issues described in the **Challenges** section above.
### Example using Puppeteer and Jest
Here's a sample Storybook we'd like to visually test:
![Storybook Screenshot](../static/storybook-screenshot.png)
The Storybook UI has a bunch of elements you wouldn't want to include in your visual test. Besides being extraneous, your tests could incorrectly fail when you add a new, unrelated story or state because it would show up in the side menu.
Instead, we'll want to render a component's story by itself. Let's assume the above Storybook runs on port 9009 and we can access it via [http://localhost:9009/](http://localhost:9009/).
Now let's pick a single story: the "with text" story of the Button.
The URL for that story contains a number of query parameters, but the first two are the most important: [http://localhost:9009/?selectedKind=Button&selectedStory=with+text](http://localhost:9009/?selectedKind=Button&selectedStory=with+text)
- selectedKind=Button
- selectedStory=with+text
Using these two parameters we can generate the URL to render the story by itself. Instead of the URL's path being the homepage/index we use `/iframe.html`:
[http://localhost:9009/iframe.html?selectedKind=Button&selectedStory=with+text](http://localhost:9009/iframe.html?selectedKind=Button&selectedStory=with+text)
![Storybook iframe Screenshot](../static/storybook-iframe-screenshot.png)
Now that we know how to render the story by itself, let's get our testing environment all set up.
For this example, we're going to use a number of packages:
* [jest](https://jestjs.io/)
- Testing framework by Facebook
* [puppeteer](https://developers.google.com/web/tools/puppeteer/)
- Library by Google for controlling a [headless](https://wikipedia.org/wiki/Headless_software) Chrome browser.
* [jest-puppeteer](https://github.com/smooth-code/jest-puppeteer)
- Integration between Jest and Puppeteer
* [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot)
- Image snapshot assertion helper
* [start-server-and-test](https://github.com/bahmutov/start-server-and-test)
- Used to start/stop our Storybook server automatically for our tests
> Even though we're choosing Jest/Puppeteer in this example, the principles are the same with other solutions.
Let's go ahead and add all of these:
```sh
yarn add jest puppeteer jest-puppeteer jest-image-snapshot start-server-and-test --dev
```
There's a bit of setup code that needs to run before your tests, so we'll need to configure a Jest setup file to run first, if you haven't already. This is done with the [`setupFilesAfterEnv` config property](https://jestjs.io/docs/en/configuration.html#setupFilesAfterEnv-string), either in your package.json or in your `jest.config.js`. We'll also set `"preset": "jest-puppeteer"` so that we get the nice integration from jest-puppeteer.
#### `integration/jest.config.js`
```js
module.exports = {
preset: 'jest-puppeteer',
testRegex: './*\\.test\\.js$',
setupFilesAfterEnv: ['./setupTests.js']
};
```
With our configuration in place, we can create our file at `integration/setupTests.js` and add the necessary setup logic:
#### `integration/setupTests.js`
```js
const { toMatchImageSnapshot } = require('jest-image-snapshot');
expect.extend({ toMatchImageSnapshot });
```
Finally, we'll create some npm scripts for us to kick everything off with [start-server-and-test](https://github.com/bahmutov/start-server-and-test):
#### `package.json`
```json
{
"name": "my-app",
"scripts": {
"jest:integration": "jest -c integration/jest.config.js",
"test:integration": "start-server-and-test storybook http-get://localhost:9009 jest:integration",
"storybook": "start-storybook -p 9009 -s public"
}
}
```
Now we're ready to write our first visual snapshot test!
#### `integration/Button.test.js`
```js
describe('Button', () => {
it('visually looks correct', async () => {
// APIs from jest-puppeteer
await page.goto('http://localhost:9009/iframe.html?selectedKind=Button&selectedStory=with+text');
const image = await page.screenshot();
// API from jest-image-snapshot
expect(image).toMatchImageSnapshot();
});
});
```
Go ahead and run it:
```bash
npm run test:integration
```
```
info Storybook started on => http://localhost:9009/
PASS integration/app.test.js
Button
✓ visually looks correct (699ms)
› 1 snapshot written.
Snapshot Summary
› 1 snapshot written from 1 test suite.
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 1 written, 1 total
Time: 1.528s, estimated 2s
Ran all test suites.
```
The first time we run a test it will create a new image snapshot to use as the baseline for subsequent test runs. Try changing the style of your story's component and running it again. You should get something like this:
```
FAIL integration/app.test.js
Button
✕ visually looks correct (880ms)
● Button › visually looks correct
Expected image to match or be a close match to snapshot but was 0.03625% different from snapshot (174 differing pixels).
See diff for details: /my-app/integration/__image_snapshots__/__diff_output__/app-test-js-button-visually-looks-correct-1-diff.png
```
If this should become the new baseline, we can tell Jest to update them:
```
npm run jest:integration -- -updateSnapshot
```
We're all set, but keep in mind the [challenges](#challenges) of doing 1:1 pixel matching!

17
docs/testing/interaction-testing/index.md
View File

@ -1,17 +0,0 @@
---
id: 'interaction-testing'
title: 'Interaction Testing'
---
For the interaction testing, [Enzyme](https://github.com/airbnb/enzyme) is the best tool we can use. With that, we can [simulate](http://airbnb.io/enzyme/docs/api/ReactWrapper/simulate.html) user inputs and see what they are doing.
You can directly write these kind of tests with a full-featured testing framework, such as **Mocha** or **Jest**. Have a look at the [Enzyme guidelines](https://github.com/airbnb/enzyme/) for more information on how to integrate them.
## Specs Addon
If you like to write your tests directly inside your stories, we also have an addon called [specs](https://github.com/mthuret/storybook-addon-specifications).
![Storybook Specs Addon](../static/specs-addon.png)
With that, you can write test specs directly inside stories.
Additionally, you also can use your CI server to run those tests.

22
docs/testing/manual-testing/index.md
View File

@ -1,22 +0,0 @@
---
id: 'manual-testing'
title: 'Manual Testing'
---
Now we arrive at the most interesting (but also hardest) part of UI testing.
We usually do this as a team.
First, we need to make a pretty solid Storybook or a set of Storybooks covering most of the scenarios of our UI components.
For that we can follow the following structure:
- Write stories for your individual UI components.
- Write another set of stories for integrating the above UI components (you could consider your pages).
For the individual UI components, you may be using a different repository.
Then, keep a storybook inside it for those components. Then, in the main app, write stories for integrations.
## Testing Plan
Open a new PR (or multiple of them).
Then run your Storybook and start reviewing one story at a time.
Then you can comment on the PR.

88
docs/testing/react-ui-testing/index.md
View File

@ -1,88 +0,0 @@
---
id: 'react-ui-testing'
title: 'Introduction: React UI Testing'
---
There are different aspects we need to look at when testing UI.
There are also a lot of tools and techniques we can use. 
## Reasons for Testing
Before we talk about testing, we need to think about why we need to test.
There are many reasons; here are some of our reasons:
- To find bugs.
- To make sure things won't break between new code commits.
- To keep tests as living documentations.
Specifically, testing is important when working with teams since it allows different people the ability to contribute with confidence.
## Different Aspects of UI Testing
We refer to UI for many things. To put this in focus, let's narrow it down to React based user interfaces.
### 1. Structural Testing
Here we'll focus on the structure of the UI and how it's laid out.
For an example, let's say we have a "login component" as shown below:
![Login Form](../static/login_form.png)
For structural testing, we are testing whether or not it has following content:
- A title with "Log in to Facebook"
- Two inputs for the username and password.
- A submit button.
- An error screen to show errors.
For React, we have been using [Enzyme](https://github.com/airbnb/enzyme) as a way to do structural testing, but now we can also use [Jest's snapshot testing](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) to make things even more simple.
### 2. Interaction Testing
UI is all about interacting with the user.
We do this with a bunch of UI elements, such as buttons, links, and input elements.
With interaction testing, we need to test if they are working properly.
Let's again use the above login component as an example. It should do these things:
- When we click the submit button, it should give us the username and password.
- When we click the "Forgotten Account" link, it should redirect to a new page.
We have few ways to do this type of testing with React. One way is to use [Enzyme](https://github.com/airbnb/enzyme).
### 3. CSS/Style Testing
UI is all about styles (whether they're simple, beautiful, or even ugly).
With style testing, we are evaluating the look and feel of our UI components between code changes.
This is a pretty complex subject and usually we do it by comparing images.
If we are using inline styles all the way, we can use JEST snapshot testing.
But to get even better results, we should consider using tools such as:
- [BackstopJS](https://github.com/garris/BackstopJS)
- [Gemini](https://github.com/gemini-testing/gemini)
- [Happo](https://github.com/happo/happo.io)
### 4. Manual Testing
All the above sections are about testing with automated tools.
But since we are building UI for humans, we must also manually test them to see how they feel.
Another reason for manual testing is for the better user experience.
We should always try to test our UI with the naked eye.
For this, we can use our existing Storybook.
This is something that we can't automate(yet) and takes time.
But it would be great if we could do this once in a while (especially with a major code changes).
## How Storybook Can Help Us
A **story** is the smallest unit in Storybook.
It's a fully functioning UI element where the input can be used for any of the testing methods we've mentioned above.
Let's look at how Storybook can help you do the above mentioned different aspects of testing.
- [Structural Testing with StoryShots](/testing/structural-testing)
- [Interaction Testing with Specs Addon](/testing/interaction-testing)
- [Storybook as the Base for Automated Visual Testing](/testing/automated-visual-testing)
- [Storybook for Manual UI Testing](/testing/manual-testing)

BIN
docs/testing/static/image-diff-1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/testing/static/image-diff-2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/testing/static/image-diff-3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 279 KiB

BIN
docs/testing/static/login_form.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/testing/static/specs-addon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/testing/static/storybook-iframe-screenshot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 80 KiB

BIN
docs/testing/static/storybook-screenshot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 121 KiB

BIN
docs/testing/static/storyshots-diff-view.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 90 KiB

BIN
docs/testing/static/storyshots-first-run.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 33 KiB

63
docs/testing/structural-testing/index.md
View File

@ -1,63 +0,0 @@
---
id: 'structural-testing'
title: 'Structural Testing'
---
For React, [Jest's snapshot testing](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) is the best way to do Structural Testing.
It's painless to use and maintain.
We've integrated Jest's snapshot testing directly into Storybook using an addon called [StoryShots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots).
Now we can use existing stories as the input for snapshot testing.
## What's Snapshot Testing?
With Snapshot testing, we keep a file copy of the structure of UI components.
Think of it like a set of HTML sources.
Then, after we've completed any UI changes, we compare new snapshots with the snapshots that we kept in the file.
If things are not the same, we can do two things:
1. We can consider new snapshots that show the current state, and then update them as new snapshots.
2. We can find the root cause for the change and fix our code.
> We can also commit these snapshots directly into the source code.
## Using StoryShots
[StoryShots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots) is our integration between Storybook and Jest Snapshot Testing.
To use StoryShots, first make sure you are inside a Storybook-enabled repo (make sure it has few stories).
Then, install StoryShots and any necessary [framework-specific peer dependencies](https://github.com/storybookjs/storybook/blob/next/addons/storyshots/storyshots-core/README.md).
For instance if you're testing a react project:
```sh
npm i -D @storybook/addon-storyshots react-test-renderer
```
Then, assuming you are using Jest for testing, you can create a test file `storyshots.test.js` that contains the following:
```js
import initStoryshots from '@storybook/addon-storyshots';
initStoryshots({ /* configuration options */ });
```
Now you can snapshot test all of your stories with:
```sh
npm test
```
This will save the initial set of snapshots inside your Storybook config directory.
![StoryShots First](../static/storyshots-first-run.png)
After you complete any changes, you can run the test again and find all structural changes.
![StoryShots Diff View](../static/storyshots-diff-view.png)
* * *
StoryShots also comes with a variety of customization options. Have a look at the StoryShots [repo](https://github.com/storybookjs/storybook/tree/master/addons/storyshots) for more information.

159
docs/toc.js
View File

@ -87,7 +87,7 @@ module.exports = {
},
{
pathSegment: 'docs-page',
title: 'Docs Page',
title: 'DocsPage',
type: 'link',
},
{
@ -97,18 +97,18 @@ module.exports = {
},
{
pathSegment: 'doc-blocks',
title: 'Docs Blocks',
title: 'Doc Blocks',
type: 'link',
},
{
pathSegment: 'build-documentation',
title: 'Preview and build Storybook documentation',
title: 'Preview and build docs',
type: 'link',
},
],
},
{
title: 'Essentials',
title: 'Essential addons',
pathSegment: 'essentials',
type: 'menu',
children: [
@ -117,24 +117,25 @@ module.exports = {
title: 'Introduction',
type: 'link',
},
{
pathSegment: 'controls',
title: 'Controls',
type: 'link',
},
{
pathSegment: 'actions',
title: 'Actions',
type: 'link',
},
{
pathSegment: 'viewports',
title: 'Viewports',
pathSegment: 'backgrounds',
title: 'Backgrounds',
type: 'link',
},
{
pathSegment: 'backgrounds',
title: 'Backgrounds',
pathSegment: 'controls',
title: 'Controls',
type: 'link',
},
{
pathSegment: 'viewports',
title: 'Viewports',
type: 'link',
},
{
@ -165,29 +166,31 @@ module.exports = {
type: 'link',
},
{
pathSegment: 'user-interface',
pathSegment: '',
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',
type: 'menu',
children: [
{
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',
@ -208,7 +211,7 @@ module.exports = {
},
{
pathSegment: 'build-pages-with-storybook',
title: 'Building pages with Storybook',
title: 'Building pages and screens',
type: 'link',
},
{
@ -251,7 +254,7 @@ module.exports = {
},
{
pathSegment: 'storybook-composition',
title: 'Storybook Composition',
title: 'Composition',
type: 'link',
},
{
@ -267,47 +270,53 @@ module.exports = {
type: 'menu',
children: [
{
pathSegment: 'stories',
title: 'Stories',
type: 'link',
pathSegment: '',
type: 'menu',
children: [
{
pathSegment: 'csf',
title: 'Component Story Format',
type: 'link',
},
{
pathSegment: 'mdx',
title: 'MDX syntax',
type: 'link',
},
{
pathSegment: 'argtypes',
title: 'ArgTypes',
type: 'link',
},
],
},
{
pathSegment: 'csf',
title: 'Component Story Format',
description: 'Learn about the Component Story Format API',
type: 'bullet-link',
},
{
pathSegment: 'mdx',
title: 'MDX syntax',
description: 'Learn how to add MDX to your Storybook',
type: 'bullet-link',
},
{
pathSegment: 'argtypes',
title: 'ArgTypes',
description: 'Learn how to use Argtypes with your Storybook',
type: 'bullet-link',
},
{
pathSegment: 'addons',
title: 'Addons',
type: 'link',
},
{
pathSegment: 'addons-api',
title: 'Addons API',
type: 'link',
},
{
pathSegment: 'presets',
title: 'Presets',
type: 'link',
},
{
pathSegment: 'writing-presets',
title: 'Writing your own Storybook Preset',
type: 'link',
pathSegment: '',
type: 'menu',
children: [
{
pathSegment: 'addons',
title: 'Addons',
type: 'link',
},
{
pathSegment: 'presets',
title: 'Presets',
type: 'link',
},
{
pathSegment: 'writing-presets',
title: 'Writing Presets',
type: 'link',
},
{
pathSegment: 'addons-api',
title: 'Addons API',
type: 'link',
},
],
},
{
pathSegment: 'new-frameworks',
@ -316,7 +325,7 @@ module.exports = {
},
{
pathSegment: 'cli-options',
title: 'CLI Options',
title: 'CLI options',
type: 'link',
},
{

35
docs/workflows/build-pages-with-storybook.md
View File

@ -2,14 +2,14 @@
title: 'Building pages with Storybook'
---
Storybook helps you build any component, from small “atomic” components to composed pages. But as you move up the component hierarchy toward the level of pages, you end up dealing with more complexity.
Storybook helps you build any component, from small “atomic” components to composed pages. But as you move up the component hierarchy toward the level of pages, you end up dealing with more complexity.
There are many ways to build pages in Storybook. Here are common patterns and solutions.
- Pure presentational pages.
- Connected components (e.g. network requests, context, browser environment).
### Pure presentational pages
## Pure presentational pages
Teams at the BBC, The Guardian, and the Storybook maintainers themselves build pure presentational pages. If you take this approach, you don't need to do anything special to render your pages in Storybook.
@ -28,7 +28,7 @@ The downsides:
- It's less flexible if you want to load data incrementally in different places on the screen.
#### Args composition for presentational screens
### Args composition for presentational screens
When you are building screens in this way, it is typical that the inputs of a composite component are a combination of the inputs of the various sub-components it renders. For instance, if your screen renders a page layout (containing details of the current user), a header (describing the document you are looking at), and a list (of the subdocuments), the inputs of the screen may consist of the user, document and subdocuments.
@ -65,25 +65,25 @@ import DocumentList from './DocumentList.stories';
export default {
component: DocumentScreen,
title: 'DocumentScreen',
}
};
const Template = (args) => <DocumentScreen {...args} />;
export const Simple = Template.bind({});
Simple.args = {
user: PageLayout.Simple.user,
document: DocumentHeader.Simple.document,
subdocuments: DocumentList.Simple.documents,
user: PageLayout.Simple.user,
document: DocumentHeader.Simple.document,
subdocuments: DocumentList.Simple.documents,
};
```
This approach is particularly useful when the various subcomponents export a complex list of different stories, which you can pick and choose to build realistic scenarios for your screen-level stories without repeating yourself. By reusing the data and taking a Don't-Repeat-Yourself(DRY) philosophy, your story maintenance burden is minimal.
### Mocking connected components
## Mocking connected components
Render a connected component in Storybook by mocking the network requests that it makes to fetch its data. There are various layers in which you can do that.
#### Mocking providers
### Mocking providers
If you are using a provider that supplies data via the context, you can wrap your story in a decorator that supplies a mocked version of that provider. For example, in the [Screens](https://www.learnstorybook.com/intro-to-storybook/react/en/screen/) chapter of Learn Storybook we mock a Redux provider with mock data.
@ -95,8 +95,8 @@ Additionally, there may be addons that supply such providers and nice APIs to se
import MyComponentThatHasAQuery, {
MyQuery,
} from '../component-that-has-a-query';
export const LoggedOut = () => <MyComponentThatHasAQuery />;
export const LoggedOut = () => <MyComponentThatHasAQuery />;
LoggedOut.parameters: {
apolloClient: {
mocks: [
@ -106,7 +106,7 @@ LoggedOut.parameters: {
};
```
#### Mocking imports
### Mocking imports
It is also possible to mock imports directly, similar to Jest, using webpack’s aliasing. This is extremely useful if your component makes network requests directly with third-party libraries.
@ -141,15 +141,15 @@ To use the mock in place of the real import, we use [webpack aliasing](https://w
module.exports = {
// your Storybook configuration
webpackFinal: config => {
webpackFinal: (config) => {
config.resolve.alias['isomorphic-fetch'] = require.resolve('../__mocks__/isomorphic-fetch.js');
return config;
}
},
};
```
Add the mock you've just implemented to your [storybook/preview.js](../configure/overview.md#configure-story-rendering) (if you don't have it already, you'll need to create the file):
```js
// .storybook/preview.js
import { decorator } from '../__mocks/isomorphic-fetch';
@ -191,9 +191,8 @@ Success.parameters = {
};
```
#### Specific mocks
### Specific mocks
Another mocking approach is to use libraries that intercept calls at a lower level. For instance you can use [`fetch-mock`](https://www.npmjs.com/package/fetch-mock) to mock fetch requests specifically, or [`msw`](https://www.npmjs.com/package/msw) to mock all kinds of network traffic.
Similar to the import mocking above, once you have a mock you’ll still want to set the return value of the mock on a per-story basis. Do this in Storybook with a decorator that reads story parameters.
Similar to the import mocking above, once you have a mock you’ll still want to set the return value of the mock on a per-story basis. Do this in Storybook with a decorator that reads story parameters.

6
docs/workflows/interaction-testing.md
View File

@ -1,8 +1,8 @@
---
title: 'Interaction testing'
title: 'Interaction testing with Storybook'
---
Stories are useful for verifying the known states of a component. But sometimes you need to test how a component changes in response to user interaction.
Stories are useful for verifying the known states of a component. But sometimes you need to test how a component changes in response to user interaction.
Stories are convenient **starting points** and **harnesses** for interaction tests using end-to-end tools like [Enzyme](https://enzymejs.github.io/enzyme/) and [Cypress](https://www.cypress.io/).
@ -19,5 +19,3 @@ describe('My Component', () => {
});
})
```

45
docs/workflows/package-composition.md
View File

@ -2,17 +2,17 @@
title: 'Package Composition'
---
Storybook is widely used by component libraries and design systems. Design system authors can automatically compose their design systems inside their consumer’s Storybooks.
Storybook is widely used by component libraries and design systems. Design system authors can automatically compose their design systems inside their consumer’s Storybooks.
For example, if you use a design system package, its stories can appear alongside your own. That makes it convenient to cross reference usage documentation without leaving Storybook.
### For package consumers
## For package consumers
Composition happens automatically if the package [supports](#for-package-authors) it. When you install the package, Storybook will load its stories alongside your own.
Composition happens automatically if the package [supports](#for-package-authors) it. When you install the package, Storybook will load its stories alongside your own.
![Package composition workflow](./package-composition.png)
#### Configuring
### Configuring
If you want to configure how the composed Storybook behaves, you can disable the `ref` element in your [`.storybook/main.js`](../configure/overview.md#configure-story-rendering)
@ -26,29 +26,28 @@ module.exports = {
}
```
#### Changing versions
### Changing versions
Change the version of the composed Storybook to see how the library evolves. This requires [configuration](#providing-a-version-section) from the package author.
![Package composition workflow](./composition-versioning.png)
### For package authors
## For package authors
Component library authors can expand adoption by composing their components in their consumer’s Storybooks.
Component library authors can expand adoption by composing their components in their consumer’s Storybooks.
Add a `storybook` property in your published `package.json `that contains an object with a `url` field. Point the URL field to a published Storybook at the version you want.
Add a `storybook` property in your published `package.json`that contains an object with a `url` field. Point the URL field to a published Storybook at the version you want.
```json
// Your component library’s package.json
{
"storybook": {
"url": "https://host.com/your-storybook-for-this-version"
}
"storybook": {
"url": "https://host.com/your-storybook-for-this-version"
}
}
```
#### Automatic version selection
### Automatic version selection
If you are using a [CHP level 1 service](#chp-level-1) for hosting (such as [Chromatic.com](https://www.chromatic.com/)), you can provide a single URL for your Storybook in the `storybook.url` field. You do not need to change the URL each time you publish a new version. Storybook will automatically find the correct URL for your package.
@ -56,23 +55,23 @@ For example, for Chromatic, you might do:
```json
{
"storybook": {
"url": "https://master--xyz123.chromatic.com"
}
"storybook": {
"url": "https://master--xyz123.chromatic.com"
}
}
```
In this example `xyz123` is your project’s id. Storybook will automatically compose in the Storybook published to that project corresponding to the version the user has installed.
#### Providing a version section
### Providing a version section
Similarly, if you're using a [CHP level 1 service](#chp-level-1) (such as chromatic.com) for hosting, you can provide a list of versions for the user to [choose from](#changing-versions) to experiment with other versions of your package.
### Component Hosting Protocol (CHP)
## Component Hosting Protocol (CHP)
Storybook can communicate with services that host built Storybooks online. This enables features such as [Composition](./storybook-composition). We categorize services via compliance with the "Component Hosting Protocol" (CHP) with various levels of support in Storybook.
#### CHP level 1
### CHP level 1
<div style="background-color:#F8FAFC">
TODO: "version=x.y.z query parameter".(vet this)
@ -84,13 +83,15 @@ The service serves uploaded Storybooks and makes the following available:
- Support for /stories.json
- Support for /metadata.json and the releases field.
Examples of such services:
Examples of such services:
- [chromatic.com](https://www.chromatic.com/)
#### CHP level 0
### CHP level 0
The service can serve uploaded Storybooks. There is no special integration with Storybook APIs.
Examples of such services:
Examples of such services:
- [Netlify](https://www.netlify.com/)
- [S3](https://aws.amazon.com/en/s3/)

17
docs/workflows/publish-storybook.md
View File

@ -4,9 +4,9 @@ title: 'Publish Storybook'
Storybook is more than a UI component development tool. Teams also publish Storybook online to review and collaborate on works in progress. That allows developers, designers, and PMs to check if UI looks right without touching code or needing a local dev environment.
### Build Storybook as a static web application
## Build Storybook as a static web application
First, we’ll need to build Storybook as a static web application using `build-storybook`, a command that’s installed by default.
First, we’ll need to build Storybook as a static web application using `build-storybook`, a command that’s installed by default.
```shell
yarn build-storybook -o ./path/to/build
@ -24,13 +24,11 @@ Asides from the `-o` flag, you can also include other flags to build Storybook,
You can learn more about these flag options [here](../api/cli-options.md).
</div>
## Publish Storybook online
### 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.
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.
We also maintain [`storybook-deployer`](https://github.com/storybookjs/storybook-deployer) to deploy to GitHub pages or AWS S3.
@ -41,7 +39,7 @@ We also maintain [`storybook-deployer`](https://github.com/storybookjs/storybook
/>
</video>
### Review with your team
## Review with your team
Publishing Storybook as part of the development process makes it quick and easy to [gather team feedback](https://www.learnstorybook.com/design-systems-for-developers/react/en/review/).
@ -51,7 +49,7 @@ If you publish your Storybook to Chromatic, you can use the [UI Review](https://
![Storybook publishing workflow](./workflow-publish.png)
### Reference external Storybooks
## Reference external Storybooks
Storybook allows you to browse components from any [Storybook published online](./storybook-composition.md) inside your local Storybook. It unlocks common workflows that teams often struggle with:
@ -59,9 +57,8 @@ Storybook allows you to browse components from any [Storybook published online](
- 🎨 Design systems can expand adoption by composing themselves into their users’ Storybooks.
- 🛠 Frontend platform can audit how components are used across projects.
![Storybook reference external](./reference-external-storybooks-composition.jpg)
Toggle between multiple versions of Storybook to see how components change between versions. This is useful for design system package authors who maintain many versions at once.
**Requires** a [CHP level 1](./package-composition.md#chp-level-1) server (such as [chromatic.com](https://www.chromatic.com/)),
**Requires** a [CHP level 1](./package-composition.md#chp-level-1) server (such as [chromatic.com](https://www.chromatic.com/)),

14
docs/workflows/snapshot-testing.md
View File

@ -1,17 +1,11 @@
---
title: 'Snapshot testing'
title: 'Snapshot testing with Storybook'
---
Snapshot tests compare the rendered markup of every story against known baselines. It’s an easy way to identify markup changes that trigger rendering errors and warnings.
Storybook is a convenient tool for snapshot testing because every story is essentially a test specification. Any time you write or update a story you get a snapshot test for free.
<div class="aside">
Snapshot vs visual tests. Visual tests take screenshots of stories and compare them against known baselines. When used to test appearance, visual tests are often a more robust solution than snapshot tests because verifying markup doesn’t test for visual changes.
</div>
Storyshots is an [official addon](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core) that enables snapshot testing. It’s powered by Jest so you’ll need to [install that](https://jestjs.io/docs/en/getting-started) first. Continue on if you already have Jest.
Install the addon. **Make sure** the version of Storyshots and your project’s Storybook version are identical.
@ -62,3 +56,9 @@ When you make changes to your components or stories, run the test again to ident
If the changes are intentional we can accept them as new baselines. If the changes are bugs, fix the underlying code then run the snapshot tests again.
Storyshots has many options for advanced use cases; read more in the [addon’s documentation](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core).
<div class="aside">
Snapshot vs visual tests. [Visual tests](./visual-testing.md) take screenshots of stories and compare them against known baselines. When used to test appearance, visual tests are often a more robust solution than snapshot tests because verifying markup doesn’t test for visual changes.
</div>

22
docs/workflows/stories-for-multiple-components.md
View File

@ -2,7 +2,7 @@
title: 'Stories for multiple components'
---
It's useful to write stories that [render two or more components](../writing-stories/introduction.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroups`, `Lists`, and `Page` components.
It's useful to write stories that [render two or more components](../writing-stories/introduction.md#stories-for-two-or-more-components) at once if those components are designed to work together. For example, `ButtonGroups`, `Lists`, and `Page` components.
```js
// List.story.js
@ -24,6 +24,7 @@ export const OneItem = (args) => (
</List>
);
```
Note that by adding `subcomponents` to the default export, we get an extra pane on the ArgsTable, listing the props of `ListItem`:
![Storybook story with subcomponent argstable](./argstable-subcomponents.png)
@ -35,7 +36,7 @@ The downside of the above approach is that it does not take advantage of Storybo
Let's talk about some techniques you can use to mitigate the above, which are especially useful in more complicated situations.
### Reusing subcomponent stories
## Reusing subcomponent stories
The simplest change we can make to the above is to reuse the stories of the `ListItem` in the `List`:
@ -57,25 +58,24 @@ By rendering the `Unchecked` story with its args, we are able to reuse the input
However, we still aren’t using args to control the `ListItem` stories, which means we cannot change them with controls and we cannot reuse them in other, more complex component stories.
### Using children as an arg
## Using children as an arg
One way we improve that situation is by pulling the render subcomponent out into a `children` arg:
```js
// List.story.js
const Template = (args) => <List {...args} />
const Template = (args) => <List {...args} />;
export const OneItem = Template.bind({});
OneItem.args = {
children: <Unchecked {...Unchecked.args} />
}
children: <Unchecked {...Unchecked.args} />,
};
```
Now that `children` is an arg, we can potentially reuse it in another story. As things stand (we hope to improve this soon) you cannot edit children in a control yet.
### Creating a Template Component
## Creating a Template Component
Another option that is more “data”-based is to create a special “story-generating” template component:
@ -89,7 +89,9 @@ import { Unchecked } from './ListItem.stories';
const ListTemplate = ({ items, ...args }) => (
<List>
{items.map(item => <ListItem {...item} />)}
{items.map((item) => (
<ListItem {...item} />
))}
</List>
);
@ -107,4 +109,4 @@ This approach is a little more complex to setup, but it means you can more easil
src="template-component-with-controls-optimized.mp4"
type="video/mp4"
/>
</video>
</video>

40
docs/workflows/storybook-composition.md
View File

@ -2,52 +2,48 @@
title: 'Storybook Composition'
---
Composition allows you to embed components from any Storybook inside your local Storybook.
Composition allows you to embed components from any Storybook inside your local Storybook. It’s made for teams who adopt Storybook in multiple projects but can’t ensure that the projects have the same tech stack or share the same repo.
It’s made for teams who adopt Storybook in multiple projects but can’t ensure that the projects have the same tech stack or share the same repo.
You can compose any Storybook [published online](./publish-storybook.md) or running locally no matter the view layer, tech stack, or dependencies.
You can compose any Storybook [published online](./publish-storybook.md) or running locally no matter the view layer, tech stack, or dependencies.
![Storybook composition](./combine-storybooks.png)
### Compose published Storybooks
## Compose published Storybooks
In your [`storybook/main.js`](../configure/overview.md#configure-story-rendering) file add a `refs` field with information about the reference Storybook. Pass in a URL to a statically built Storybook.
In your [`storybook/main.js`](../configure/overview.md#configure-story-rendering) file add a `refs` field with information about the reference Storybook. Pass in a URL to a statically built Storybook.
```js
//.storybook/main.js
module.exports={
// your Storybook configuration
refs: {
'design-system': {
title: "Storybook Design System",
'design-system': {
title: "Storybook Design System",
url: "https://5ccbc373887ca40020446347-yldsqjoxzb.chromatic.com"
}
}`
}
```
### Compose local Storybooks
## Compose local Storybooks
You can also compose Storybook that are running locally. For instance, if you have a React Storybook and a Angular Storybook running on different ports:
```js
//.storybook/main.js
module.exports={
module.exports = {
// your Storybook configuration
refs: {
react: {
title: "React",
url: 'http://localhost:7007'
react: {
title: 'React',
url: 'http://localhost:7007',
},
angular: {
title: "Angular",
url: 'http://localhost:7008'
}
}
}
angular: {
title: 'Angular',
url: 'http://localhost:7008',
},
},
};
```
This composes the React and Angular Storybooks into your current Storybook. When either code base changes, hot-module-reload will work perfectly. That enables you to develop both frameworks in sync.
This composes the React and Angular Storybooks into your current Storybook. When either code base changes, hot-module-reload will work perfectly. That enables you to develop both frameworks in sync.

9
docs/workflows/unit-testing.md
View File

@ -1,14 +1,14 @@
---
title: 'Unit testing'
title: 'Unit testing with Storybook'
---
Unit tests are useful for verifying functional aspects of components. They verify that the output of a component remains the same given a fixed input.
Unit tests are useful for verifying functional aspects of components. They verify that the output of a component remains the same given a fixed input.
![Unit testing with a component](./component-unit-testing.gif)
Thanks to the [CSF format](../../formats/component-story-format/), your stories are reusable in unit testing tools. Each [named export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) is “renderable” without depending on Storybook. That means your testing framework will also be able to render that story.
Thanks to the [CSF format](../../formats/component-story-format/), your stories are reusable in unit testing tools. Each [named export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) is “renderable” without depending on Storybook. That means your testing framework will also be able to render that story.
Additionally, the Storybook framework packages have an export that makes this easy and doesn’t rely on any other Storybook dependencies.
Additionally, the Storybook framework packages have an export that makes this easy and doesn’t rely on any other Storybook dependencies.
Here is an example of how you can use it in a testing library:
@ -29,4 +29,3 @@ it('renders the button in the primary state’, () => {
```
Unit tests can be brittle and expensive to maintain for _every_ component. We recommend combining unit tests with other testing methods like [visual regression testing](./visual-testing.md) for comprehensive coverage with less maintenance work.

30
docs/workflows/visual-testing.md
View File

@ -1,29 +1,21 @@
---
title: 'Visual Testing'
title: 'Visual Testing with Storybook'
---
Visual tests, also called visual regression tests, catch bugs in UI appearance. They work by taking screenshots of every story and comparing them commit-to-commit to identify changes.
This is ideal for verifying what the user sees:
- 🖼️ Layout.
- 🎨 Color.
- 📐 Size.
- 🔳 Contrast.
Storybook is a fantastic tool for visual testing because every story is essentially a test specification. Any time you write or update a story you get a spec for free.
> Visual vs snapshot tests. Snapshot tests compare the rendered markup of every story against known baselines. When used to test how things look, snapshot tests generate a lot of false positives because code changes don’t always yield visual changes.
Visual tests, also called visual regression tests, catch bugs in UI appearance. They work by taking screenshots of every story and comparing them commit-to-commit to identify changes.
This is ideal for verifying what the user sees: layout, color, size, and contrast. Storybook is a fantastic tool for visual testing because every story is essentially a test specification. Any time you write or update a story you get a spec for free.
![Visually testing a component in Storybook](./component-visual-testing.gif)
There are [many tools](https://github.com/mojoaxel/awesome-regression-testing) for visual testing. Storybook uses [Chromatic](https://www.chromatic.com), a visual testing service made by Storybook maintainers to run tests in the cloud across browsers.
There are [many tools](https://github.com/mojoaxel/awesome-regression-testing) for visual testing. Storybook uses [Chromatic](https://www.chromatic.com), a visual testing service made by Storybook maintainers to run tests in the cloud across browsers.
This prevents UI bugs in our:
This prevents UI bugs in [Storybook itself](https://www.chromatic.com/library?appId=5a375b97f4b14f0020b0cda3), the [design system](https://www.chromatic.com/library?appId=5ccbc373887ca40020446347), and our [website](https://www.chromatic.com/library?appId=5be26744d2f6250024a9117d).
- 🖥️ [Application](https://www.chromatic.com/library?appId=5a375b97f4b14f0020b0cda3).
- ⚙️ [Design system](https://www.chromatic.com/library?appId=5ccbc373887ca40020446347)
- 🔗 [Website](https://www.chromatic.com/library?appId=5be26744d2f6250024a9117d).
We also maintain [StoryShots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots), a snapshot testing addon that integrates with [jest-image-snapshot](https://github.com/storybookjs/storybook/tree/master/addons/storyshots#configure-storyshots-for-image-snapshots).
We also maintain [StoryShots](https://github.com/storybookjs/storybook/tree/master/addons/storyshots), a snapshot testing addon that integrates with [jest-image-snapshot](https://github.com/storybookjs/storybook/tree/master/addons/storyshots#configure-storyshots-for-image-snapshots).
<div class="aside">
Visual vs snapshot tests. [Snapshot tests](./snapshot-testing.md) compare the rendered markup of every story against known baselines. When used to test how things look, snapshot tests generate a lot of false positives because code changes don’t always yield visual changes.
</div>

15
docs/writing-docs/build-documentation.md
View File

@ -1,17 +1,17 @@
---
title: 'Preview and build Storybook documentation'
title: 'Preview and build docs'
---
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
## 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",
"storybook-docs": "start-storybook --docs"
}
}
```
@ -20,7 +20,6 @@ Depending on your configuration, when you execute the `storybook-docs` script. S
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...
![Storybook in documentation mode](./storybook-docs-build.png)
There's some caveats to this build mode, as to the normal Storybook build:
@ -29,26 +28,22 @@ There's some caveats to this build mode, as to the normal Storybook build:
- 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
## 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",
"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/)

119
docs/writing-docs/doc-blocks.md
View File

@ -6,11 +6,11 @@ title: 'Doc Blocks'
TODO: vet the canvas changes. Originally it was Preview and now it's Canvas (associated issue https://github.com/storybookjs/storybook/issues/11696)
</div>
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.
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
## ArgsTable
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.
@ -29,10 +29,8 @@ This is extremely useful, but it can be further expanded. Additional information
import React from 'react';
import PropTypes from 'prop-types';
export default function Button({isDisabled,content}) {
return (
<button disabled={isDisabled}>{content}</button>
);
export default function Button({ isDisabled, content }) {
return <button disabled={isDisabled}>{content}</button>;
}
Button.propTypes = {
@ -45,13 +43,11 @@ Button.propTypes = {
*/
content: PropTypes.string.isRequired,
};
```
By including the additional information, the args table will be updated. Offering a richer experience for any stakeholders involved.
#### DocsPage
### DocsPage
To use the `ArgsTable` in [DocsPage](./docs-page.md#component-parameter), export a component property on your stories metadata:
@ -67,7 +63,7 @@ export default {
// your templates and stories
```
#### MDX
### MDX
To use the `ArgsTable` in MDX, use the Props block:
@ -82,7 +78,7 @@ import { MyComponent } from './MyComponent';
<Props of={MyComponent} />
```
#### Customizing
### Customizing
`ArgsTables` are automatically inferred from your components and stories, but sometimes it's useful to customize the results.
@ -98,21 +94,20 @@ NOTE: This API is experimental and may change outside of the typical semver rele
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 |
|:-----------------------------|:----------------------------------------------------------------------------------------------:|
| **name** |The name of the property |
| **type.required** |The stories to be show, ordered by supplied name |
| **description** |A Markdown description for the property |
|**table.type.summary** |A short version of the type |
|**table.type.detail** |A short version of the type |
|**table.defaultValue.summary**|A short version of the type |
|**table.defaultValue.detail** |A short version of the type |
|**control** |See [addon-controls README ](https://github.com/storybookjs/storybook/tree/next/addons/controls)|
| Field | Description |
| :----------------------------- | :----------------------------------------------------------------------------------------------: |
| **name** | The name of the property |
| **type.required** | The stories to be show, ordered by supplied name |
| **description** | A Markdown description for the property |
| **table.type.summary** | A short version of the type |
| **table.type.detail** | A short version of the type |
| **table.defaultValue.summary** | A short version of the type |
| **table.defaultValue.detail** | A short version of the type |
| **control** | See [addon-controls README ](https://github.com/storybookjs/storybook/tree/next/addons/controls) |
For instance:
```js
export default {
title: 'Button',
component: Button,
@ -120,9 +115,9 @@ export default {
label: {
description: 'overwritten description',
table: {
type: {
summary: 'something short',
detail: 'something really really long'
type: {
summary: 'something short',
detail: 'something really really long',
},
},
control: {
@ -142,7 +137,7 @@ For instance you can use:
- `number`, which is shorthand for `type: {name: 'number'}`
- `radio`, which is a shorhand for `control: {type: 'radio' }`
##### MDX
#### MDX
To customize `argTypes` in MDX, you can set an `mdx` prop on the `Meta` or `Story` components:
@ -152,34 +147,34 @@ To customize `argTypes` in MDX, you can set an `mdx` prop on the `Meta` or `Stor
title="MyComponent"
component={MyComponent}
argTypes={{
label: {
label: {
name: 'label',
/* other argtypes required */
/* other argtypes required */
},
}}
/>
<Story name="some story" argTypes={{
label: {
name: 'different label',
/* other required data */
label: {
name: 'different label',
/* other required data */
}
}}>
{/* story contents */}
</Story>
```
#### Controls
### Controls
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
## Source
Storybook Docs displays a story’s source code using the `Source` block. The snippet has built-in syntax highlighting and can be copied with the click of a button.
![Docs blocks with source](./docblock-source.png)
#### DocsPage
### DocsPage
In DocsPage, the `Source` block appears automatically within each story’s [Canvas](#canvas) block.
@ -190,15 +185,15 @@ To customize the source snippet that’s displayed for a story, set the `docs.so
export const CustomSource = () => Template.bind({});
CustomSource.parameters = {
docs: {
source: {
code: 'Some custom string here';
}
docs: {
source: {
code: 'Some custom string here';
}
},
};
```
#### MDX
### MDX
You can also use the `Source` block in MDX. It accepts either a story ID or `code` snippet. Use the `language` for syntax highlighting.
@ -207,22 +202,22 @@ import { Source } from '@storybook/addon-docs/blocks';
import dedent from 'ts-dedent';
<Source
language='css'
language="css"
code={dedent`
.container {
display: grid | inline-grid;
}
`}
/>
/>;
```
#### ⚒️ Description
## Description
Storybook Docs shows a component’s description extracted from the source code or based on a user-provided string.
![Docs blocks with description](./docblock-description.png)
#### DocsPage
### DocsPage
In DocsPage, a component’s description is shown at the top of the page. For [supported frameworks](https://github.com/storybookjs/storybook/tree/next/addons/docs#framework-support), the component description is automatically extracted from a docgen component above the component in its source code. It can also be set by the `docs.description` parameter.
@ -231,25 +226,25 @@ In DocsPage, a component’s description is shown at the top of the page. For [s
export default {
title: 'CustomDescription'
parameters: {
docs: {
description: {
component: 'some component _markdown_'
}
docs: {
description: {
component: 'some component _markdown_'
}
},
}
};
export const WithStoryDescription = Template.bind({});
WithStoryDescription.parameters = {
docs: {
description: {
story: 'some story **markdown**'
}
docs: {
description: {
story: 'some story **markdown**'
}
},
};
```
#### MDX
### MDX
In MDX, the `Description` shows the component’s description using the same heuristics as the DocsPage. It also accepts a `markdown` parameter to show any user-provided Markdown string.
@ -267,17 +262,17 @@ import { Button } from './Button';
`}/>
```
### Story
## Story
Stories (component examples) are the basic building blocks in Storybook. In Storybook Docs, stories are rendered in the `Story` block.
![Docs blocks with stories](./docblock-story.png)
#### DocsPage
### DocsPage
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
### 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 [Canvas](#canvas) block defined at the top level:
@ -295,30 +290,28 @@ export const Template = (args) => <Button {...args} />;
You can also reference existing stories in Storybook by ID:
```js
import { Story } from '@storybook/addon-docs/blocks';
<Story id="some-component--some-name" />
<Story id="some-component--some-name" />;
```
#### Inline rendering
### 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.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.
### Canvas
## Canvas
Storybook Docs’ `Canvas` block is a wrapper that provides a toolbar for interacting with its contents, and also also provides [Source](#source) snippets automatically.
![Docs block with a story preview](./docblock-preview.png)
#### DocsPage
### DocsPage
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.
![Docs blocks preview toolbar](./docblock-preview-toolbar.png)
#### MDX
### MDX
In MDX, `Canvas` is more flexible: in addition to the DocsPage behavior, it can show multiple stories in one:
@ -348,7 +341,7 @@ import { MyComponent } from './MyComponent';
<Preview>
<h2>Some here</h2>
<MyComponent />
</Preview>
</Preview>;
```
This renders the JSX content exactly as it would if you’d placed it directly in the MDX, but it also inserts the source snippet in a [Source](#source) block beneath the block.

52
docs/writing-docs/docs-page.md
View File

@ -4,9 +4,9 @@ title: 'DocsPage'
When you install [Storybook Docs](https://github.com/storybookjs/storybook/blob/next/addons/docs/README.md), DocsPage is the zero-config default documentation that all stories get out of the box. It aggregates your stories, text descriptions, docgen comments, props tables, and code examples into a single page for each component.
The best practice for docs is for each component to have its own set of documentation and stories.
The best practice for docs is for each component to have its own set of documentation and stories.
### Component parameter
## Component parameter
Storybook uses the `component` key in the story file’s default export to extract the component's description and props.
@ -20,13 +20,12 @@ export default {
};
```
### Subcomponents parameter
## Subcomponents parameter
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.
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
// ButtonGroup.stories.js
@ -35,7 +34,7 @@ import { Button, ButtonGroup } from './ButtonGroup';
export default {
title: 'Path/to/ButtonGroup',
component: ButtonGroup,
subcomponents: { Button},
subcomponents: { Button },
};
```
@ -45,8 +44,7 @@ Subcomponent `ArgsTables` will show up in a tabbed interface along with the prim
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.
### Replacing DocsPage
## Replacing DocsPage
Replace DocsPage template with your own for the entire Storybook, a specific component, or a specific story.
@ -56,7 +54,7 @@ Override the `docs.page` [parameter](../writing-stories/parameters.md):
- With MDX docs.
- With a custom component
#### Story-level
### Story-level
Override the `docs.page` [parameter](../writing-stories/parameters.md#story-parameters) in the story definition.
@ -64,10 +62,10 @@ Override the `docs.page` [parameter](../writing-stories/parameters.md#story-para
// Button.stories.js
export const Primary = ButtonStory.bind({});
Primary.parameters = { docs: { page: null } }
Primary.parameters = { docs: { page: null } };
```
#### Component-level
### Component-level
Override the `docs.page` [parameter](../writing-stories/parameters.md#component-parameters) in the default export of the story file.
@ -78,15 +76,15 @@ import { Button } from './Button';
export default {
title: 'Storybook Examples/Button',
component: Button,
parameters: {
docs: {
page: null
}
parameters: {
docs: {
page: null,
},
},
};
```
#### Global-level
### Global-level
Override the `docs.page` [parameter](../writing-stories/parameters.md#global-parameters) in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
@ -96,11 +94,11 @@ Override the `docs.page` [parameter](../writing-stories/parameters.md#global-par
export const parameters { docs: { page: null } });
```
### Remixing DocsPage using doc blocks
## Remixing DocsPage using doc blocks
Doc blocks are the basic building blocks of Storybook Docs. DocsPage composes them to provide a reasonable UI documentation experience out of the box.
Doc blocks are the basic building blocks of Storybook Docs. DocsPage composes them to provide a reasonable UI documentation experience out of the box.
If you want to make minor customizations to the default DocsPage but don’t want to write your own MDX you can remix DocsPage. That allows you to reorder, add, or omit doc blocks without losing Storybook’s automatic docgen capabilities.
If you want to make minor customizations to the default DocsPage but don’t want to write your own MDX you can remix DocsPage. That allows you to reorder, add, or omit doc blocks without losing Storybook’s automatic docgen capabilities.
Here's an example of rebuilding DocsPage for the Button component using doc blocks:
@ -144,23 +142,23 @@ Apply a similar technique to remix the DocsPage at the [story](#story-level), [c
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
## Story file names
Unless you use a custom [webpack configuration](../configure/integration#extending-storybooks-webpack-config), all of your story files should have the suffix `*.stories.@(j|t)sx?`. For example, "Badge.stories.js" or "Badge.stories.tsx". This tells Storybook and its docs preset to display the docs based on the file contents.
### Inline stories vs. iframe stories
## Inline stories vs. iframe stories
DocsPage displays all the stories of a component in one page. You have the option of rendering those stories inline or in an iframe.
DocsPage displays all the stories of a component in one page. You have the option of rendering those stories inline or in an iframe.
By default, we render React and Vue stories inline. Stories from other supported frameworks will render in an `<iframe>` by default.
By default, we render React and Vue stories inline. Stories from other supported frameworks will render in an `<iframe>` by default.
The iframe creates a clean separation between your code and Storybook’s UI. But using an iframe has disadvantages. You have to explicitly set the height of iframe stories or you’ll see a scroll bar. And certain dev tools might not work right.
Render your framework’s stories inline using two docs configuration options in tandem, `inlineStories` and `prepareForInline`.
Render your framework’s stories inline using two docs configuration options in tandem, `inlineStories` and `prepareForInline`.
Setting `inlineStories` to `true` tells Storybook to stop putting your stories in an iframe. The `prepareForInline` accepts a function that transforms story content from your given framework to something React can render (Storybook’s UI is built in React).
Setting `inlineStories` to `true` tells Storybook to stop putting your stories in an iframe. The `prepareForInline` accepts a function that transforms story content from your given framework to something React can render (Storybook’s UI is built in React).
Different frameworks will need to approach this in different ways. Angular, for example, might convert its story content into a custom element (you can read about that [here](https://angular.io/guide/elements)).
Different frameworks will need to approach this in different ways. Angular, for example, might convert its story content into a custom element (you can read about that [here](https://angular.io/guide/elements)).
Here’s an example of how to render Vue stories inline. The following docs config block uses `prepareForInline` along with an effect hook provided by [@egoist/vue-to-react](https://github.com/egoist/vue-to-react).
@ -181,6 +179,6 @@ export const parameters = {
};
```
With this function, anyone using the docs addon for [@storybook/vue](https://github.com/storybookjs/storybook/tree/master/app/vue) can make their stories render inline, either globally with the inlineStories docs parameter, or on a per-story-basis using the inline prop on the `<Story>` doc block.
With this function, anyone using the docs addon for [@storybook/vue](https://github.com/storybookjs/storybook/tree/master/app/vue) can make their stories render inline, either globally with the inlineStories docs parameter, or on a per-story-basis using the inline prop on the `<Story>` doc block.
If you come up with an elegant and flexible implementation for the `prepareForInline` function for your own framework, let us know. We'd love to make it the default configuration to make inline stories more accessible for a larger variety of frameworks!

7
docs/writing-docs/introduction.md
View File

@ -1,8 +1,8 @@
---
title: 'Introduction'
title: 'How to document components'
---
When you write component stories during development, you also create basic documentation to revisit later.
When you write component stories during development, you also create basic documentation to revisit later.
Storybook gives you tools to expand this basic documentation with prose and layout that feature your components and stories prominently. That allows you to create UI library usage guidelines, design system sites, and more.
@ -15,9 +15,8 @@ Storybook gives you tools to expand this basic documentation with prose and layo
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.md), 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](./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).

57
docs/writing-docs/mdx.md
View File

@ -8,8 +8,7 @@ In addition, you can write pure documentation pages in MDX and add them to Story
![MDX simple example result](./mdx-hero.png)
### Basic example
## Basic example
Let's get started with an example that combines Markdown with a single story:
@ -28,26 +27,27 @@ Markdown documentation.
export const Template = (args) => <Checkbox {...args} />
<Preview>
<Story name="Unchecked" args={{
<Story name="Unchecked" args={{
label: 'Unchecked'
}}>
{Template.bind({})}
</Story>
<Story name="Checked" args={{
label: 'Unchecked',
checked: true
<Story name="Checked" args={{
label: 'Unchecked',
checked: true
}}>
{Template.bind({})}
</Story>
<Story name="Secondary" args={{
label: 'Secondary',
checked: true,
label: 'Secondary',
checked: true,
appearance: 'secondary'
}}>
{Template.bind({})}
</Story>
</Preview>
```
And here's how that's rendered in Storybook:
![MDX simple example result](./mdx-simple.png)
@ -56,7 +56,7 @@ As you can see there's a lot going on here. We're writing Markdown, we're writin
Let's break it down.
### MDX-flavored CSF
## MDX-flavored CSF
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.
@ -68,11 +68,11 @@ For example, here's the first story from the Checkbox example above, rewritten i
import React from 'react';
import { Checkbox } from './Checkbox';
export default {
title: "MDX/Checkbox",
component: Checkbox
export default {
title: 'MDX/Checkbox',
component: Checkbox,
};
const Template = (args) => <Checkbox {...args} />
const Template = (args) => <Checkbox {...args} />;
export const Unchecked = Template.bind({});
Unchecked.args = { label: 'Unchecked' };
@ -80,7 +80,7 @@ Unchecked.args = { label: 'Unchecked' };
There's a one-to-one mapping from the code in MDX to CSF. As a user, this means your existing Storybook knowledge should translate between the two.
### Writing stories
## Writing stories
Let's look at a more realistic example to see how MDX works:
@ -100,8 +100,8 @@ export const Template = (args) => <Badge {...args } />
Let's define a story for our `Badge` component:
<Story name="positive" args={{
status: 'positive',
label: 'Positive'
status: 'positive',
label: 'Positive'
}}>
{Template.bind({})}
</Story>
@ -110,7 +110,7 @@ We can drop it in a `Preview` to get a code snippet:
<Preview>
<Story name="negative" args={{
status: 'negative',
status: 'negative',
label: 'Negative'
}}>
{Template.bind({})}
@ -124,24 +124,24 @@ with unique URLs which is great for review and testing.
<Preview>
<Story name="warning" args={{
status: warning,
label: 'Warning'
label: 'Warning'
}}>
{Template.bind({})}
</Story>
<Story name="neutral" args={{
status: 'neutral',
label: 'Neutral'
status: 'neutral',
label: 'Neutral'
}}>
{Template.bind({})}
</Story>
<Story name="error" args={{
status: 'error',
label: 'Error'
status: 'error',
label: 'Error'
}}>
{Template.bind({})}
</Story>
<Story name="with icon" args={{
status: warning,
status: warning,
label: (<Icon icon="check" inline /> with icon)
)}}>
{Template.bind({})}
@ -154,8 +154,7 @@ And here's how that gets rendered in Storybook:
![MDX page](./mdx-page.png)
### Embedding stories
## Embedding stories
Suppose you have an existing story and want to embed it into your docs. Here's how to show a story with ID some--id. Check the browser URL in Storybook v5+ to find a story's ID.
@ -172,7 +171,7 @@ And Markdown here
You can also use the rest of the MDX features in conjunction with embedding. That includes source, preview, and prop tables.
### Decorators and parameters
## Decorators and parameters
To add decorators and parameters in MDX:
@ -192,7 +191,7 @@ To add decorators and parameters in MDX:
Global parameters and decorators work just like before.
### Documentation-only MDX
## Documentation-only MDX
Typically, when you use Storybook MDX, you define stories in the MDX and documentation is automatically associated with those stories. But what if you want to write Markdown-style documentation without any stories inside?
@ -204,7 +203,7 @@ To get a "documentation-only story", in your UI, define a `<Meta>` as you normal
![MDX docs only story](./mdx-documentation-only.png)
### MDX file names
## MDX file names
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.
@ -212,4 +211,4 @@ Unless you use a custom [webpack configuration](../configure/integration.md#exte
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>
</div>

63
docs/writing-stories/args.md
View File

@ -2,19 +2,17 @@
title: 'Args'
---
A story is a component with a set of arguments (props, slots, inputs, etc). “Args” are Storybook’s mechanism for defining those arguments as a first class entity that’s machine readable. This allows Storybook and its addons to live edit components. You *do not* need to change your underlying component code to use args.
A story is a component with a set of arguments (props, slots, inputs, etc). “Args” are Storybook’s mechanism for defining those arguments as a first class entity that’s machine readable. This allows Storybook and its addons to live edit components. You _do not_ need to change your underlying component code to use args.
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.md#using-args) section. For details on how args work, read on.
### Args object
## Args object
The args object can be defined at the story and component level (see below). It is an object with string keys, where values can have any type that is allowed to be passed into a component in your framework.
### Story args
## Story args
To define the args of a single story, use the `args` CSF story key:
@ -26,7 +24,7 @@ export const Primary = Template.bind({});
Primary.args = {
primary: true,
label: 'Primary',
}
};
```
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:
@ -39,13 +37,12 @@ export const PrimaryLongName = Template.bind({});
PrimaryLongName.args = {
...Primary.args,
label: 'Primary with a really long name',
}
};
```
In the above example, we use the [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) feature of ES 2015.
### Component args
## Component args
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:
@ -54,7 +51,7 @@ You can also define args at the component level; such args will apply to all sto
import Button from './Button';
export default {
title: "Button",
title: 'Button',
component: Button,
args: {
// Now all Button stories will be primary.
@ -63,25 +60,24 @@ export default {
};
```
### Args composition
## Args composition
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 = {
primary: true,
label: 'Button',
}
};
const Secondary = ButtonStory.bind({});
Secondary.args = {
...Primary.args,
primary: false,
}
};
```
<div class="aside">
@ -109,43 +105,42 @@ LoggedIn.args = {
...Header.LoggedIn.args,
};
```
<details>
<summary>Using args in addons</summary>
If you are [writing an addon](../api/addons.md) 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';
```js
// your-addon/register.js
import { useArgs } from '@storybook/api';
const [args, updateArgs,resetArgs] = useArgs();
const [args, updateArgs, resetArgs] = useArgs();
// To update one or more args:
updateArgs({ key: 'value' });
// To update one or more args:
updateArgs({ key: 'value' });
// To reset one (or more) args:
resetArgs(argNames:['key']);
// To reset one (or more) args:
resetArgs((argNames: ['key']));
// To reset all args
resetArgs();
```
// To reset all args
resetArgs();
```
</details>
<details>
<summary>parameters.passArgsFirst</summary>
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 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.md#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
```js
// .storybook/preview.js
export const parameter = { passArgsFirst : false }.
```
export const parameter = { passArgsFirst : false }.
```
<div class="aside">

52
docs/writing-stories/decorators.md
View File

@ -6,7 +6,7 @@ A decorator is a way to wrap a story in extra “rendering” functionality. Man
When writing stories, decorators are typically used to wrap stories with extra markup or context mocking.
### Wrap stories with extra markup
## Wrap stories with extra markup
Some components require a “harness” to render in a useful way. For instance if a component runs right up to its edges, you might want to space it inside Storybook. Use a decorator to add spacing for all stories of the component.
@ -17,15 +17,19 @@ Some components require a “harness” to render in a useful way. For instance
export default {
component: TextComponent,
decorators: [(Story) => <div style={{ margin: '3em' }}><Story/></div>]
}
decorators: [
(Story) => (
<div style={{ margin: '3em' }}>
<Story />
</div>
),
],
};
```
![Story with padding](./decorators-padding.png)
### “Context” for mocking
## “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.md#configure-story-rendering):
@ -34,7 +38,11 @@ Some libraries require components higher up in the component hierarchy to render
import { ThemeProvider } from 'styled-components';
export const decorators = [
(Story) => <ThemeProvider theme="default"><Story/></ThemeProvider>,
(Story) => (
<ThemeProvider theme="default">
<Story />
</ThemeProvider>
),
];
```
@ -46,12 +54,11 @@ The second argument to a decorator function is the **story context** which in pa
- `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
### 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.md) section.
### Story decorators
## Story decorators
To define a decorator for a single story, use the `decorators` key on a named export:
@ -62,29 +69,40 @@ 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/doc-blocks.md#source) docblock works best when you do this.
### Component decorators
## Component decorators
To define a decorator for all stories of a component, use the `decorators` key of the default CSF export:
```js
import Button from './Button';
export default {
title: "Button",
title: 'Button',
component: Button,
decorators: [(Story) => <div style={{ margin: '3em' }}><Story/></div>]
decorators: [
(Story) => (
<div style={{ margin: '3em' }}>
<Story />
</div>
),
],
};
```
### Global decorators
## Global decorators
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>]
export const decorators = [
(Story) => (
<div style={{ margin: '3em' }}>
<Story />
</div>
),
];
```
### Decorator inheritance
## Decorator inheritance
Like parameters, decorators can be defined globally, at the component level and for a single story (as we’ve seen).

80
docs/writing-stories/introduction.md
View File

@ -1,12 +1,12 @@
---
title: 'Introduction'
title: 'How to write stories'
---
**A story captures the rendered state of a UI component**. It’s a function that returns a component’s state given a set of arguments.
A story captures the rendered state of a UI component. It’s a function that returns a component’s state given a set of arguments.
Storybook uses the generic term arguments (args for short) when talking about React’s `props`, Vue’s `slots`, Angular’s `@input`, and other similar concepts.
### Where to put stories
## Where to put stories
A component’s stories are defined in a story file that lives alongside the component file. The story file is for development-only, it won't be included in your production bundle.
@ -15,13 +15,13 @@ Button.js | ts
Button.stories.js | ts
```
### Component Story Format
## Component Story Format
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.
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.
#### Default export
### Default export
The default export metadata controls how Storybook lists your stories and provides information used by addons. For example, here’s the default export for a story file `Button.stories.js`:
@ -33,10 +33,10 @@ import { Button } from './Button';
export default {
title: 'Components/Button',
component: Button,
}
};
```
#### Defining stories
### Defining stories
Use the named exports of a CSF file to define your component’s stories. Here’s how to render `Button` in the “primary” state and export a story called `Primary`.
@ -47,27 +47,25 @@ import { Button } from './Button';
export default {
title: 'Components/YourComponent',
component: YourComponent,
}
};
export const Primary = () => <Button primary label="Button" />;
```
#### Rename stories
### 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';
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
## 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.
@ -80,9 +78,9 @@ export const Tertiary = () => <Button background="#ff0" label="📚📕📈🤓"
```
This is straightforward for components with few stories, but can be repetitive with many stories.
This is straightforward for components with few stories, but can be repetitive with many stories.
#### Using args
### Using args
Refine this pattern by defining a master template for a component’s stories that allows you to pass in `args`. This reduces the unique code you’ll need to write and maintain for each story.
@ -112,15 +110,16 @@ import { Primary, Secondary } from '../Button.stories';
export default {
title: 'ButtonGroup',
component: ButtonGroup,
}
const Template = (args) => <ButtonGroup {...args} />
};
const Template = (args) => <ButtonGroup {...args} />;
export const Pair = Template.bind({});
Pair.args = {
buttons: [ Primary.args, Secondary.args ],
buttons: [Primary.args, Secondary.args],
orientation: 'horizontal',
};
```
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.md) panel. This means your team can dynamically change components in Storybook to stress test and find edge cases.
@ -141,7 +140,7 @@ Addons can enhance args. For instance, [Actions](../essentials/actions.md) auto
/>
</video>
#### Using parameters
### Using parameters
Parameters are Storybook’s method of defining static metadata for stories. A story’s parameters can be used to provide configuration to various addons at the level of a story or group of stories.
@ -157,21 +156,20 @@ export default {
parameters: {
backgrounds: {
values: [
{ name: 'red', value: '#f00', },
{ name: 'green', value: '#0f0', },
{ name: 'blue', value: '#00f', },
]
}
}
}
{ name: 'red', value: '#f00' },
{ name: 'green', value: '#0f0' },
{ name: 'blue', value: '#00f' },
],
},
},
};
```
![Background colors parameter](./parameters-background-colors.png)
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
### Using decorators
Decorators are a mechanism to wrap a component in arbitrary markup when rendering a story. Components are often created with assumptions about ‘where’ they render. Your styles might expect a theme or layout wrapper. Or your UI might expect certain context or data providers.
@ -184,33 +182,38 @@ import Button from './Button';
export default {
title: 'Button',
component: Button,
decorators: [(Story) => <div style={{ padding: '3em' }}><Story /></div>]
}
decorators: [
(Story) => (
<div style={{ padding: '3em' }}>
<Story />
</div>
),
],
};
```
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
## Stories for two or more components
When building design systems or component libraries, you may have two or more components that are designed to work together. For instance, if you have a parent `List` component, it may require child `ListItem` components.
```js
import List from './List'
import List from './List';
export default {
component: List,
title: 'List',
};
// Always an empty list, not super interesting
const Template = (args) => <List {...args} />
const Template = (args) => <List {...args} />;
```
In such cases, it makes sense to render something a different function for each story:
```js
import List from './List'
import ListItem from './ListItem'
import List from './List';
import ListItem from './ListItem';
export default {
component: List,
title: 'List',
@ -251,4 +254,3 @@ export const ManyItems = (args) => (
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>

36
docs/writing-stories/naming-components-and-hierarchy.md
View File

@ -5,19 +5,17 @@ title: 'Naming components and hierarchy'
The title of the component you export in the `default` export controls the name shown in the sidebar.
```js
// Button.stories.js
export default {
title: 'Button'
}
title: 'Button',
};
```
Yields this:
![Stories hierarchy without paths](./naming-hierarchy-no-path.png)
### Grouping
## Grouping
It is also possible to group related components in an expandable interface in order to help with Storybook organization. To do so, use the `/` as a separator:
@ -25,29 +23,29 @@ It is also possible to group related components in an expandable interface in or
// Button.stories.js
export default {
title: 'Design System/Atoms/Button'
}
title: 'Design System/Atoms/Button',
};
```
```js
// Checkbox.stories.js
export default {
title: 'Design System/Atoms/Checkbox'
}
title: 'Design System/Atoms/Checkbox',
};
```
Yields this:
![Stories hierarchy with paths](./naming-hierarchy-with-path.png)
### Roots
## 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.
We recommend naming components according to the file hierarchy.
### Sorting stories
## Sorting stories
By default, stories are sorted in the order in which they were imported. This can be overridden by adding `storySort` to the `options` parameters in your `preview.js` file.
@ -73,18 +71,18 @@ export const parameters = {
options: {
storySort: {
method: '',
order: [],
locales: '',
order: [],
locales: '',
},
},
};
```
| Field | Type | Description | Required | Default Value |Example |
| ------------- |:-------------:|:------------------------------------------------------:|:--------:|:----------------------:|:-----------------------:|
| **method** | String |Tells Storybook in which order the stories are displayed|No |Storybook configuration |`'alphabetical'` |
| **order** | Array |The stories to be show, ordered by supplied name |No |Empty Array `[]` |`['Intro', 'Components']`|
| **locales** | String |The locale required to be displayed |No |System locale |`en-US` |
| Field | Type | Description | Required | Default Value | Example |
| ----------- | :----: | :------------------------------------------------------: | :------: | :---------------------: | :-----------------------: |
| **method** | String | Tells Storybook in which order the stories are displayed | No | Storybook configuration | `'alphabetical'` |
| **order** | Array | The stories to be show, ordered by supplied name | No | Empty Array `[]` | `['Intro', 'Components']` |
| **locales** | String | The locale required to be displayed | No | System locale | `en-US` |
To sort your stories alphabetically, set `method` to `'alphabetical'` and optionally set the `locales` string. To sort your stories using a custom list, use the `order` array; stories that don't match an item in the `order` list will appear after the items in the list.

44
docs/writing-stories/parameters.md
View File

@ -2,11 +2,11 @@
title: 'Parameters'
---
**Parameters** are a set of static, named metadata about a story, typically used to control the behavior 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.
### Story parameters
## Story parameters
We can set a parameter for a single story with the `parameters` key on a CSF export:
@ -14,21 +14,21 @@ We can set a parameter for a single story with the `parameters` key on a CSF exp
// Button.story.js
export const Primary = Template.bind({});
Primary.args ={
Primary.args = {
primary: true,
label: 'Button',
}
Primary.parameters = {
backgrounds:{
};
Primary.parameters = {
backgrounds: {
values: [
{ name: 'red', value: '#f00', },
{ name: 'green', value: '#0f0', },
{ name: 'red', value: '#f00' },
{ name: 'green', value: '#0f0' },
],
}
},
};
```
### Component parameters
## Component parameters
We can set the parameters for all stories of a component using the `parameters` key on the default CSF export:
@ -38,20 +38,20 @@ We can set the parameters for all stories of a component using the `parameters`
import Button from './';
export default {
title: "Button",
title: 'Button',
component: Button,
parameters: {
backgrounds: {
values: [
{ name: 'red', value: '#f00', },
{ name: 'green', value: '#0f0', },
{ name: 'red', value: '#f00' },
{ name: 'green', value: '#0f0' },
],
}
}
},
},
};
```
### Global parameters
## Global parameters
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):
@ -61,16 +61,16 @@ We can also set the parameters for **all stories** via the `parameters` export o
export const parameters = {
backgrounds: {
values: [
{ name: 'red', value: '#f00', },
{ name: 'green', value: '#0f0', },
{ name: 'red', value: '#f00' },
{ name: 'green', value: '#0f0' },
],
},
}
};
```
Setting a global parameter is a common way to configure addons. With backgrounds, you configure the list of backgrounds that every story can render in.
Setting a global parameter is a common way to configure addons. With backgrounds, you configure the list of backgrounds that every story can render in.
### Rules of parameter inheritance
## Rules of parameter inheritance
The way the global, component and story parameters are combined is:
@ -79,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.md)) it is a good idea to take this behavior 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.