# How to Use the Outline Addon for CSS Debugging in Storybook

> Debug CSS layout issues in Storybook instantly with the Outline addon. This tool adds colored outlines to all elements, making CSS debugging quick and easy. Press 'o' to enable.

- Repository: [Storybook/storybook](https://github.com/storybookjs/storybook)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/outline/constants.ts) and [`code/core/src/outline/preview.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/outline/preview.ts). The [`constants.ts`](https://github.com/storybookjs/storybook/blob/main/constants.ts) file declares the addon ID (`storybook/outline`) and the global parameter key (`outline`), while [`preview.ts`](https://github.com/storybookjs/storybook/blob/main/preview.ts) registers the preview addon with default `initialGlobals` set to `{ outline: false }`.

The decorator logic lives in [`code/core/src/outline/withOutline.ts`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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:

```js
// .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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/outline/preview.ts) or your local preview file:

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

```

### Per-Story Configuration

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

```tsx
// 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

```ts
// .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

```tsx
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:

```js
// .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:

```css
.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`](https://github.com/storybookjs/storybook/blob/main/withOutline.ts), using styles generated by [`outlineCSS.ts`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/helpers.ts), leaving no trace in your production component code or static builds.