How to Use the Outline Addon for CSS Debugging in Storybook

The Outline addon injects a scoped CSS stylesheet that applies colored 1px outlines to every HTML element in your Storybook stories, helping you debug layout issues instantly by pressing o or clicking the toolbar button.

The Outline addon is included by default in Storybook's Essentials package and provides a powerful visual debugging tool for CSS layout analysis. According to the storybookjs/storybook source code, this addon works by dynamically injecting a comprehensive stylesheet that targets every common HTML element with distinct colored borders. This allows developers to see the box model of components without manually adding temporary CSS rules.

How the Outline Addon Works

The addon follows a decorator-based architecture that monitors a global state parameter and conditionally injects CSS into the preview canvas or Docs view.

Core Architecture

The addon's entry points and state management are defined in code/core/src/outline/constants.ts and code/core/src/outline/preview.ts. The constants.ts file declares the addon ID (storybook/outline) and the global parameter key (outline), while preview.ts registers the preview addon with default initialGlobals set to { outline: false }.

The decorator logic lives in code/core/src/outline/withOutline.ts. This file exports a decorator function that:

1. Reads the global outline boolean value from Storybook's globals
2. Computes the appropriate CSS selector (.sb-show-main for the canvas view or [data-story-block="true"] for Docs)
3. Calls outlineCSS to generate the stylesheet content
4. Uses helper functions to insert or remove the <style> element from the DOM

CSS Injection Mechanism

When activated, the addon generates a heavyweight CSS string via code/core/src/outline/outlineCSS.ts. This module uses ts-dedent to produce a template literal that applies a different colored outline rule to each HTML element (body, header, h1, button, etc.). The selector argument scopes these rules to prevent leakage outside Storybook's preview container.

The code/core/src/outline/helpers.ts file provides low-level DOM utilities that create, update, or remove the <style> element with a specific ID, ensuring efficient updates when toggling the feature on and off.

Enabling the Outline Addon for CSS Debugging

Prerequisites

The Outline addon is part of @storybook/addon-essentials, which is included by default in modern Storybook installations. Ensure your main configuration includes:

// .storybook/main.js
module.exports = {
  addons: [
    '@storybook/addon-essentials', // includes outline addon
  ],
};

Global Configuration

You can control the addon's behavior globally through parameters in your preview configuration. To completely disable the outline addon for your entire Storybook instance, add the following to code/core/src/outline/preview.ts or your local preview file:

// .storybook/preview.js
export const parameters = {
  outline: { disable: true },
};

Per-Story Configuration

Disable or enable outlines for individual stories by overriding the global parameter:

// Button.stories.tsx
export const Primary = {
  args: { label: 'Primary' },
  parameters: {
    outline: { disable: true }, // Disables outlines for this specific story
  },
};

Keyboard Shortcuts and Toolbar Controls

The addon registers a keyboard shortcut (o) that toggles the boolean global state. You can also activate the feature by clicking the "Outline" button in the Storybook toolbar. The current state persists in the global outline key, making it easy to switch between normal and debugging views during development.

Code Examples

Disabling Outlines Globally in TypeScript

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    outline: { disable: true }, // Completely disables outline addon
  },
};

export default preview;

Enabling Outlines for a Specific Story

import type { StoryFn } from '@storybook/react';

export const DebugLayout: StoryFn = (args) => <ComplexComponent {...args} />;
DebugLayout.parameters = {
  // Explicitly enable outline for this story only
  outline: { disable: false },
};

Manual Decorator Registration

While the addon auto-registers when FEATURES?.outline is true, you can manually import the decorator for custom builds:

// .storybook/preview.js
import { withOutline } from 'storybook/outline';

export const decorators = [withOutline];

Inspecting the Injected CSS

To verify the addon is working or debug the CSS rules, open your browser's DevTools and locate the <style> element with ID addon-outline (or addon-outline-docs-<story-id> for Docs view). The content matches exactly what outlineCSS generates:

.sb-show-main body { outline: 1px solid #2980b9 !important; }
.sb-show-main h1   { outline: 1px solid #162544 !important; }
.sb-show-main div  { outline: 1px solid #16a085 !important; }
/* ... additional element rules ... */

Summary

• The Outline addon is included in @storybook/addon-essentials and located in code/core/src/outline/.
• It injects CSS via the withOutline decorator defined in withOutline.ts, using styles generated by outlineCSS.ts.
• Press o or use the toolbar button to toggle outlines on and off.
• Disable the addon globally using outline: { disable: true } in preview parameters.
• Override settings per-story using the outline parameter in story objects.
• The injected stylesheet targets .sb-show-main for canvas views and [data-story-block="true"] for Docs views.

Frequently Asked Questions

How do I completely remove the Outline addon from Storybook?

Remove @storybook/addon-essentials from your main.js addons array, or exclude the specific addon by configuring Essentials with outline: false. Alternatively, set outline: { disable: true } in your preview parameters to disable it while keeping the package installed.

Why are outlines appearing on my host page outside of Storybook?

The withOutline decorator in code/core/src/outline/withOutline.ts specifically scopes CSS selectors to .sb-show-main (canvas) or [data-story-block="true"] (Docs). If outlines leak, verify you are not manually injecting the CSS and that your Storybook version is up to date.

Can I customize the colors used by the Outline addon?

The current implementation in outlineCSS.ts uses hardcoded color values for each element type. To customize colors, you would need to fork the addon or apply custom CSS overrides after the addon injects its stylesheet.

Does the Outline addon affect production builds?

No. The addon only injects styles into the Storybook preview iframe during development. The CSS is dynamically added and removed via DOM manipulation in helpers.ts, leaving no trace in your production component code or static builds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}