mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 15:31:16 +08:00
173 lines
8.5 KiB
Plaintext
173 lines
8.5 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 your toolbar items that control special “globals,” which you can then read 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`), 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.
|
||
|
||
## 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:
|
||
|
||
<CodeSnippets path="storybook-preview-configure-globaltypes.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
<Callout variant="info" icon="💡">
|
||
|
||
As globals are *global* you can *only* set `globalTypes` 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
|
||
|
||
By default, custom toolbars and other globals defined with the `globalTypes` annotation, similar to the one created to set up our custom theme, are consistently applied to every story available. However, if you need to, you can override them at the component or story level to use a custom value for a specific story or subset of stories. This will allow you to test specific scenarios (e.g., custom appearance, behavior) where a particular value should be used. To do this, add a `globals` annotation in your story to enable the selected option.
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="component-story-theme-override-globals.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
When Storybook loads the stories, it applies the selected theme to every story except the `Dark` story, which automatically applies the `dark` theme. It also turns off the toolbar dropdown with the theme options, preventing them from being changed and notifying that this story requires a specific value to be used.
|
||
|
||
<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)). Enabling them at the story level will turn them off, 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" usesCsf3 csf2Path="essentials/toolbars-and-globals#snippet-my-component-story-use-globaltype" />
|
||
|
||
{/* 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 */}
|