Toolbars & globals
Watch a video tutorial on the Storybook channel
Storybook ships with toolbar addons to control the viewport and background the story renders in. You can also create your own toolbar items which control special “globals” which you can then read to create decorators to control story rendering.
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.
Global types and the toolbar annotation
Storybook has a simple, declarative syntax for configuring toolbar menus. In your
.storybook/preview.js, you can add your own toolbars by creating
globalTypes with a
💡 As globals are global you can only set
When you start your Storybook, you should see a new dropdown with the
dark options in your toolbar.
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
For example, suppose you are using
styled-components. You can add a theme provider decorator to your
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.
.storybook/preview.js, add the following:
icon element used in the examples loads the icons from the
@storybook/components package. See here for the list of available icons that you can use.
@storybook/addon-toolbarsaddon is required to use toolbars. The toolbars addon is included by default in
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.
Here's a list of the configuration options available.
|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 on the left side of the menu||No|
|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 define 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:
💡 In Storybook 6.0, if you set the global option
passArgsFirst: false for backward compatibility, the story context is passed as the first argument:
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() 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:
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/manager-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 both
@storybook/core-events packages together to trigger the refresh.
For example, if you were working on a toolbar addon, and you want to refresh the UI and update the global once the user clicks on a button: