Install and Configure Addons

Purpose and Scope

Addons are the extension mechanism for Storybook projects. They let a project add features such as accessibility checks, navigation helpers, documentation behavior, custom panels, or framework-specific setup without rewriting the core Storybook runtime. This page focuses on the user workflow for installing an addon, registering it in project configuration, and choosing the right configuration surface after it is installed. The important distinction is that installing a package only makes the addon code available; registering and configuring it tells Storybook how the addon should participate in the manager, preview, build, or story metadata layers.

The Configure Addons documentation frames the addon API as intentionally customizable and describes three major ways an addon can communicate with or configure a user's Storybook: presets, parameters, and channels. Presets are global and Node-accessible; parameters are browser-accessible configuration values that can be scoped globally, to a component, or to a single story; channels provide event-based communication between the manager UI and preview pane. Understanding those surfaces helps you decide whether an addon belongs in the main Storybook configuration, in story metadata, or inside addon UI logic. Sources: docs/addons/configure-addons.mdx

Relevant Source Files

• docs/addons/configure-addons.mdx — Defines the public addon configuration model used here, including presets, parameters, channels, and the hooks addon authors use to read parameter and channel data.

Installation and Registration Flow

Start by adding the addon package recommended by the addon's documentation. For many published addons, the preferred flow is the Storybook CLI command shown in the official docs: run the package manager command that invokes Storybook's add workflow, for example adding the accessibility addon by package name. That automated command installs dependencies and updates the Storybook configuration when the addon supports automatic setup. It is a good default for common community-led addons because it reduces the chance of forgetting the registration step or adding the addon to the wrong configuration field.

When automatic setup is not available, the manual flow has two parts. First, install the package as a development dependency because Storybook addons normally affect the local workshop, documentation build, or testing workflow rather than the production application bundle. Second, add the addon package name to the Storybook configuration file, usually the addons array in the project main configuration. Registration is the point where Storybook discovers the addon during startup, loads any preset behavior, and wires addon-provided manager or preview features into the running instance.

npx storybook@latest add @storybook/addon-a11y

// .storybook/main.ts
const config = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
  addons: ['@storybook/addon-a11y'],
};
 
export default config;

Treat the addon's README or documentation as authoritative for whether it should be installed through the CLI, added manually, configured with options, or used from story files. Preset-style addons often need only a single entry in the addons array because the preset can centralize setup on behalf of the user. Other addons expose story APIs, decorators, functions, or components that you import where needed. The safest workflow is to install, register, restart Storybook, then apply the addon's documented configuration at the narrowest scope that solves the problem.

Core Configuration Primitives

A preset is the broadest configuration primitive. The Configure Addons docs describe presets as a way to offload configuration from the user to the addon, with options that are global and accessible from NodeJS. That makes presets appropriate for build-time and server-side setup, such as preconfiguring Webpack loaders, Babel plugins, or library and framework integrations. If a UI library requires every story to be wrapped in a provider, a preset can describe that behavior so users get the correct story environment from a single line of configuration rather than hand-authoring the same wrapper in every project. Sources: docs/addons/configure-addons.mdx

Parameters are the primary story-facing configuration primitive. Unlike preset options, parameters are available in the browser and can be declared at multiple scopes: globally, for a component, or for an individual story. This makes them a strong fit for addon behavior that varies by story state. The Configure Addons docs use the pseudo-states addon as an example: a project can set defaults and then override a particular pseudo-state on a specific story. Addon code can then read those values with the documented parameter hook and react to the effective configuration for the currently rendered story. Sources: docs/addons/configure-addons.mdx

Channels are the communication primitive for runtime messages between Storybook's manager and preview pane. The documentation describes them as a two-way channel using an EventEmitter-compatible API. This matters because the manager and preview have different jobs: the manager owns the surrounding Storybook UI, while the preview renders stories. Addons such as Actions depend on this boundary by capturing user events in the preview and displaying event data in a manager panel. An addon that needs live coordination across that boundary should use channel events rather than forcing all behavior into static configuration. Sources: docs/addons/configure-addons.mdx

