OpenWikistorybookjs/storybook

Essentials Overview

Purpose and Scope

Storybook Essentials is the built-in set of capabilities that turns a running Storybook from a plain component renderer into a productive UI workshop. The official Essentials docs describe the bundle as zero-config and list Actions, Backgrounds, Controls, Highlight, Measure and outline, Toolbars and globals, and Viewport. This page explains how that feature set fits into the project’s addon model: Essentials features are presented to users as integrated tools, while the repository documentation snippets show the same underlying extension surfaces that custom addons and presets use.

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

The reader problem is usually not “which package exists?” but “where do these capabilities live in my Storybook configuration, and how do they relate to stories?” Essentials features sit between story authoring and addon authoring. They consume story metadata such as args and parameters, add manager UI such as panels, notifications, and toolbar controls, and influence the preview iframe where stories render. That makes Essentials a practical bridge: story authors use the controls, backgrounds, and viewport UI every day, while maintainers can still reason about them as configurable addons.

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

Relevant Source Files

  • docs/_snippets/args-usage-with-addons.md — shows a manager-side addon using useArgs from storybook/manager-api to read, update, and reset story args, which is the same story-input concept used heavily by Controls and action-style workflows.
  • docs/_snippets/main-config-addons.md — shows the canonical .storybook/main.js and .storybook/main.ts addons array, including a string addon entry and an object addon entry with name and options.
  • docs/_snippets/nextjs-remove-addons.md — shows a framework migration cleanup where storybook-addon-next and storybook-addon-next-router can be removed from the addons array for Next.js-oriented Storybook configurations.
  • docs/_snippets/storybook-addon-load-external-addons-preset.md — shows a preset exporting managerEntries and previewAnnotations so one package can load another addon’s manager and preview code.
  • docs/_snippets/storybook-addons-api-addnotification.md — shows a manager addon registered through addons.register and using api.addNotification with id, content, optional icon, and duration.
  • docs/_snippets/storybook-addons-api-disablequeryparams.md — shows an addon clearing a query parameter by calling api.setQueryParams with a parameter value of null.

Core Primitives

Essentials relies on a few Storybook primitives that are useful to define before exploring each feature. A story is a named example of a component state. Args are serializable inputs for that story, and manager-side code can use useArgs to read the current args, update one or more values, reset named args, or reset all args. The snippet uses const [args, updateArgs, resetArgs] = useArgs();, followed by updateArgs({ key: 'value' }) and reset calls. That shape is central to interactive editing because the UI can change story inputs without rewriting the story file.

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

The second primitive is configuration in .storybook/main.js or .storybook/main.ts. Storybook projects declare a framework, glob patterns for stories, and an addons array. The addon examples show two common forms: a package name string such as @storybook/addon-docs, and an object with name plus options, as used for @storybook/addon-styling-webpack. Essentials is documented as zero-config, but this configuration surface still matters because it is where teams add, remove, or customize addon packages around the built-in experience.

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

The third primitive is the manager and preview split. The manager is Storybook’s application shell: sidebar, toolbar, panels, notifications, and URL state. The preview is the iframe environment where stories render. Presets can contribute to both sides by returning manager entries and preview annotations. The external addon preset snippet appends my-other-addon/manager through managerEntries and appends my-other-addon/preview through previewAnnotations, which demonstrates how a packaged integration can bundle UI behavior and rendering behavior together.

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

Essentials Feature Set

Actions help developers see when event handlers or callbacks are invoked and what arguments they receive. In everyday component development, that means a button story can report clicks without wiring a full application backend. The official Actions page emphasizes Storybook-generated mock functions and spy-friendly patterns for interaction tests. The source-backed connection is the args model: callbacks are commonly passed as args, and manager code can inspect or update args through useArgs. Actions therefore sit at the intersection of story inputs, panel output, and testable event behavior.

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

Controls expose args as editable UI so developers can explore component states without writing a separate story for every small variation. The useArgs snippet is especially relevant here because it shows the contract behind live editing: current args are available to the manager, updateArgs can patch specific values, and resetArgs can restore one key or the entire story. This keeps the story source as the durable model while allowing the running Storybook to become an interactive workbench for props, slots, data values, and handler placeholders.

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

Backgrounds and Viewport change the rendering context around a story rather than the component inputs themselves. The official Backgrounds docs describe default light and dark backgrounds plus project-defined background options in preview configuration. Viewport similarly helps authors inspect responsive states. These features matter because isolated component development is only useful when the surrounding context is representative enough to catch visual and layout issues. They are also configured through Storybook’s metadata and UI surfaces rather than through application routes or production screens.

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

Toolbars and globals provide cross-story context switches such as theme, locale, or mode. Highlight, Measure, and outline are inspection tools that help developers understand the rendered DOM and visual geometry without leaving Storybook. Together with Actions, Backgrounds, Controls, and Viewport, they create a tight feedback loop: choose a story, adjust inputs, switch global context, inspect layout, and verify events. The important architectural point is that these capabilities are not independent apps; they are addon-driven extensions of the same Storybook manager and preview runtime.

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

