Addons Overview

Purpose and Scope

Addons are Storybook extensions that add features, integrations, and workflow-specific behavior around the core component workshop. In practical projects, they are how teams turn Storybook from a component browser into a documentation system, accessibility checker, design review surface, styling environment, or project-specific tool panel. The official documentation frames many familiar Storybook capabilities as addons, including documentation, accessibility testing, controls, actions, backgrounds, viewport, and other Essentials features. This page gives an overview of how addons are declared, how they interact with stories and the user interface, and how repository snippets demonstrate the public configuration and API patterns a Storybook user or addon author will encounter.

Sources: docs/_snippets/main-config-addons.md, docs/_snippets/args-usage-with-addons.md

Storybook has two major runtime surfaces that matter for addons: the manager and the preview. The manager is the application shell that contains navigation, toolbars, panels, notifications, and Storybook-level state. The preview is where stories render, receive args, run decorators and loaders, and exercise framework-specific rendering. A single addon may contribute only to the manager, only to the preview, or to both. For example, a documentation addon can alter generated docs and add UI, while a styling preset can affect preview bundling so components render with the same CSS pipeline as the application.

The key reader task is deciding whether an addon is something to install and configure, something to remove because a framework now includes equivalent behavior, or something to author. A project maintainer mostly edits the addons array in Storybook main configuration. An addon author thinks in terms of manager entries, preview annotations, parameters, args, and manager API calls. The snippets in this page show each of those layers: main configuration for consumers, preset composition for package authors, and manager API methods for UI integrations such as notifications or query parameter cleanup.

Relevant Source Files

• docs/_snippets/main-config-addons.md — Shows the canonical main configuration shape where addons are listed as package names or objects with name and options, including JavaScript, TypeScript, and defineMain variants.
• docs/_snippets/args-usage-with-addons.md — Demonstrates a manager-side addon reading and updating the current story args through the Storybook manager API.
• docs/_snippets/nextjs-remove-addons.md — Shows a migration-oriented configuration example where older Next.js community addons can be removed when using the current Next.js framework integration.
• docs/_snippets/storybook-addon-load-external-addons-preset.md — Demonstrates a preset that loads another addon's manager and preview entries, which is useful when composing addon packages.
• docs/_snippets/storybook-addons-api-addnotification.md — Shows an addon registering with the manager API and adding notifications, including notification content, icon, identifier, and duration.
• docs/_snippets/storybook-addons-api-disablequeryparams.md — Shows a manager addon clearing a query parameter by setting its value to null through the API.

Core Addon Model

A consuming Storybook project enables addons from its main configuration. The central pattern is an addons array alongside the framework and stories fields. Entries can be simple package names when defaults are enough, or structured objects when the addon exposes configuration options. The main configuration snippets show Storybook docs enabled with a package-name entry and a styling addon configured as an object with a name and options. That distinction is important: addon installation is not only about npm packages; it is also about passing the addon the project-specific context it needs to integrate with builders, loaders, or runtime features.

Sources: docs/_snippets/main-config-addons.md

The structured addon option example is especially useful because it demonstrates that an addon can participate in the build pipeline rather than just the visible UI. The styling addon receives rules for CSS handling and a PostCSS implementation resolved from Node. In a Webpack-backed Storybook, that kind of option lets the addon install loader behavior without forcing the user to hand-edit lower-level builder configuration. From the user's perspective, the addon remains a single entry in main configuration. From the addon's perspective, those options are a contract that can be consumed by a preset or configuration hook.

Storybook also distinguishes framework integrations from generic addons. The Next.js removal snippet documents that storybook-addon-next and storybook-addon-next-router can be removed when the project uses the current Next.js or Next.js Vite framework package. That is a useful edge case when auditing an addons list: not every historical addon should remain installed forever. Some ecosystem functionality migrates into a first-party framework package, where it can be maintained with tighter knowledge of routing, images, styles, and bundling. Removing redundant addons reduces configuration noise and avoids conflicting behavior.

Sources: docs/_snippets/nextjs-remove-addons.md

System-to-Code Mapping

This mapping shows that addons are not one uniform type of package. Some addons are end-user features, such as Docs or styling support. Some are presets that gather several behaviors behind a simpler configuration surface. Some are manager tools that add panels, toolbar controls, notifications, or state synchronization. Others are preview behaviors that annotate story rendering, install decorators, or change how args and parameters are interpreted. The same installed package may include several of these pieces, which is why Storybook's addon documentation treats configuration, authoring, presets, and the Addon API as related but distinct topics.

Configuration Flow for Consumers

A typical consumer workflow starts by installing the addon package, then adding it to the addons array in Storybook main configuration. If the addon has no required options, a string entry keeps the configuration short. If it needs project details, use an object entry. The main configuration snippet shows both forms in one file, which mirrors how real projects accumulate addons: a general documentation addon may sit next to a styling addon that needs loader rules. The framework and stories fields remain separate, so Storybook can still discover stories and choose the correct renderer independently of addon-specific setup.

