Disable addon panel for specific stories
To disable the addon panel for a particular story, pass the `paramKey` element when registering the panel. Then when adding a story, pass a disabled parameter to disable the addon panel for that story.
Storybook · Setup · all subjects
addons
108 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Addon classification: UI-based vs Presets
Each Storybook addon is classified into two general categories: UI-based or Presets. UI-based addons allow customization of Storybook's UI with panels, toolbars, and tabs. Preset addons are grouped collections of babel, webpack, and addons configurations to integrate Storybook with other technologies.
Actions addon example of using channels
The Actions addon is an example of an addon that uses channels. It captures user events and displays their data in a panel, demonstrating two-way communication between the manager and preview pane.
Use useChannel hook to access channel data in addons
Use the useChannel hook to access the channel data within your addon. This allows addon code to interact with events sent between the manager and preview pane.
Example addon configuration with parameters
The Pseudo States addon uses parameters to enable various pseudo-states. Here is an example of how to configure a story with addon parameters: ```js export const Hover = { render: () => <Button>Label</Button>, parameters: { pseudo: { hover: true } }, }; ``` This shows how to set addon-specific parameters on a story object.
Parameters are available in the browser for addon configuration
Parameters are available in the browser and are great for configuring addon behavior globally, at the component level, or at the story level. Users can provide global defaults and then override them at the story level.
Use useParameter hook to access parameter values in addons
Use the useParameter hook to access parameter values within your addon. This allows addon code running in the browser to read configuration parameters set at the global, component, or story level.
Channels enable two-way communication between manager and preview pane
Channels enable two-way communication between the manager and the preview pane, using a NodeJS EventEmitter compatible API. Addons can plug into specific channels and respond to these events.
Addons extend Storybook with features and integrations
Addons extend Storybook with features and integrations that are not built into the core. Most Storybook features are implemented as addons, including documentation, accessibility testing, and interactive controls.
UI-based addons focus on customizing Storybook user interface
UI-based addons focus on customizing Storybook's user interface to extend the development workflow. Examples include Controls, Docs, and Accessibility.
Storybook architecture: Manager and Preview
Storybook is divided into Manager and Preview. The Manager is the UI responsible for rendering search, navigation, toolbars, and addons. The Preview is an iframe where stories are rendered. Both elements run in separate iframes and use a communication channel to keep in sync.
Addon API enables configuration and customization
The addon API makes it easy to configure and customize Storybook in new ways. There are countless addons made by the community that unlock time-saving workflows.
storybook add command for addon installation
Storybook includes a `storybook add` command to automate the setup of addons. Running this command with your package manager updates the Storybook configuration to include the addon and installs any necessary dependencies. This command works for most community-led addons except for preset addons.
Manual addon installation via configuration
Storybook addons are added through the `addons` configuration array in `.storybook/main.js|ts`. To manually install an addon, run the npm install command for the addon package, then add it to the `addons` array in the main configuration file.
storybook add command limitation
When attempting to install multiple addons at once using the `storybook add` command, only the first addon that was specified will be installed. This is a known limitation that will be addressed in a future release.
Remove addon with CLI command
Addons can be removed from Storybook using the `storybook remove` command via the CLI, which automatically uninstalls the addon and removes it from the configuration file.
Manual addon removal process
To manually remove an addon from Storybook, uninstall it using your package manager and remove it from the configuration file (`.storybook/main.js|ts`).
Storybook has hundreds of reusable addons
Storybook has hundreds of reusable addons packaged as NPM modules available for extending Storybook functionality.
api.addNotification() for UI notifications
The api.addNotification(notification) method displays a notification in the Storybook UI. The notification object should contain `id` and `content`, and optionally `duration` and `icon`.
addons.setConfig() configuration table
The addons.setConfig(config) method allows you to override the default Storybook UI configuration. Configuration options are: `navSize` (Number in pixels, size of sidebar showing story list, example: 300), `bottomPanelHeight` (Number in pixels, addon panel size in bottom position, example: 200), `rightPanelWidth` (Number in pixels, addon panel size in right position, example: 200), `panelPosition` (String, where to show addon panel, 'bottom' or 'right'), `enableShortcuts` (Boolean, enable/disable shortcuts, true), `showToolbar` (Boolean, show/hide toolbar, true), `theme` (Object, Storybook theme, undefined), `selectedPanel` (String, id to select addon panel, example: storybook/actions/panel), `initialActive` (String, select default active tab on Mobile: 'sidebar', 'canvas', or 'addons'), `sidebar` (Object, sidebar options), and `toolbar` (Object, modify toolbar tools using addon id).
addons.setConfig() toolbar options
The toolbar namespace in addons.setConfig() accepts options using the format `[id]` (String, toggle visibility for specific toolbar item like 'title' or 'zoom', example: { hidden: false }).
useStorybookState hook
The useStorybookState hook allows access to Storybook's internal state. It is recommended to optimize addons using this hook by relying on React.memo, useMemo, or useCallback to prevent high volumes of re-render cycles.
useStorybookApi hook
The useStorybookApi hook is a convenient helper that provides full access to all Storybook API methods.
useChannel hook for event subscriptions
The useChannel hook allows setting subscriptions to events and getting the emitter to emit custom events to the channel. Messages can be listened to on both the iframe and the manager.
useAddonState hook for data persistence
The useAddonState hook is useful for addons that require data persistence, either due to Storybook's UI lifecycle or for more complex addons involving multiple types such as toolbars and panels.
useGlobals hook for globals management
The useGlobals hook is useful for addons that rely on Storybook Globals. It allows you to obtain and update global values. It is recommended to optimize addons using this hook by relying on React.memo, useMemo, or useCallback to prevent high volumes of re-render cycles.
useParameter hook for story parameters
The useParameter hook retrieves the current story's parameters. If the parameter's value is not defined, it automatically defaults to the second value defined.
useArgs hook for story args
The useArgs hook allows you to retrieve or update a story's args.
Core Addon API packages
Storybook's API is exposed via two packages. The `storybook/manager-api` package is used to interact with the Storybook manager UI or access the Storybook API. The `storybook/preview-api` package is used to control and configure the addon's behavior.
addons.add() method arguments
The addons.add() method registers the type of UI component associated with the addon and accepts the following arguments: `type` (the type of UI component to register), `title` (the title to feature in the Addon Panel), and `render` (the function that renders the addon's UI component). The render function is called with an `active` parameter that is true when the panel is focused on the UI.
addons.register() entry point
The addons.register() method serves as the entry point for all addons. It allows you to register an addon and access the Storybook API, returning a StorybookAPI instance.
addons.getChannel() for manager-preview communication
The addons.getChannel() method gets an instance to the channel to communicate with the manager and the preview. It can be found in both the addon register code and the addon's wrapper component used inside a story. It has a NodeJS EventEmitter compatible API for emitting and listening to events.
makeDecorator API for custom addon decorators
The makeDecorator API is used to create decorators in the style of official addons. It requires the following arguments: `name` (unique name to identify the custom addon decorator), `parameterName` (sets a unique parameter to be consumed by the addon), `skipIfNoParametersOrOptions` (optional, doesn't run the decorator if the user hasn't provided options via decorators or parameters), and `wrapper` (the decorator function that takes getStory, context, options, and parameters). If a story's parameters include `{ exampleParameter: { disable: true } }` where exampleParameter is the parameterName of the addon, the decorator will not be called.
api.selectStory() method
The selectStory API method allows you to select a single story. It accepts two parameters: the story kind name and an optional story name.
api.selectInCurrentKind() method
The selectInCurrentKind API method is similar to selectStory but only accepts the story name as the only parameter.
api.setQueryParams() for temporary addon storage
The setQueryParams() method allows you to set query string parameters that can be used as temporary storage for addons. To remove a query parameter, set it as `null` instead of removing it from the addon.
api.getQueryParam() method
The getQueryParam() method allows retrieval of a query parameter that was enabled via the setQueryParams() API method.
api.getUrlState() method
The getUrlState(overrideParams) method allows you to get the application URL state, including any overridden or custom parameter values.
api.getStoryHrefs() method and options
The getStoryHrefs(storyId, options?) method gets the manager and preview URLs for a story. URLs are relative to the current Storybook unless `base` is set or in case of previewHref with `refId` set. The storyId parameter is required. Optional options include: `base` (return an absolute href based on current origin or network address), `inheritArgs` (inherit args from current URL, defaults to true if storyId matches current story), `inheritGlobals` (inherit globals from current URL, defaults to true), `queryParams` (additional query params to append, merged with args and globals when inheriting), `refId` (ID of the ref for composed Storybooks), and `viewMode` (the view mode to use, defaults to 'story').
api.on() event handler method
The api.on(eventName, fn) method allows you to register a handler function called whenever the user navigates between stories.
api.openInEditor() for IDE integration
The api.openInEditor(payload) method opens a file in the configured code editor. The payload object requires `payload.file` (the file path to open), and optionally accepts `payload.line` (line number to jump to) and `payload.column` (column number to jump to). It returns a Promise that resolves with information about whether the operation was successful.
api.getCurrentStoryData() method
The api.getCurrentStoryData() method returns the current story's data, including its ID, kind, name, and parameters.
api.toggleFullscreen() method
The api.toggleFullscreen(toggled?) method toggles the fullscreen mode of the Storybook UI. Pass `true` to enable fullscreen, `false` to disable, or omit the parameter to toggle the current state.
api.togglePanel() method
The api.togglePanel(toggled?) method toggles the visibility of the addon panel. Pass `true` to show the panel, `false` to hide, or omit the parameter to toggle the current state.
Publishing addon to NPM with Auto
The Addon Kit comes pre-configured with the Auto package for release management. It generates a changelog and uploads the package to NPM and GitHub automatically. To use it, authenticate with npm adduser, generate an NPM access token with read and publish permissions, and create a GitHub personal access token with repo and workflow scopes.
Two main categories of addons
Storybook addons fall into two main categories: UI-based addons, which customize the interface and enable shortcuts for common tasks, and Presets, which are pre-configured settings that enable developers to quickly set up and customize their environment with a specific set of features.
UI-based addon types
UI-based addons can create three types of UI elements: toolbars (enabling users to draw outlines or perform actions through shortcuts or button clicks), panels (providing additional information or interaction in a dedicated panel area), and tabs (offering custom tab views with their own functionality).
React version requirement for addons with UI
Addons with a UI must use the same React version as Storybook. If your component library uses a different React version, you must use addons that are built and published as standalone packages.
Addon package.json exports field structure
An addon's package.json must include an exports field with: '.' entry containing types, node, require, and import paths; './manager' path to manager.mjs; './preview' path to preview.mjs; and './package.json' path. Additionally, main, module, and types fields should point to the corresponding dist files.
Addon package.json files field contents
The files field in addon package.json should include: dist/**/* (all transpiled code), README.md, and any root-level .js and .d.ts files.
Addon bundler metadata in package.json
The bundler property in addon package.json must declare exportEntries (array of entry file paths for exports), managerEntries (array of entry file paths for manager), and previewEntries (array of entry file paths for preview).
Addon integration catalog metadata in storybook property
The storybook property in addon package.json configures integration catalog metadata with: displayName (human-readable addon name), unsupportedFrameworks (array of framework identifiers the addon doesn't support), and icon (URL to addon icon).
Addon keywords for catalog discoverability
The keywords property in addon package.json maps to the catalog's tag system. The keyword 'storybook-addon' is essential as it ensures the addon is discoverable in the catalog when searching for addons. Additional keywords help with searchability and categorization.
Environment variables for addon release management
To publish an addon using Auto, create a .env file in the project root with: GH_TOKEN=<github_personal_access_token> and NPM_TOKEN=<npm_access_token>.
Auto create-labels command for GitHub release management
Run npx auto create-labels to create labels on GitHub that are used to categorize changes to the package during the release process.
Addon Kit CI automation with GitHub Actions
The Addon Kit comes pre-configured with a GitHub Actions workflow that automates release management. When a pull request is merged to the default branch, the workflow runs automatically, publishes a new release, increments the version number, and updates the changelog.
GitHub Actions secrets configuration for addon publishing
To enable CI automation for addon publishing, add NPM_TOKEN and GH_TOKEN as repository secrets in GitHub Actions settings. Go to repository Settings > Secrets and variables > Actions, then click 'New repository secret' to add each token.
Addon distribution as NPM packages
Storybook addons are distributed as NPM packages and must meet specific criteria to be published to NPM and crawled by the integration catalog: they must have a dist folder with transpiled code and a package.json file declaring module-related information and integration catalog metadata.
Community addons are written by the Storybook community
Community addons are addons written by the Storybook community. They can be found on the Storybook website (https://storybook.js.org/addons/), GitHub, and npm.
addon-docs is a core addon implementing documentation features
The addon-docs addon is a core addon that implements documentation features in Storybook.