Introducing a new way to review your PRs.

Read the announcement

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

View on GitHub

20 documents · Updated Nov 20, 2026

docs / manager-ui

Manager UI

The Manager UI is Storybook’s control surface for browsing stories, selecting a view, changing layout and global values, and hosting addon features. It builds a shell around preview frames and uses shared state plus a browser channel to keep the shell and preview in sync. See also Storybook runtime, Preview runtime, CLI and server lifecycle, and Story format and analysis.

Application composition

The manager runtime builds a provider tree before it renders the main shell. The tree supplies browser location, manager state, API access, theme data, layout context, and error isolation to the sidebar, preview, panel, settings pages, and addon pages.

flowchart TD
  Runtime[Manager runtime] --> Channel[Browser channel]
  Runtime --> Root[Manager root]
  Root --> Location[Location provider]
  Location --> Provider[Manager provider]
  Provider --> Theme[Theme and layout context]
  Theme --> App[Manager application]
  App --> Sidebar[Story sidebar]
  App --> Preview[Preview area]
  App --> Panel[Addon panel]
  App --> Pages[Settings and addon pages]
  Provider --> Addons[Registered addons]
  Channel <--> PreviewFrame[Preview iframe]

The browser channel is ready before manager entries and addons render. This lets addons register listeners before the preview sends its first events. A closed connection becomes a visible manager notification instead of leaving the UI silently stale. References: code/…/runtime.tsx• L22-79, code/…/index.tsx• L32-93

The manager runtime also provides a shared module set to manager code and addons. This keeps React, Storybook APIs, themes, channels, router values, and core types aligned across the manager bundle and the addon bundle. The test package is not part of this manager runtime surface. References: code/…/runtime.ts• L23-50, code/…/globals.ts• L1-26

Manager shell

The shell combines the story sidebar, preview area, addon panel, settings or addon pages, notifications, and persistent overlays. Desktop mode uses resizable regions. Mobile mode uses a navigation drawer instead of the desktop sidebar, and choosing a story closes that drawer. References: code/…/App.tsx• L20-97, code/…/Layout.tsx• L21-53, code/…/LayoutProvider.tsx• L7-47, code/…/Menu.tsx• L200-257, code/…/Tree.tsx• L361-377

The layout keeps the last visible sizes for the sidebar and panel. Hiding and restoring a region therefore returns it to the user’s previous size. Fullscreen hides both regions without losing those sizes. The mobile drawer is temporary and does not restore as open from saved state. References: code/…/layout.ts• L200-253, code/…/layout.ts• L269-421, code/…/layout.test.ts• L74-99, code/…/layout.test.ts• L407-437

Route model

The URL is the source of truth for the selected story, docs view, composed ref, settings page, view mode, and query filters. Story and docs routes show the preview canvas. Other view modes show a registered page instead. Review routes can make navigation unavailable even when the stored layout says that navigation is shown. References: code/…/index.tsx• L40-88, code/…/layout.ts• L40-49, code/…/layout.ts• L579-585

Manager-owned query values control layout and navigation. Other query values remain custom preview state and pass through to the preview, so addon or story-specific URL state survives manager navigation. References: code/…/root.tsx• L121-124, code/…/root.tsx• L226-245, code/…/layout.ts• L622-656

State stores

The Manager API combines state modules into one state and one API. The modules own related behavior for layout, stories, composed refs, globals, notifications, shortcuts, settings, versions, URLs, and release notes. UI components read this shared state through manager context instead of passing it through the whole shell.

Manager state

The manager store holds the current story index, filtered navigation data, selected view, refs, layout, settings, and URL state. Session storage keeps temporary layout choices such as region sizes. Permanent storage keeps longer-lived choices such as panel position and shortcut bindings. URL state keeps story filters shareable. References: code/…/root.tsx• L80-119, code/…/store.ts• L57-183, code/…/layout.ts• L659-673

