or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-storybook--addon-outline

Outline all elements with CSS to help with layout placement and alignment

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/addon-outline@8.6.x

To install, run

npx @tessl/cli install tessl/npm-storybook--addon-outline@8.6.0

index.mddocs/

@storybook/addon-outline

@storybook/addon-outline provides visual debugging capabilities for Storybook by drawing colored outlines around HTML elements. Based on the Pesticide CSS library, it helps developers identify layout issues, understand element boundaries, and debug complex UI components through an integrated toolbar toggle and keyboard shortcut.

Package Information

  • Package Name: @storybook/addon-outline
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -D @storybook/addon-outline
  • Storybook Support: 6.1+ (included in essentials by default)
  • Framework Support: All Storybook frameworks except React Native

Core Imports

Main entry point:

import addonOutline from "@storybook/addon-outline";
import type { OutlineParameters } from "@storybook/addon-outline";

Preview-specific imports:

import { decorators, initialGlobals } from "@storybook/addon-outline/preview";

Basic Usage

Configuration

Add to your .storybook/main.js (if not using essentials):

export default {
  addons: ['@storybook/addon-outline'],
};

Activation

  • Toolbar Button: Click the outline icon in the Storybook toolbar
  • Keyboard Shortcut: Press Alt+O (Windows/Linux) or Option+O (Mac)
  • Programmatic: Set the global parameter outline: true

Basic Example

// .storybook/preview.js
export default {
  globals: {
    outline: false, // Default state
  },
};

Capabilities

Addon Configuration

Configure the outline addon for preview integration.

/**
 * Default export factory function that configures the addon for preview
 * Returns a preview configuration with decorator and global annotations
 */
declare function addonOutline(): PreviewAnnotations;

Usage Example:

// .storybook/preview.js
import addonOutline from '@storybook/addon-outline';

export default addonOutline();

Type Definitions

Configuration interface for addon parameters.

/**
 * Addon configuration parameters interface
 */
interface OutlineParameters {
  /**
   * Outline configuration
   * @see https://storybook.js.org/docs/essentials/measure-and-outline#parameters
   */
  outline: {
    /** Remove the addon panel and disable the addon's behavior */
    disable?: boolean;
  };
}

Usage Example:

// In a story file
export default {
  title: 'Example/Button',
  component: Button,
  parameters: {
    outline: {
      disable: true, // Disable outline for this story
    },
  },
};

Preview Integration

Core decorator and global configuration exported from preview entry point.

/**
 * Array of decorators including the outline decorator
 */
declare const decorators: DecoratorFunction[];

/**
 * Initial global state configuration
 * Sets the outline parameter to false by default
 */
declare const initialGlobals: {
  outline: boolean;
};

Usage Example:

// .storybook/preview.js
import { decorators, initialGlobals } from '@storybook/addon-outline/preview';

export default {
  decorators,
  initialGlobals,
};

Architecture

The addon is built around several key components:

  • Manager Integration: Registers toolbar button and keyboard shortcut (Alt+O/Option+O) via Storybook's manager API
  • Preview Decorator: Core decorator monitors global state and injects/removes CSS dynamically
  • Dynamic CSS: Pesticide-based CSS generation that outlines all HTML elements with unique colors for each element type
  • Context Awareness: Different behavior for story view (.sb-show-main selector) vs docs view ([data-story-block="true"] selector)
  • Global State: Uses Storybook's global parameter system (outline key) for state management

Advanced Configuration

Story-Level Configuration

// In a story file
export const MyStory = {
  parameters: {
    outline: {
      disable: true, // Disable for this specific story
    },
  },
};

Global Configuration

// .storybook/preview.js
export default {
  globals: {
    outline: true, // Enable by default for all stories
  },
};

Manual Integration

For custom preview configurations:

// .storybook/preview.js
import { decorators, initialGlobals } from '@storybook/addon-outline/preview';

export default {
  decorators: [...decorators, /* your other decorators */],
  initialGlobals: {
    ...initialGlobals,
    // your other globals
  },
};