Applying Addon Options

After an addon is registered, decide where its options belong by asking when the option is needed and who needs to read it. If the option changes Storybook's build pipeline, framework integration, or global setup before the browser runtime starts, it belongs in preset or main configuration. If the option describes a story behavior that can vary between examples, use parameters. If the option is actually a live signal from a panel, toolbar, or preview interaction, model it as channel communication handled by the addon. This separation keeps configuration predictable and avoids overusing global settings for story-specific behavior.

A common pattern is to put stable defaults in preview-level parameters and override them in individual story exports. The story-level example from the Configure Addons docs shows a story object with a render function and a nested pseudo parameter that enables hover state. That pattern scales because the default remains close to Storybook setup, while exceptional examples document their own differences inside the story file. Readers browsing the story can see not only the rendered component state, but also the metadata that tells the addon how to enhance that state. Sources: docs/addons/configure-addons.mdx

export const Hover = {
  render: () => <Button>Label</Button>,
  parameters: { pseudo: { hover: true } },
};

For addon authors, this same division becomes a public contract. If your addon tells users to add an entry to the addons array, you are asking them to opt into package-level behavior. If you tell them to set parameters, you are giving them a declarative per-project, per-component, or per-story API. If you expose channel events, you are defining an event vocabulary shared by manager and preview code. The Configure Addons docs point authors toward the parameter and channel hooks for reading these values in addon code, which keeps the user-facing setup aligned with the implementation surface. Sources: docs/addons/configure-addons.mdx

Practical Examples and Edge Cases

For a straightforward addon, the checklist is short: install the package, add it to the addons array if the CLI did not do that automatically, restart Storybook, then verify that the UI, panel, toolbar, decorator, or story behavior appears. If the addon is a preset, do not assume it needs a story import; the whole point of a preset is to package configuration centrally. If the addon exposes story helpers, register the addon first, then import helpers only in the stories that need them. That keeps shared setup and story-specific APIs easy to reason about.

Be careful when moving options between scopes. A global parameter can be convenient, but it affects every story unless a lower scope overrides it. A component-level parameter is a better fit when all examples for one component share an addon behavior. A story-level parameter is best when the behavior demonstrates a specific state, such as enabling one pseudo-state, disabling a check, or changing a display mode for one example. This hierarchy is especially useful in large Storybooks where teams want consistent defaults but still need small exceptions without forking global configuration.

Another edge case is manager-preview communication. It can be tempting to store live UI choices as parameters, but parameters are better treated as declarative story metadata. If a panel button, toolbar control, or manager-side addon interface needs to notify the rendered story frame, channel events are the appropriate mechanism described by the docs. Conversely, if all you need is a static option that a story declares before render, channels are unnecessary complexity. Choosing the primitive that matches the timing of the data makes addons easier to debug and less likely to behave differently between development and static builds.

System-to-Code Mapping

The source documentation maps directly to the user workflow. The opening section establishes that addon authors have multiple ways to configure and communicate with a user's Storybook. The Preset section explains package-level configuration that runs in NodeJS and can automate integration work. The Parameters section explains browser-visible metadata, its global, component, and story scopes, and the hook used to read parameter values. The Channels section explains two-way communication between manager and preview and points to the hook used by addon code to access that communication layer. Sources: docs/addons/configure-addons.mdx

Next Steps

After installing an addon, read its documentation to identify whether it is a preset, a UI addon, a decorator-based integration, or a story helper package. Then register it once in Storybook configuration and keep story-level customization in parameters whenever possible. If you are authoring an addon rather than only consuming one, continue to the writing-addons and addon-types-and-presets pages so you can design a user-facing setup that matches Storybook's established primitives. For built-in addon behavior, the Essentials pages for Actions, Controls, Viewport, Backgrounds, and accessibility testing provide concrete examples of how these configuration ideas appear in day-to-day Storybook work.