The store gives manager API reads an up-to-date view while React still has state updates waiting to commit. It resolves functional updates against that view and keeps pending patches in order, even when React commits a later update first. Empty patches do not trigger a React update or storage write. This prevents addon and manager actions from reading or restoring stale fields during rapid changes. References: code/…/store.ts• L62-183, code/…/store.test.js• L175-285

The story state resolves the selected story or docs entry and updates when the preview reports prepared data. Composed refs keep separate indexes and preview readiness for external Storybooks. Tag and status filters rebuild the visible indexes and remain part of shareable URL state. References: code/…/stories.ts• L123-135, code/…/stories.ts• L450-525, code/…/stories.ts• L953-1125, code/…/refs.ts• L98-117

Version information

The version state gives the manager its current and available Storybook versions. It also builds links to the matching documentation and decides when an upgrade notice is useful. The running manager version is supplied by code/…/version.ts and is currently 11.0.0-beta.3. The state starts with that version, adds version data supplied through the global version check, and keeps a dismissed notification so the UI can avoid repeating a notice. References: code/…/version.ts• L1, code/…/versions.ts• L19-31, code/…/versions.ts• L80-91

Documentation links can target a subpath or asset and can include a version, renderer, tracking reference, and URL fragment. The link builder uses the active version for versioned documentation, falls back to the latest version for placeholder builds, and normalizes Vue renderer names for the docs site. References: code/…/versions.ts• L109-152

Upgrade state treats a newer major or minor release as an available update while ignoring patch-only changes and prerelease noise. For a prerelease manager, the next release can be more useful than the stable latest release. The sidebar and upgrade surface use this state to link users to documentation and upgrade guidance. References: code/…/versions.ts• L93-107, code/…/versions.ts• L154-181, code/…/Menu.tsx• L176-191, code/…/UpgradeBlock.tsx• L62-70

Shared addon stores

Addon state crosses the manager and preview through named shared stores. Manager hooks expose stores for status, test providers, checklists, and other shared values. A change remains in the manager store and travels over the channel so the other side can apply the same value. References: code/…/root.tsx• L403-489, code/…/manager-stores.ts• L1-10, code/…/index.ts• L3-24

Story navigation

The sidebar turns local and composed story indexes into a browsable tree. Each ref can show loading, authentication, error, empty, or ready state. In the ready state, the tree groups stories and docs entries and marks the current selection. References: code/…/Explorer.tsx• L19-61, code/…/Refs.tsx• L84-179

Story tree

The tree supports branch expansion, story selection, search-driven navigation, context actions, status marks, and keyboard use. Branch activation changes only that branch’s expansion, while leaf activation selects its story or docs page. Focus movement does not activate a branch. The tree keeps deep selections visible while scrolling and closes the mobile navigation drawer after story selection. References: code/…/Tree.tsx• L361-411, code/…/Tree.tsx• L629-730, code/…/TreeNode.tsx• L485-638

The explorer places local stories and composed references in one shared scroll area, so all reference blocks remain reachable in one column. Trees use that area for sticky rows and row positioning while still limiting rendered rows for large indexes. Search results use a separate scroll area because they replace the explorer view. References: code/…/Explorer.tsx• L35-59, code/…/Sidebar.tsx• L182-230, code/…/SidebarScrollArea.tsx• L15-22, code/…/SidebarScrollArea.tsx• L28-40, code/…/Tree.tsx• L440-582

The sidebar reserves space below the explorer for its floating status and test widget, so the last rows remain reachable. The widget can filter rows with warnings or errors, and it exposes test-provider actions in development mode. Its measured height becomes part of the scroll area’s bottom space rather than hiding story rows. References: code/…/Sidebar.tsx• L169-232, code/…/SidebarBottom.tsx• L109-169, code/…/SidebarScrollArea.tsx• L28-40

The shared sidebar scroll area also manages a quiet scrollbar. The thumb appears while the pointer is over the area or while a row inside it has focus, then fades after a short delay. This keeps scrolling available without adding a strong visual boundary to the navigation. References: code/…/SidebarScrollArea.tsx• L41-66, code/…/SidebarScrollArea.tsx• L93-177