Sources: docs/_snippets/main-config-addons.md

When reviewing an existing configuration, read addon entries as ordered project capabilities. Start with first-party or essential features, then look for styling, testing, routing, design, or data integrations. For each object entry, treat the options as part of the project contract. Changing a loader rule, implementation package, or preset option can affect how every story renders. For each legacy or community package, check whether the framework package now supplies the same behavior. The Next.js snippet is a concrete example of that maintenance practice: remove obsolete Next.js addons instead of layering them on top of the current framework integration.

import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-docs',
    {
      name: '@storybook/addon-styling-webpack',
      options: {
        rules: []
      }
    }
  ]
};
 
export default config;

Authoring and Preset Patterns

Addon authors often package configuration so users do not have to understand every manager and preview entry. The preset snippet demonstrates two exported functions: managerEntries and previewAnnotations. The manager function appends a manager module for another addon, while the preview function appends a preview module. This pattern lets an addon depend on or re-export another addon's behavior without asking users to add both entries manually. It also reflects the manager-preview split: one module affects the Storybook UI, and the other affects story rendering or preview setup.

Sources: docs/_snippets/storybook-addon-load-external-addons-preset.md

Presets are best understood as configuration adapters. They translate a simple addon entry into one or more lower-level Storybook contributions. A preset can preconfigure build tooling, add annotations, include manager code, or coordinate behavior across packages. This is why the official docs recommend presets for cases where addon authors want to offload burden from users. If an integration requires Babel, Webpack, provider wrapping, or companion UI, the preset becomes the place to hide those mechanics while still exposing a concise options object in main configuration.

The snippets also show manager API usage for active story state. An addon can import useArgs from the manager API, retrieve the current args, update selected keys, reset selected args, or reset all args. That is the basis for controls-like behavior and custom panels that edit story inputs. Args are not just a story authoring convenience; they are also the communication layer between the rendered preview and manager UI. If a custom addon edits args, it should do so deliberately because the active story may re-render, controls may update, and the resulting state can affect testing or documentation examples.

Sources: docs/_snippets/args-usage-with-addons.md

Manager API Capabilities

Manager-side addons register under an identifier and receive an API object. The notification snippet shows this flow with addons.register and api.addNotification. A notification has an id, content, and duration, and it can include an icon. That makes it suitable for short-lived feedback such as a completed operation, successful save, or integration status. Because the id is explicit, addon authors can reason about whether a message is unique, replaceable, or tied to a specific action. The manager API is therefore not just for adding panels; it can also integrate with Storybook's global application feedback mechanisms.

Sources: docs/_snippets/storybook-addons-api-addnotification.md

Another manager API pattern is owning URL state. The query parameter snippet registers an addon and calls setQueryParams with a parameter value of null. In this API shape, null means the parameter should be disabled or removed rather than set to a string value. This is useful when an addon uses query parameters for temporary state and later needs to clean them up. It also hints at a broader design principle: addons should be polite participants in the shared manager environment. If an addon writes state into the URL, toolbar, globals, or args, it should also provide predictable cleanup behavior.

Sources: docs/_snippets/storybook-addons-api-disablequeryparams.md

Built-in and Ecosystem Categories

Storybook's built-in Essentials are the most visible addon category. They cover everyday development tasks such as editing args through controls, logging events through actions, choosing backgrounds, simulating viewports, measuring and outlining layout, highlighting elements, and changing globals through toolbars. Documentation features such as addon-docs are also commonly installed through the addon system. These packages are maintained as part of the Storybook ecosystem and demonstrate the same extension model available to community addons: they add manager UI, preview behavior, generated documentation, or configuration hooks around the same story source files.

Ecosystem addons tend to cluster around project-specific concerns. Styling addons adapt CSS pipelines. Framework or routing addons historically filled gaps before framework packages gained native support. Design integrations attach external design references. Testing and accessibility addons add checks, panels, or reports. Preset-style addons bundle several pieces for a library or platform. When evaluating one, start by identifying which surface it extends: manager UI, preview rendering, build configuration, documentation generation, or Storybook state. Then decide whether the addon should be installed directly, wrapped by a preset, configured with options, or removed because the framework integration supersedes it.

Practical Next Steps

For a project maintainer, the next step is to open Storybook main configuration and categorize every addon entry. Keep simple string entries when defaults are enough, keep object entries when the options are still required, and remove legacy framework-specific packages when current framework support makes them redundant. For an addon author, start by deciding whether the feature belongs in manager code, preview annotations, or a preset. Then use the manager API only for state and UI that belongs in the manager, and use preview annotations for behavior that affects rendered stories.

After this overview, read Install and Configure Addons for consumer setup details, Addon Types and Presets for package structure, Writing Addons for authoring workflow, and Addons API and Integration Catalog for manager and preview API reference. If your goal is to understand built-in user features rather than author extensions, the Essentials pages for Controls, Actions, Backgrounds, Viewport, Toolbars and Globals, and Measure, Outline, and Highlight are the most direct continuation.