mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 15:31:16 +08:00
180 lines
8.8 KiB
Plaintext
180 lines
8.8 KiB
Plaintext
---
|
||
title: 'Toolbars & globals'
|
||
sidebar:
|
||
order: 7
|
||
title: Toolbars & globals
|
||
---
|
||
|
||
<YouTubeCallout id="DuJ_gmSncLM" title="Create custom toolbar items using global types" />
|
||
|
||
Storybook ships with toolbar addons to control the [viewport](./viewport.mdx) and [background](./backgrounds.mdx) the story renders in. You can also create toolbar items which control special “globals”. You can then read the global values to create [decorators](../writing-stories/decorators.mdx) 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`). Instead, they are typically used 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.
|
||
|
||
## Global types and the toolbar annotation
|
||
|
||
Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-configure-globaltypes.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
<Callout variant="info" icon="💡">
|
||
|
||
As globals are *global* you can *only* set `globalTypes` and `initialGlobals` in [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering).
|
||
|
||
</Callout>
|
||
|
||
When you start your Storybook, your toolbar should have a new dropdown menu with the `light` and `dark` options.
|
||
|
||
## Create a decorator
|
||
|
||
We have a `global` implemented. Let's wire it up! We can consume our new `theme` global in a decorator using the `context.globals.theme` value.
|
||
|
||
<IfRenderer renderer="react">
|
||
For example, suppose you are using [`styled-components`](https://styled-components.com/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) config:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-use-global-type.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
</IfRenderer>
|
||
|
||
<IfRenderer renderer="vue">
|
||
For example, suppose you are using [`Vuetify`](https://vuetifyjs.com/en/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) config:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-use-global-type.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
</IfRenderer>
|
||
|
||
<IfRenderer renderer="angular">
|
||
For example, suppose you are using [`Angular Material`](https://material.angular.io/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) config:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-use-global-type.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
</IfRenderer>
|
||
|
||
<IfRenderer renderer={['ember', 'html', 'preact', 'qwik', 'svelte', 'solid', 'web-components' ]}>
|
||
Depending on your framework and theming library, you can extend your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) and provide a decorator to load the theme. For example:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-use-global-type.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
</IfRenderer>
|
||
|
||
## Setting globals on a story
|
||
|
||
<Callout variant="warning" icon="🆕">
|
||
The ability to set globals on a story or component is available in Storybook 8.3+. Some addons, like [backgrounds](./backgrounds.mdx) and [viewport](./viewport.mdx), have been updated to use the `globals` API when a [feature flag](../api/main-config/main-config-features.mdx) is enabled.
|
||
</Callout>
|
||
|
||
When a global value is changed with a toolbar menu in Storybook, that value continues to be used as you navigate between stories. But sometimes a story requires a specific value to render correctly, e.g., when testing against a particular environment.
|
||
|
||
To ensure that a story always uses a specific global value, regardless of what has been chosen in the toolbar, you can set the `globals` annotation on a story or component. This overrides the global value for those stories and disables the toolbar menu for that global when viewing the stories.
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="addon-backgrounds-define-globals.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
In the example above, Storybook will force all Button stories to use a gray background color, except the `OnDark` story, which will use the dark background. For all Button stories, the toolbar menu will be disabled for the `backgrounds` global, with a tooltip explaining that the global is set at the story level.
|
||
|
||
<Callout variant="info" icon="💡">
|
||
|
||
Configuring a story's `globals` annotation to override the project-level global settings is useful but should be used with moderation. Globals that are _not_ defined at the story level can be selected interactively in Storybook's UI, allowing users to explore every existing combination of values (e.g., global values, [`args`](../writing-stories/args.mdx)). Setting them at the story level will disable that control, preventing users from exploring the available options.
|
||
|
||
</Callout>
|
||
|
||
## Advanced usage
|
||
|
||
So far, we've created and used a global inside Storybook.
|
||
|
||
Now, let's take a look at a more complex example. 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|ts`](../configure/index.mdx#configure-story-rendering), add the following:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="storybook-preview-locales-globaltype.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
<Callout variant="info" icon="💡" style={{ marginBottom: '10px' }}>
|
||
|
||
The `icon` element used in the examples loads the icons from the `@storybook/components` package. See [here](../faq.mdx#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use.
|
||
|
||
</Callout>
|
||
|
||
<Callout variant="info" icon="💡">
|
||
|
||
To use toolbars, you must install the `@storybook/addon-toolbars` add-on, which is included by default in `@storybook/addon-essentials`.
|
||
|
||
</Callout>
|
||
|
||
Adding the configuration element `right` will display the text on the right side in the toolbar menu once you connect it to a decorator.
|
||
|
||
Here's a list of the available configuration options.
|
||
|
||
| 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 |
|
||
| **right** | String | A string that gets displayed on the 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 defining a global setting for all stories.
|
||
|
||
But we're aware that sometimes it's more beneficial to use toolbar options on a per-story basis.
|
||
|
||
Using the example above, you can modify any story to retrieve the **Locale** `global` from the story context:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="my-component-story-use-globaltype.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
## Consuming globals from within an addon
|
||
|
||
If you're working on a Storybook addon and need to retrieve globals, you can do so. The `@storybook/manager-api` package provides a hook for this scenario. You can use the [`useGlobals()`](../addons/addons-api.mdx#useglobals) hook to retrieve any globals you want.
|
||
|
||
Using the ThemeProvider example above, you could expand it to display which theme is active inside a panel as such:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="addon-consume-globaltype.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
## Updating globals from within an addon
|
||
|
||
If you're working on a Storybook addon that needs to update the global and refresh the UI, you can do so. As mentioned previously, the `@storybook/manager-api` package provides the necessary hook for this scenario. You can use the `updateGlobals` function to update any global values you need.
|
||
|
||
For example, if you were working on a [toolbar addon](../addons/addon-types.mdx#toolbars), and you want to refresh the UI and update the global once the user clicks on a button:
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="addon-consume-and-update-globaltype.md" />
|
||
|
||
{/* prettier-ignore-end */}
|