The tree can preload a likely next story while the user hovers a branch or search result. Search results also show recently opened entries, status marks, and a control to clear that history. References: code/…/Tree.tsx• L440-582, code/…/SearchResults.tsx• L181-220, code/…/SearchResults.tsx• L291-341

Addon integration

Addons extend the manager by registering typed UI elements. The manager groups these elements as panels, tools, extra tools, wrappers, pages, and test providers, then places them in the matching shell region. Built-in elements load first, while addon elements provide extension points around them. References: code/…/addons.ts• L33-142, code/…/root.tsx• L130-219

The preview area combines addon tools and wrappers with the selected story. A panel can be hidden by story parameters or by its own disabled rule. Registered pages use the manager route instead of the preview canvas. Panel availability is evaluated before a story is prepared and again when preparation changes the story data, so panels can respond to the active story without hiding unrelated panels. References: code/…/index.tsx• L64-85, code/…/Preview.tsx• L22-49, code/…/Panel.tsx• L47-84, code/…/Panel.test.tsx• L84-143

Addon-owned state uses the shared manager store. An addon can read its current state, update it with a value or merger, and choose the same persistence modes as other manager state. Equal non-persistent values do not cause a manager write, but equal values with persistence still reach storage. The update changes only the addon state branch, which keeps unrelated manager fields from being held at an older pending value. The selected panel is session-persistent and falls back to the first registered panel when the saved choice is no longer available. References: code/…/addons.ts• L83-161, code/…/store.ts• L62-69, code/…/addons.test.js• L204-273

Test provider integration

Test providers add test-related state and UI to the manager. The sidebar uses their presence to offer row actions, and the testing widget renders each provider’s status area. A provider without a render surface is skipped so it cannot break the rest of the manager. References: code/…/Tree.tsx• L135-138, code/…/TreeNode.tsx• L539-546, code/…/TestingWidget.tsx• L384-397

Toolbar and preview controls

The toolbar is the manager-side view of global controls. It reads global type definitions, creates controls for globals that declare a toolbar, and writes the selected value through the globals API. The preview consumes the resulting globals when it renders the current story. References: code/…/ToolbarManager.tsx• L10-28, code/…/ToolbarMenuSelect.tsx• L28-145, code/…/preview.ts• L1-2

Story-level global values take priority over toolbar values, so the matching toolbar control is disabled while the story owns that value. Toolbar actions can also register manager shortcuts. References: code/…/ToolbarManager.tsx• L10-28, code/…/zoom.tsx• L239-264

The preview toolbar also exposes manager controls for the current view. The addon-panel control appears when the panel is hidden and navigation is hidden when the sidebar is unavailable. Both controls restore their target region and move focus to it. The remount control is available for story views and asks the preview to reload the current story. References: code/…/addons.tsx• L24-65, code/…/menu.tsx• L21-63, code/…/remount.tsx• L34-71

Preview controls

The preview area displays the selected story in a local or composed-ref frame. It can show a loading state while the local preview builds or a composed ref becomes ready. Story view supports scaling, while docs view keeps the normal scale. References: code/…/Preview.tsx• L37-115, code/…/Preview.tsx• L155-188

Viewport controls let a user choose a device-like size, edit width and height, rotate the view, restore the last named viewport, and resize the frame by dragging. Zoom controls provide preset and numeric scale changes, keyboard controls, and a reset action. These values affect the manager’s frame presentation rather than the story’s own state. References: code/…/Viewport.tsx• L200-395, code/…/zoom.tsx• L60-199

Settings and shortcuts

Settings is a full-page route under /settings/. Its child routes provide About, keyboard shortcuts, and conditional Guide and What's new views. The settings menu reuses the manager menu and relevant tools so users can leave settings without losing the main controls. References: code/…/index.tsx• L40-183, code/…/Menu.tsx• L43-91

The manager menu also exposes sidebar, toolbar, addon-panel, story-navigation, documentation, and registered addon actions. Addon menu items resolve their action when clicked, so a later addon registration is used without rebuilding the menu. References: code/…/Menu.tsx• L89-221, code/…/Menu.test.tsx• L15-52

The Guide presents grouped checklist items with progress, locked steps, actions, skip and reset controls, and deep links to an item. The menu can show the guide’s progress when onboarding is enabled. References: code/…/Checklist.tsx• L254-301, code/…/Checklist.tsx• L331-467, code/…/Menu.tsx• L56-72

Shortcut behavior

The shortcut store holds built-in and addon bindings. Users can change bindings in settings, restore one binding or all defaults, and keep valid choices across sessions. Addon bindings exist only while the addon registers them, so an old saved binding cannot claim a key after the addon is gone. Re-registration keeps a user-customized binding while accepting a changed addon default. References: code/…/shortcuts.ts• L223-288, code/…/shortcuts.ts• L547-554, code/…/shortcuts.test.js• L189-208, code/…/shortcuts.test.js• L323-414

Shortcut handling runs before other manager key handlers and ignores text inputs, editable content, and open dialogs. It opens hidden regions before moving focus, waits briefly for delayed regions to mount, and cancels an older focus move when a newer one starts. Escape exits fullscreen only when an overlay has not already consumed it. References: code/…/shortcuts.ts• L185-221, code/…/shortcuts.ts• L290-467, code/…/shortcuts.ts• L577-593, code/…/shortcuts.test.js• L380-547

The preview forwards key events that need manager handling. Landmark navigation uses a separate path so F6 and Shift+F6 remain available to the accessibility layer in both documents. References: code/…/shortcuts.ts• L595-625, code/…/shortcuts.test.js• L550-597

Preview communication

The manager preview derives the active entry, view mode, refs, query parameters, toolbar tools, and wrappers from manager state. It creates the local or composed-ref frame URL and marks only the selected frame as active. The URL API can create matching manager and preview links while keeping manager-only values out of the preview link. References: code/…/Preview.tsx• L65-118, code/…/Preview.tsx• L24-35

The manager and preview exchange selection, preparation, index, argument, option, global, filter, and readiness events over the browser channel. Navigation normally changes the manager URL first, then the preview follows it. Prepared events enrich the manager index and can start nearby-story preloading. The manager also accepts older composed-Storybook selection payloads so cross-story links continue to work across supported versions. References: code/…/stories.ts• L78-104, code/…/stories.ts• L1127-1301

sequenceDiagram
  participant User
  participant Manager
  participant Channel
  participant Preview

  User->>Manager: Select story or change global
  Manager->>Manager: Update URL and manager state
  Manager->>Channel: Send selection or global change
  Channel->>Preview: Deliver event to active frame
  Preview-->>Channel: Report prepared state and story data
  Channel-->>Manager: Update index and readiness
  Manager->>Manager: Render active frame and shell

Target routing sends args, globals, and selection changes to the local preview or the selected composed ref. URL changes are emitted after manager URL state changes, so the preview and addons that read query state see the same values. References: code/…/Preview.tsx• L62-80, code/…/Preview.tsx• L141-188, code/…/Viewport.tsx• L223-273, code/…/channel.ts• L52-76, code/…/stories.ts• L782-797, code/…/url.ts• L329-404

Change checklist

When these files or sections are changed, remember to consider these:

  • When a manager state field changes, check its initial value, persistence mode, URL form if applicable, and every shell consumer that maps it into the UI.
  • When a store updater changes, check that it returns only the fields it owns so pending React updates cannot pin unrelated route or manager state.
  • When version data or upgrade rules change, check the current manager version source, current, latest, and next release handling, dismissed notices, documentation URL variants, renderer mapping, and menu or upgrade surfaces.
  • When a layout control changes, check desktop behavior, mobile drawer behavior, single-story behavior, review-route availability, and restoration of recent visible sizes.
  • When a sidebar row or status changes, check story selection, composed-ref targeting, keyboard activation, context-menu actions, status filters, bottom-widget spacing, shared scroll behavior, scrollbar focus behavior, and mobile drawer closing.
  • When an addon element type changes, check registration, page or preview collection lookup, element filtering, and the public addon type mapping.
  • When addon state changes, check the selected-panel fallback, session persistence, no-op write behavior, addon state reads, and manager fields that can update at the same time.
  • When the manager global module map changes, check the matching reference map and the shared runtime surface available to manager addons.
  • When a route or view mode changes, check URL parsing, page selection, sidebar availability, settings return behavior, and the preview frame URL.
  • When a channel event changes, check target routing for local and composed refs and both the manager listener and preview listener.
  • When a shortcut changes, check default bindings, persisted stale bindings, addon re-registration, conflict and Escape validation, focus timing, and preview key forwarding.
  • When global or viewport controls change, check the manager value, the preview value, story-level overrides, and links that carry query state.
  • When a preview tool changes, check its view-mode match, hidden-region focus target, single-story behavior, and the event contract used by the preview.
  • When panel filtering changes, check both unprepared and prepared story data and the distinction between story parameters, panel parameters, and static disable rules.
  • When the sidebar scroll area changes, check the explorer and search scroll ownership, tree positioning context, bottom-widget padding, and pointer or focus scrollbar behavior.

Important failure modes

TriggerConsequenceGuard
The manager channel is installed after an addon reads itEarly listeners can attach to a throwaway channel and miss preview eventsInstall the browser channel before deferred manager rendering and addon loading
Version check data is malformed or unavailableUpgrade state and documentation links can lose version contextTreat the global payload as optional and fall back to the running manager version
A prerelease is compared directly with the stable latest releaseThe manager can show the wrong upgrade target or noticeCompare the prerelease against the next release and normalize it for update checks
A selected story or ref is missing from the current indexThe manager cannot create a valid preview URL or sidebar selectionResolve against the active local or ref index and fall back to a filtered first story when starting
A channel event uses the wrong preview targetAn argument or selection update reaches no frame or the wrong composed StorybookNormalize targets to the local preview or the matching ref identifier
A review route still treats navigation as availableSidebar actions and sidebar shortcuts expose controls that the route must suppressUse route-aware navigation availability for both rendering and shortcut matching
The mobile drawer state is restored from storageThe manager can open with navigation covering the previewKeep mobile navigation ephemeral and reset it when restoring layout state
A shortcut binding remains for an unregistered addonThe capture listener can swallow a key without running an actionMatch addon bindings only after the addon registers them
A shortcut focus request finishes after a newer requestFocus jumps back to an older region after the user has moved itAbort the previous focus request when a new one starts
A story-level global overrides a toolbar globalA manager control can suggest a value that the story does not useDisable the control while the story override is active
A viewport resize is applied while the frame is scaledThe visible frame size and the reported story viewport can differConvert displayed dimensions back through the current scale before committing the resize
The preview WebSocket disconnectsThe manager can show stale story data and controlsShow the connection-lost notification and require a server restart or page reload
React commits manager updates out of orderA later API read or addon update can use an older field valueKeep ordered pending patches and expose their merged view until earlier patches commit
An addon state updater spreads the full manager stateA pending update can overwrite a newer route or manager fieldSubmit a partial patch containing only the addon state branch
An addon clears status through a missing or failing provider hookOne provider can break status reset for all providersSkip missing hooks and catch each provider error before continuing
A manager addon imports a module absent from the global runtime mapThe addon can fail when it resolves its shared manager dependencyKeep the reference map and value map aligned and use only the supported manager runtime surface
A composed preview sends only a legacy selection payloadStory links can stop navigating in mixed-version StorybooksNormalize legacy title and name fields before selecting the story
A hidden sidebar or panel tool omits its focus targetKeyboard users can restore a region without a usable focus destinationOpen the region and focus its registered landmark, with polling for delayed mount
A remount tool emits without the active story identifierThe preview cannot identify which story to reloadDisable the tool until a story is selected and send the current story ID with the event
A panel filter runs only at bootA panel can remain visible or hidden after story preparation changes its parametersRe-evaluate panels on preparation events while preserving panels that do not match the active story
The sidebar bottom widget covers the final tree rowsUsers cannot reach or inspect the last storiesMeasure the bottom content and apply matching scroll padding
A tree selection change is treated as activation during focus movementArrow-key navigation can expand branches or navigate stories unexpectedlyActivate only for pointer or Space input and handle Enter through the action path
A tree or search view owns a different scroll area than its positioning logicSticky rows or row reveal can use the wrong scroll position, or one reference block can become unreachableKeep the shared scroll-area context aligned with the explorer tree and use a separate area only for search results

