OpenWikistorybookjs/storybook

Measure, Outline, and Highlight

Purpose and Scope

Storybook’s visual inspection helpers let a developer debug a rendered story without leaving the component workshop. A story renders in the preview iframe, and these helpers add temporary overlays or selection affordances on top of that rendered DOM. The shared goal is fast feedback for layout, alignment, spacing, and issue localization while the component is already isolated in Storybook. Measure focuses on the box model of a hovered element, Outline exposes element boundaries across the preview, and Highlight targets specific DOM nodes from a story or addon event.

Sources: docs/essentials/highlight.mdx, code/core/src/measure/README.md, code/core/src/outline/README.md

These features are part of the Essentials area rather than the story authoring model itself. They do not replace args, decorators, play functions, or accessibility assertions; instead, they give the person viewing a story an inspection layer for what the browser actually rendered. That distinction matters when debugging: stories define component states, while inspection helpers make those states easier to understand visually. A design-system maintainer might use Outline to see whether wrapper elements create unexpected nesting, Measure to inspect padding and border dimensions, and Highlight to point users toward elements found by another addon.

Relevant Source Files

  • docs/essentials/highlight.mdx — Documents the Highlight feature, including the HIGHLIGHT, REMOVE_HIGHLIGHT, RESET_HIGHLIGHT, and SCROLL_INTO_VIEW events, selector payloads, style customization, and click menus.
  • code/core/src/measure/README.md — Describes the Measure addon as a layout inspection tool that visualizes margin, padding, border, width, and height when enabled and hovering DOM nodes.
  • code/core/src/outline/README.md — Describes the Outline addon as a preview-pane visual debugging tool that draws outlines around every element and can be toggled from the toolbar or keyboard.

Core Primitives

Measure is the most direct box-model inspector. The supplied Measure README describes enabling the addon with the m key, hovering a DOM node, and seeing dimensions for margin, padding, border, width, and height in pixels. That workflow is intentionally close to browser DevTools, but optimized for Storybook’s preview: the developer is already looking at a single component state, so the overlay answers, “what is this element’s rendered size and spacing right now?” Use it when a component is visually close but exact spacing or dimensions are suspicious.

Outline is a broad layout scanner. The supplied Outline README says it draws outlines around every element in the preview pane and can be toggled with the outline toolbar button or the o key. Because it applies across the rendered preview, it is useful before drilling into a single node with Measure. It can reveal unexpected wrapper elements, invisible layout boxes, off-by-one alignment problems, or flex and grid children that occupy space differently than expected. Its strength is showing the page structure at a glance, not attaching metadata to a particular issue.

Highlight is the programmable primitive. The docs describe it as a way to highlight specific DOM nodes within a story when used directly, or to enhance addons such as the Accessibility addon by pointing to elements with issues. Unlike Measure and Outline, Highlight is driven by Storybook events. A story or addon emits an event with selectors, and Storybook’s UI updates the highlighted elements. That makes Highlight a bridge between automated analysis and visual debugging: an addon can find a problem, then mark the affected DOM nodes so the developer can inspect them in context.

Sources: docs/essentials/highlight.mdx, code/core/src/measure/README.md, code/core/src/outline/README.md

Highlight Event API

The Highlight docs define an event-oriented contract. To add highlights, emit the HIGHLIGHT event with a payload containing selectors, an array of selectors matching the elements to highlight. The page explicitly recommends choosing the most specific selector possible because the feature tries to match selectors against the entire DOM tree. That guidance is important for addon authors: broad selectors can accidentally match Storybook chrome, addon-rendered elements, or multiple unrelated nodes inside a complex story. Treat selector specificity as part of the user experience, not just an implementation detail.

emit(HIGHLIGHT, {
  selectors: ['[data-testid="primary-submit"]'],
});

The Highlight payload can also carry optional style properties. The docs state that highlighted elements have a standard outline by default, but that additional payload properties can customize their appearance. The same section notes that hoverStyles and focusStyles are recommended when using a menu, and that pseudo-classes and pseudo-elements are not supported. In practice, this means a custom visual language should be expressed through the supported payload fields rather than CSS selectors such as :hover or generated pseudo-element content.

Highlight can do more than paint a static outline. The docs describe a built-in debugging menu that appears when clicking a highlighted element. To enable it, add a menu property to the payload. Each menu item must include an id and a title, and can include an optional selectors property to limit that menu item to particular highlighted elements. If no custom information is needed, the menu property can be omitted, or set to an empty array to show the default menu of selectable targets.

Removal and reset use separate events because they serve different scopes. To remove a specific highlight, emit REMOVE_HIGHLIGHT with the id of the highlight to remove. To clear all highlights manually, emit RESET_HIGHLIGHT. The docs also state that Storybook automatically removes highlighted elements when transitioning between stories, so manual reset is mainly for story or addon flows that need cleanup before navigation. Be careful with RESET_HIGHLIGHT in addons because it removes all highlights, including ones created by other addons.

The SCROLL_INTO_VIEW event adds another task-oriented behavior: it scrolls a targeted element into view and highlights it. The documented payload must include a selector property for the element to target. This is useful when a report or addon panel references an issue outside the current viewport. Rather than asking the user to search the rendered page manually, the addon can move the preview to the relevant node and then apply a visual marker so the issue is immediately visible.

Sources: docs/essentials/highlight.mdx

Execution Flow

A typical inspection session starts with a running Storybook and a selected story in the preview iframe. If the question is general layout structure, toggle Outline first and look for unexpected boxes or alignment boundaries. If the question is exact spacing, enable Measure and hover the suspicious node to read its dimensions and box-model values. If the question came from an automated or addon-driven signal, emit a Highlight event so the preview marks the specific DOM nodes being discussed. These helpers compose naturally because each answers a different visual-debugging question.

For addon authors, the flow is event-driven. An addon can compute selectors from its own analysis, then emit HIGHLIGHT through Storybook’s channel. The Highlight docs call out that the emit function derived from the useChannel API hook creates a communication channel in Storybook’s UI so listeners can update the UI. That means the addon does not directly mutate the preview DOM as its public integration contract; it communicates intent through documented events and payloads, leaving Storybook’s Highlight feature to render and manage the overlay.

Implementation Guidance and Next Steps

Prefer the least disruptive helper that answers the current question. Use Outline for a broad structural scan, Measure for precise spacing and dimensions, and Highlight when a story or addon needs to call attention to exact elements. When authoring Highlight integrations, use stable selectors such as test IDs or component-specific attributes rather than broad element selectors. Add menus only when there is useful context or an action for the user; otherwise, keep the overlay simple and avoid competing with other addons that may also use Highlight.

Next, read the Essentials pages for related inspection and context controls. Backgrounds and Viewport help reproduce visual environments, while Toolbars and Globals can switch themes, locales, and feature modes before you inspect the rendered result. For automated issue discovery, pair Highlight with accessibility or interaction-testing workflows so a failing condition can point directly to the DOM node the developer needs to fix.

Ask a question...