Configuration and Extension Model

For most projects, Essentials should be treated as part of the default Storybook experience rather than a checklist of packages to manually assemble. When a project does need explicit addon configuration, the addons array in .storybook/main.js or .storybook/main.ts is the key location. The documented snippet shows Storybook configuration with a framework placeholder, story globs for MDX and CSF files, and addon registration. It also shows that addons may accept structured options, which is how advanced project-specific behavior is usually expressed without changing Storybook internals.

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

A compact example of the supported shape is:

const config = {
  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: [] } },
  ],
};

The same source file also documents CSF Next style configuration for supported renderers using defineMain from @storybook/your-framework/node. That matters for Essentials because the configuration shape remains recognizable even as Storybook evolves its authoring APIs. A team can move from object default exports to defineMain while preserving the core idea that framework selection, story discovery, and addon registration are declared together in the main configuration file.

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

Framework integrations can also reduce the need for old compatibility addons. The Next.js cleanup snippet shows storybook-addon-next and storybook-addon-next-router commented as removable entries in the addons array when using nextjs or nextjs-vite framework packages. This is an important maintenance signal: do not treat every historical addon as an Essentials requirement. Prefer the current framework package and built-in Storybook capabilities first, then add external addons only when they provide behavior that the framework and Essentials set do not cover.

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

Addon API Touchpoints

Essentials users rarely need to write manager addons, but understanding the API helps explain how the UI is extended. The notification snippet registers an addon with addons.register('my-organisation/my-addon', (api) => { ... }) and then calls api.addNotification. Notifications include an id, content with headline and subHeadline, optional icon, and duration. This demonstrates that addon code can participate in the Storybook manager experience, not only in the rendered story. Essentials panels and tools are built around the same idea of augmenting the workspace around stories.

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

URL and query state are another manager concern. The query-parameter snippet shows an addon clearing a value by calling api.setQueryParams({ exampleParameter: null }). That small example is useful because Storybook’s UI state often needs to be shareable, resettable, or encoded in the browser location. Essentials features such as selected globals, tool state, or panel behavior need to coexist with story navigation. Addons that manipulate query params should be deliberate so they do not create confusing or persistent UI state for story authors.

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

Presets are the packaging mechanism for reusable addon behavior. The preset snippet exports managerEntries and previewAnnotations, each returning a new array that appends resolved entry points from another addon. This means an integration can compose an external addon without asking every consuming project to list each underlying manager and preview file manually. In practice, this is how teams should think about larger Storybook extensions: if a capability needs both UI affordances and preview setup, package it as a preset-like integration rather than scattering manual imports across projects.

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

Execution Flow

A typical Essentials-enabled workflow begins when Storybook loads .storybook/main.*, resolves the selected framework, discovers stories from configured globs, and loads addons. The source snippet’s stories patterns include MDX documentation files and JavaScript or TypeScript story files, which matches the product model where examples and documentation live together. Once the manager and preview start, the manager exposes navigation, panels, toolbar controls, notifications, and URL state, while the preview renders the currently selected story with its args and contextual annotations.

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

When a developer edits a Control, the change conceptually flows through the args channel: the manager has current args, applies updateArgs, and the preview re-renders with the new input values. When a developer triggers a callback, Actions can display the observed call data. When the same developer changes background, viewport, or global toolbar state, Storybook changes the context in which the same story renders. These loops are intentionally fast and local, which is why Essentials is central to Storybook’s role as a frontend workshop rather than only a static component catalog.

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

Practical Guidance

Start with the default Essentials experience and add configuration only when a project requirement is clear. If a feature is driven by story inputs, look first at args and arg types. If it changes all stories or a broad context, look at globals, toolbar configuration, or preview-level parameters. If it adds UI to Storybook itself, expect manager APIs such as addons.register, notifications, query parameters, or panel integration. If it changes how stories render, expect preview annotations or framework-specific configuration.

Sources: docs/_snippets/args-usage-with-addons.md, docs/_snippets/storybook-addons-api-addnotification.md, docs/_snippets/storybook-addons-api-disablequeryparams.md

For existing projects, periodically review the addons array. Keep explicit entries that provide real project value, but remove obsolete framework helpers when the modern framework integration covers them. The Next.js snippet is the clearest example: old Next-specific addons can be removed in configurations that use current nextjs or nextjs-vite framework packages. After that cleanup, use the feature-specific pages for deeper configuration: Controls for args editing, Actions for callback logging, Backgrounds and Viewport for rendering context, and Toolbars and globals for cross-story state.

Sources: docs/_snippets/nextjs-remove-addons.md, docs/_snippets/main-config-addons.md

Ask a question...