Key files

FileWhy to read it
code/…/runtime.tsxShows manager startup, channel setup, addon loading, toolbar registration, and disconnect handling.
code/…/runtime.tsShows the shared module values exposed to manager code and addons.
code/…/index.tsxShows the provider tree and the boundary between routing, manager state, theme, and the application shell.
code/…/App.tsxShows how the sidebar, preview, panel, pages, and persistent overlays compose into one application.
code/…/Layout.tsxShows desktop and mobile regions and how layout sizes affect the shell.
code/…/root.tsxShows the combined manager state and API model used by the UI and addons.
code/…/store.tsShows state persistence, no-op writes, and the ordered pending-update view used during React commits.
code/…/addons.tsShows addon elements, panel selection, addon state, and test-provider status access.
code/…/layout.tsShows layout options, route-aware navigation, persistence, mobile drawer state, and UI customisations.
code/…/version.tsDefines the manager version used to seed version state and upgrade checks.
code/…/versions.tsShows version state, documentation link selection, and upgrade availability used by the manager UI.
code/…/shortcuts.tsShows built-in and addon shortcut state, key handling, focus movement, and preview key forwarding.
code/…/stories.tsShows story selection, index updates, filters, preview readiness, compatibility handling, and manager-preview event handling.
code/…/url.tsShows the boundary between manager URL state and preview query state and how story links are built.
code/…/Sidebar.tsxShows how the sidebar composes the heading, checklist or review widget, search, explorer, search results, and bottom status area.
code/…/SidebarScrollArea.tsxShows the shared sidebar scroll contract, tree context, bottom padding, and focus-aware scrollbar behavior.
code/…/Explorer.tsxShows how refs and their story trees form the main navigation area.
code/…/Tree.tsxShows story tree activation, virtual navigation, sticky context, preloading, statuses, context actions, and mobile behavior.
code/…/TreeNode.tsxShows row labels, accessibility state, context actions, status badges, and story or docs row identity.
code/…/SidebarBottom.tsxShows notifications, test status controls, status filters, and bottom-area space management.
code/…/SearchResults.tsxShows search result presentation, recent-story controls, status marks, and search preloading.
code/…/Menu.tsxShows settings links, shell toggles, story actions, documentation, and addon menu actions.
code/…/Panel.tsxShows panel filtering, story preparation updates, selected-panel state, and panel visibility actions.
code/…/Panel.test.tsxShows the panel contract for static disable rules, story parameter rules, and prepared-story updates.
code/…/Preview.tsxShows how manager state and addon elements become preview props.
code/…/Preview.tsxShows loading, wrappers, toolbar display, scaling, and the active canvas.
code/…/Viewport.tsxShows viewport sizing, rotation, restore behavior, and frame resizing.
code/…/addons.tsxShows the hidden-panel toolbar control and its focus behavior.
code/…/menu.tsxShows the hidden-sidebar toolbar control and its view-mode and navigation rules.
code/…/remount.tsxShows the story reload tool and its preview event contract.
code/…/zoom.tsxShows zoom controls and their addon shortcut registrations.
code/…/Checklist.tsxShows guide progress, item actions, locks, skip and reset behavior, and deep links.
code/…/shortcuts.tsxShows shortcut editing, conflict validation, Escape protection, and restoring defaults.