mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-05 08:01:20 +08:00
Merge pull request #16073 from storybookjs/chore_update_essential_section
Chore: (Docs) Polish the Essentials section
This commit is contained in:
jonniebigodes
GitHub
commit
9831529d0a
@ -17,7 +17,7 @@ Actions work via supplying special Storybook-generated “action” arguments (r
|
||||
|
||||
### Action argType annotation
|
||||
|
||||
You can use [argTypes](../api/argtypes.md) to tell Storybook that an arg to your story should be an action. Usually it makes sense to do this at the component level (although it can be done per story):
|
||||
You can use [argTypes](../api/argtypes.md) to tell Storybook that an arg to your story should be an action. Usually, it makes sense to do this at the component level (although you can apply it per individual story):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -30,7 +30,7 @@ You can use [argTypes](../api/argtypes.md) to tell Storybook that an arg to your
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
When Storybook sees this argType it will create an arg that is set to a special “action” callback. If your component calls this arg (based on user interaction) the event will show up in the action panel:
|
||||
When Storybook sees this argType, it will create an arg set to a special “action” callback. If your component calls this arg (based on the user's interaction or through the `play` function), the event will show up in the action panel:
|
||||
|
||||
|
||||
|
||||
@ -51,7 +51,7 @@ Another option is to use a parameter to match all [argTypes](../api/argtypes.md)
|
||||
|
||||
<div class="aside">
|
||||
|
||||
NOTE: If you're generating argTypes in using another addon (like [docs](../writing-docs/introduction.md), which is the common behavior) you'll need to make sure that the actions addon loads **AFTER** the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md).
|
||||
💡 <strong>NOTE</strong>: If you're generating argTypes with another addon (like [docs](../writing-docs/introduction.md), which is the common behavior), ensure the actions addon <strong>AFTER</strong> the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering). This is default in [essentials](./introduction.md).
|
||||
|
||||
</div>
|
||||
|
||||
@ -70,8 +70,8 @@ It is also possible to detect if your component is emitting the correct HTML eve
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is `<eventname> <selector>`. Selector is optional; it defaults to all elements.
|
||||
This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is `<eventname> <selector>`. The selector is optional; it defaults to all elements.
|
||||
|
||||
## Advanced / legacy usage
|
||||
|
||||
There are also some older ways to use actions as documented in the [advanced README](../../addons/actions/ADVANCED.md).
|
||||
There are also some older ways to use actions as documented in the [advanced README](../../addons/actions/ADVANCED.md).
|
||||
Binary file not shown.
@ -2,7 +2,7 @@
|
||||
title: 'Backgrounds'
|
||||
---
|
||||
|
||||
The backgrounds toolbar item allows you to adjust the background that your story is rendered on via Storybook’s UI:
|
||||
The backgrounds toolbar addon allows you to set the background color in which the story renders in the UI:
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -13,9 +13,9 @@ The backgrounds toolbar item allows you to adjust the background that your story
|
||||
|
||||
## Configuration
|
||||
|
||||
By default, the backgrounds toolbar presents you with a light and dark background.
|
||||
By default, the backgrounds toolbar includes a light and dark background.
|
||||
|
||||
But you're not restricted to these two backgrounds, you can configure your own set of colors with the `parameters.backgrounds` [parameter](../writing-stories/parameters.md) in your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
But you're not restricted to these backgrounds, you can configure your own set of colors with the `parameters.backgrounds` [parameter](../writing-stories/parameters.md) in your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -27,9 +27,11 @@ But you're not restricted to these two backgrounds, you can configure your own s
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
If you define the `default` property, the backgrounds toolbar will set that color for every story where the parameter is applied to. If you don't set it, the colors will be available but not automatically set when a story is rendered.
|
||||
If you define the `default` property, the addon will apply it to all stories. Otherwise, it's only listed as an available color.
|
||||
|
||||
You can also set backgrounds on per-story or per-component basis by using [parameter inheritance](../writing-stories/parameters.md#component-parameters):
|
||||
### Extending the configuration
|
||||
|
||||
You can also define backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.md#component-parameters):
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -42,7 +44,7 @@ You can also set backgrounds on per-story or per-component basis by using [param
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
You can also only override a single key on the backgrounds parameter, for instance to set a different default value for a single story:
|
||||
You can also override a single key on the `backgrounds` parameter, for instance, to set a different default value for a particular story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -55,6 +57,8 @@ You can also only override a single key on the backgrounds parameter, for instan
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Disable backgrounds
|
||||
|
||||
If you want to disable backgrounds in a story, you can do so by setting the `backgrounds` parameter like so:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
@ -70,11 +74,9 @@ If you want to disable backgrounds in a story, you can do so by setting the `bac
|
||||
|
||||
## Grid
|
||||
|
||||
Backgrounds toolbar also comes with a Grid selector. This way you can easily see if your components are aligned.
|
||||
Backgrounds toolbar also includes a Grid selector. This way, you can quickly see if your components are aligned.
|
||||
|
||||
By default you don't need to configure anything in order to use it, but the properties of the grid are fully configurable.
|
||||
|
||||
Each of these properties have the following default values in case they are not passed:
|
||||
You don't need additional configuration to get started. But its properties are fully customizable, if you don't supply any value to any of its properties, they'll default to the following values:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -87,7 +89,9 @@ Each of these properties have the following default values in case they are not
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
If you wish to disable the grid in a story, you can do so by setting the `backgrounds` parameter like so:
|
||||
### Disable the grid
|
||||
|
||||
If you need to disable the grid for a specific story, set the `backgrounds` parameter to the following:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: 'Controls'
|
||||
---
|
||||
|
||||
Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically, without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.
|
||||
Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -17,17 +17,17 @@ Controls does not require any modification to your components. Stories for contr
|
||||
- Portable. Reuse your interactive stories in documentation, tests, and even in designs.
|
||||
- Rich. Customize the controls and interactive data to suit your exact needs.
|
||||
|
||||
To use the Controls addon, you need to write your stories using [args](../writing-stories/args.md). Storybook will automatically generate UI controls based on your args and what it can infer about your component; but you can configure the controls further using [argTypes](../api/argtypes.md), see below.
|
||||
To use the Controls addon, you need to write your stories using [args](../writing-stories/args.md). Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using [argTypes](../api/argtypes.md), see below.
|
||||
|
||||
<div class="aside">
|
||||
|
||||
If you have written stories in the older pre-Storybook 6 style, you may want to read the [args & controls migration guide](https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5) to help understand how to convert your stories for args.
|
||||
💡 If you have stories in the older pre-Storybook 6 style, check the <a href="https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5">args & controls migration guide</a> to learn how to convert your existing stories for args.
|
||||
|
||||
</div>
|
||||
|
||||
## Choosing the control type
|
||||
|
||||
By default, Storybook will choose a control for each arg based on the initial value of the arg. This works well with some kind of args, such as boolean values or free-text strings, but in other cases you want a more restricted control.
|
||||
By default, Storybook will choose a control for each arg based on the initial value of the arg. It works well with certain types of args, such as boolean values or free-text strings, but in other cases, you want a more restricted control.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -61,11 +61,11 @@ By default, Storybook will render a free text input for the `variant` arg:
|
||||
|
||||
|
||||
|
||||
This works as long as you type a valid string into the auto-generated text control, but it's not the best UI for our scenario, given that the component only accepts `primary` or `secondary` as variants. Let’s replace it with Storybook’s radio component.
|
||||
It works as long as you type a valid string into the auto-generated text control. Still, it's not the best UI for our scenario, given that the component only accepts `primary` or `secondary` as variants. Let’s replace it with Storybook’s radio component.
|
||||
|
||||
We can specify which controls get used by declaring a custom [argType](../api/argtypes.md) for the `variant` property. ArgTypes encode basic metadata for args, such as name, description, defaultValue for an arg. These get automatically filled in by Storybook Docs.
|
||||
|
||||
ArgTypes can also contain arbitrary annotations which can be overridden by the user. Since `variant` is a property of the component, let's put that annotation on the default export.
|
||||
ArgTypes can also contain arbitrary annotations, which the user can override. Since `variant` is a property of the component, let's put that annotation on the default export.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -91,7 +91,7 @@ For a few types, Controls will automatically infer them by using [regex](https:/
|
||||
| **color** | `/(background\|color)$/i` | Will display a color picker UI for the args that match it |
|
||||
| **date** | `/Date$/` | Will display a date picker UI for the args that match it |
|
||||
|
||||
To do so, use the `matchers` property in `controls` parameter:
|
||||
To do so, use the `matchers` property in the `controls` parameter:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -105,7 +105,7 @@ To do so, use the `matchers` property in `controls` parameter:
|
||||
|
||||
## Fully custom args
|
||||
|
||||
Up until now, we only used auto-generated controls based on the component we're writing stories for. If we are writing [complex stories](../workflows/stories-for-multiple-components.md) we may want to add controls for args that aren’t part of the component.
|
||||
Up until now, we only used auto-generated controls based on the component we're writing stories for. If we are writing [complex stories](../workflows/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -135,9 +135,9 @@ Using `argTypes`, you can change the display and behavior of each control.
|
||||
|
||||
### Dealing with complex values
|
||||
|
||||
You'll notice when dealing with non-primitive values, you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g. Controls addon) and the preview (your story).
|
||||
You'll notice that when dealing with non-primitive values, you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the `args` param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story).
|
||||
|
||||
One way to deal with this is to use primitive values (e.g. strings) as arg values, and using a story template to convert these values to their complex counterpart before rendering. This isn't the nicest way to do it (see below), but certainly the most flexible.
|
||||
One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom `render` function to convert these values to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -157,7 +157,7 @@ One way to deal with this is to use primitive values (e.g. strings) as arg value
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a `mapping`. Additionally, you can specify `control.labels` to configure custom labels for your checkbox, radio or select input.
|
||||
Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a `mapping`. Additionally, you can specify `control.labels` to configure custom labels for your checkbox, radio, or select input.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -169,7 +169,7 @@ Unless you need the flexibility of a function, an easier way to map primitives t
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Note that both `mapping` and `control.labels` don't have to be exhaustive. If the currently selected option is not listed, it will be used verbatim.
|
||||
Note that both `mapping` and `control.labels` don't have to be exhaustive. If the currently selected option is not listed, it's used verbatim.
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -216,7 +216,7 @@ If you need to customize a control for a number data type in your story, you can
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
If you don't provide a specific one, it defaults to the number control type.
|
||||
💡 If you don't provide a specific one, it defaults to the number control type.
|
||||
</div>
|
||||
|
||||
### Parameters
|
||||
@ -225,7 +225,7 @@ Controls supports the following configuration [parameters](../writing-stories/pa
|
||||
|
||||
## Show full documentation for each property
|
||||
|
||||
Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete [ArgsTable](../writing-docs/doc-blocks.md#argstable) doc block in the controls pane. The description and default value rendering can be [customized](#fully-custom-args) in the same way as the doc block.
|
||||
Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete [ArgsTable](../writing-docs/doc-blocks.md#argstable) doc block in the controls panel. The description and default value rendering can be [customized](#fully-custom-args) in the same way as the doc block.
|
||||
|
||||
To enable expanded mode globally, add the following to [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
|
||||
@ -252,16 +252,12 @@ For `color` controls, you can specify an array of `presetColors`, either on the
|
||||
|
||||
export const parameters = {
|
||||
controls: {
|
||||
presetColors: [
|
||||
{ color: '#ff4785', title: 'Coral' },
|
||||
'rgba(0, 159, 183, 1)',
|
||||
'#fe4a49',
|
||||
]
|
||||
presetColors: [{ color: '#ff4785', title: 'Coral' }, 'rgba(0, 159, 183, 1)', '#fe4a49'],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
These will then be available as swatches in the color picker. Color presets can be defined as an object with `color` and `title`, or as a simple CSS color string. The `title` will be shown when you hover over the color swatch. In case no title is specified, the nearest CSS color name will be used instead.
|
||||
Color presets can be defined as an object with `color` and `title` or a simple CSS color string. These will then be available as swatches in the color picker. When you hover over the color swatch, you'll be able to see its title. If none is specified, it will default to the nearest CSS color name instead.
|
||||
|
||||
### Disable controls for specific properties
|
||||
|
||||
@ -289,7 +285,7 @@ Resulting in the following change in Storybook UI:
|
||||
/>
|
||||
</video>
|
||||
|
||||
The previous example also removed the prop documentation from the table. In some cases this is fine, however sometimes you might want to still render the prop documentation but without a control. The following example illustrates how:
|
||||
The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation, but without a control. The following example illustrates how:
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
@ -300,7 +296,7 @@ paths={[
|
||||
|
||||
<div class="aside">
|
||||
|
||||
As with other Storybook properties, such as [decorators](../writing-stories/decorators.md) the same principle can also be applied at a story-level for more granular cases.
|
||||
💡 As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases.
|
||||
|
||||
</div>
|
||||
|
||||
@ -320,9 +316,9 @@ If you don't plan to handle the control args inside your Story, you can remove t
|
||||
|
||||
## Filtering controls
|
||||
|
||||
In some cases, you may want to either only present a few controls in the controls panel, or present all controls except a small set.
|
||||
In specific cases, you may require to display only a limited number of controls in the controls panel, or all of them except a particular set.
|
||||
|
||||
To make this possible, you can use optional `include` and `exclude` configuration fields in the `controls` parameter, which can be set to either an array of strings, or a regular expression.
|
||||
To make this possible, you can use optional `include` and `exclude` configuration fields in the `controls` parameter, which you can define as an array of strings, or as a regular expression.
|
||||
|
||||
Consider the following story snippets:
|
||||
|
||||
@ -339,7 +335,7 @@ Consider the following story snippets:
|
||||
|
||||
## Sorting controls
|
||||
|
||||
By default, controls are unsorted and use whatever order the args data is processed in (`none`). It can also be configured to sort alphabetically by arg name (`alpha`) or alphabetically required args first (`requiredFirst`).
|
||||
By default, controls are unsorted and use whatever order the args data is processed in (`none`). Additionally, you can sort them alphabetically by the arg's name (`alpha`) or with the required args first (`requiredFirst`).
|
||||
|
||||
Consider the following snippet to force required args first:
|
||||
|
||||
@ -352,4 +348,4 @@ Consider the following snippet to force required args first:
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -20,12 +20,12 @@ If you ran `sb init` to include Storybook in your project, the Essentials addon
|
||||
If you're upgrading from a previous Storybook version, you'll need to run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
npm install --save-dev @storybook/addon-essentials
|
||||
```
|
||||
#With npm
|
||||
npm install -D @storybook/addon-essentials
|
||||
|
||||
<div class="aside">
|
||||
💡 <strong>Note</strong>: If you're using <a href="https://yarnpkg.com/">yarn</a> as a package manager, you'll need to adjust the command accordingly.
|
||||
</div>
|
||||
#With yarn
|
||||
yarn add -D @storybook/addon-essentials
|
||||
```
|
||||
|
||||
Update your Storybook configuration (in `.storybook/main.js`) to include the Essentials addon.
|
||||
|
||||
|
||||
@ -26,4 +26,4 @@ With Storybook's Outline addon, you can toggle the outlines associated with all
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source src="addon-outline-optimized.mp4" type="video/mp4"/>
|
||||
</video>
|
||||
</video>
|
||||
@ -2,11 +2,11 @@
|
||||
title: 'Toolbars & globals'
|
||||
---
|
||||
|
||||
Storybook ships with toolbar items to control the [viewport](./viewport.md) and [background](./backgrounds.md) the story renders in. You can also create your own toolbar items which control special “globals” which you can then read to create [decorators](../writing-stories/decorators.md) to control story rendering.
|
||||
Storybook ships with toolbar addons to control the [viewport](./viewport.md) and [background](./backgrounds.md) the story renders in. You can also create your own toolbar items which control special “globals” which you can then read to create [decorators](../writing-stories/decorators.md) to control story rendering.
|
||||
|
||||
## Globals
|
||||
|
||||
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.
|
||||
Globals in Storybook represents “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.
|
||||
|
||||
@ -26,11 +26,11 @@ 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>
|
||||
|
||||
When you start your Storybook, you should see a new dropdown in your toolbar with options `light` and `dark`.
|
||||
When you start your Storybook, you should see a new dropdown with the `light` and `dark` options in your toolbar.
|
||||
|
||||
## Create a decorator
|
||||
|
||||
@ -50,7 +50,7 @@ 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.
|
||||
|
||||
@ -68,12 +68,12 @@ In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rende
|
||||
|
||||
<div class="aside">
|
||||
|
||||
The <code>icon</code> element used in the examples loads the icons from the <code>@storybook/components</code> package. See [here](../workflows/faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.
|
||||
💡 The <code>icon</code> element used in the examples loads the icons from the <code>@storybook/components</code> package. See [here](../workflows/faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.
|
||||
|
||||
</div>
|
||||
|
||||
<div class="aside">
|
||||
The <code>@storybook/addon-toolbars</code> addon is required to use toolbars. The toolbars addon is included by default in <code>@storybook/addon-essentials</code>.
|
||||
💡The <code>@storybook/addon-toolbars</code> addon is required to use toolbars. The toolbars addon is included by default in <code>@storybook/addon-essentials</code>.
|
||||
</div>
|
||||
|
||||
By adding the configuration element `right`, the text will be displayed on the right side in the toolbar menu once you connect it to a decorator.
|
||||
@ -116,7 +116,7 @@ Using the example above, you can modify any story to retrieve the **Locale** `gl
|
||||
|
||||
<div class="aside">
|
||||
|
||||
In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwards compatibility, the story context is passed as the first argument:
|
||||
💡 In Storybook 6.0, if you set the global option `passArgsFirst: false` for backward compatibility, the story context is passed as the first argument:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -136,9 +136,9 @@ In Storybook 6.0, if you set the global option `passArgsFirst: false` for backwa
|
||||
|
||||
## 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()`](../addons/addons-api.md#useglobals) hook to retrieve any globals you want.
|
||||
If you're working on a Storybook addon and need to retrieve globals, you can do so. The `@storybook/api` package provides a hook for this scenario. You can use the [`useGlobals()`](../addons/addons-api.md#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:
|
||||
Using the ThemeProvider example above, you could expand it to display which theme is active inside a panel as such:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -152,11 +152,11 @@ Using the ThemeProvider example above, you could expand it to display which curr
|
||||
|
||||
## Updating globals from within an addon
|
||||
|
||||
If you're working on a Storybook addon that needs to update the global and refreshes the UI, you can do so. As mentioned previously, the `@storybook/api` package provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you want.
|
||||
If you're working on a Storybook addon that needs to update the global and refreshes the UI, you can do so. As mentioned previously, the `@storybook/api` package provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you need.
|
||||
|
||||
Also, you can use the `@storybook/addons` and `@storybook/core-events` packages together to trigger the refresh.
|
||||
Also, you can use both `@storybook/addons` and `@storybook/core-events` packages together to trigger the refresh.
|
||||
|
||||
For example, if you were working on a [toolbar addon](../addons/addon-types.md#toolbars), and you want to refresh the UI and update the global once the user clicks on a button, like so:
|
||||
For example, if you were working on a [toolbar addon](../addons/addon-types.md#toolbars), and you want to refresh the UI and update the global once the user clicks on a button:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: 'Viewport'
|
||||
---
|
||||
|
||||
The Viewport toolbar item allows you to adjust the dimensions of the iframe your story is rendered in. This makes it easy to develop responsive UIs.
|
||||
The Viewport toolbar item allows you to adjust the dimensions of the iframe your story is rendered in. It makes it easy to develop responsive UIs.
|
||||
|
||||
<video autoPlay muted playsInline loop>
|
||||
<source
|
||||
@ -13,7 +13,7 @@ The Viewport toolbar item allows you to adjust the dimensions of the iframe your
|
||||
|
||||
### Configuration
|
||||
|
||||
By default, you are presented with a set of common viewports.
|
||||
Out of the box, the Viewport addon offers you a standard set of viewports that you can use.
|
||||
|
||||
If you want to change the default set of viewports, you can set the global `parameters.viewport` [parameter](../writing-stories/parameters.md) in your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering):
|
||||
|
||||
@ -27,7 +27,7 @@ If you want to change the default set of viewports, you can set the global `para
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
The viewport global can take a object with the following keys:
|
||||
The viewport global can take an object with the following keys:
|
||||
|
||||
| Field | Type | Description | Default Value |
|
||||
| ------------------- | :-----: | :---------------------------------------: | :------------: |
|
||||
@ -43,9 +43,9 @@ The viewports object needs the following keys:
|
||||
| **styles** | Object | Sets Inline styles to be applied to the story | `{width:0,height:0}` |
|
||||
| **type** | String | Type of the device (e.g. desktop, mobile, or tablet) | `desktop` |
|
||||
|
||||
### Use detailed set of devices
|
||||
### Use a detailed set of devices
|
||||
|
||||
By default Storybook uses a [minimal set of viewports](https://github.com/storybookjs/storybook/blob/master/addons/viewport/src/defaults.ts#L135) to get you started. But you're not restricted to these, the addon offers a more granular list of devices that you can use.
|
||||
By default, Storybook uses a [minimal set of viewports](https://github.com/storybookjs/storybook/blob/master/addons/viewport/src/defaults.ts#L135) to get you started. But you're not restricted to these. The addon offers a more granular list of devices that you can use.
|
||||
|
||||
Change your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) to the following:
|
||||
|
||||
@ -59,13 +59,13 @@ Change your [`.storybook/preview.js`](../configure/overview.md#configure-story-r
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
Once you start your Storybook, you'll see that now you have a whole different set of devices to use.
|
||||
Start your Storybook, and you'll see the new devices that you can use.
|
||||
|
||||
See [here](https://github.com/storybookjs/storybook/blob/master/addons/viewport/src/defaults.ts#L3) the complete list of devices and their configurations.
|
||||
|
||||
### Add new devices
|
||||
|
||||
If you have either a specific viewport, or a list of viewports that you need to use. You can modify your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) file to include them like so:
|
||||
If you have either a specific viewport or a list of viewports that you need to use, you can modify your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) file and include them:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -77,7 +77,7 @@ If you have either a specific viewport, or a list of viewports that you need to
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
To use them in your Storybook you'll need to make the following change:
|
||||
Make the following change to use them in your Storybook:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -93,7 +93,7 @@ Once you start Storybook, you'll see your new viewports and devices.
|
||||
|
||||
If you need, you can also add these two to another list of viewports.
|
||||
|
||||
For instance, if you wanted to use these two with the minimal set of viewports, you can do it like so:
|
||||
For instance, if you want to use these two with the minimal set of viewports, you can do it like so:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -105,15 +105,13 @@ For instance, if you wanted to use these two with the minimal set of viewports,
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
This will add both `Kindle Fire 2` and `Kindle Fire HD` to the list of devices. This is achieved by making use of the exported [`MINIMAL_VIEWPORTS`](https://github.com/storybookjs/storybook/blob/master/addons/viewport/src/defaults.ts#L135) property, by merging it with the new ones.
|
||||
Both viewports (`Kindle Fire 2` and `Kindle Fire HD`) will feature in the list of devices by merging them into the [`MINIMAL_VIEWPORTS`](https://github.com/storybookjs/storybook/blob/master/addons/viewport/src/defaults.ts#L135).
|
||||
|
||||
### Configuring per component or story
|
||||
|
||||
There are cases where it's not effective for you to use a certain visual viewport on a global scale and you need it to adjust it to a individual story.
|
||||
There are cases where it's not practical for you to use a specific visual viewport on a global scale, and you need it to adjust it to an individual story.
|
||||
|
||||
You can change your story through [parameters](../writing-stories/parameters.md) to include the viewports you need to use for your component.
|
||||
|
||||
[Parameters](../writing-stories/parameters.md) can be configured for a whole set of stories or a single story via the standard parameter API:
|
||||
Update your story through [parameters](../writing-stories/parameters.md) to include your viewports at a component level or for a specific story:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -136,9 +134,8 @@ You can change your story through [parameters](../writing-stories/parameters.md)
|
||||
|
||||
### Keyboard shortcuts
|
||||
|
||||
* Previous viewport: <kbd>shift</kbd> + <kbd>v</kbd>
|
||||
* Next viewport: <kbd>v</kbd>
|
||||
* Reset viewport: <kbd>alt</kbd> + <kbd>v</kbd>
|
||||
- Previous viewport: <kbd>shift</kbd> + <kbd>v</kbd>
|
||||
- Next viewport: <kbd>v</kbd>
|
||||
- Reset viewport: <kbd>alt</kbd> + <kbd>v</kbd>
|
||||
|
||||
|
||||
These shortcuts can be edited in Storybook's Keyboard shortcuts page.
|
||||
If you need, you can edit them on the shortcuts page.
|
||||
Loading…
x
Reference in New Issue
Block a user