0
# @storybook/addon-outline
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-outline
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D @storybook/addon-outline`
10
- **Storybook Support**: 6.1+ (included in essentials by default)
11
- **Framework Support**: All Storybook frameworks except React Native
12

13
## Core Imports
14

15
Main entry point:
16

17
```typescript
18
import addonOutline from "@storybook/addon-outline";
19
import type { OutlineParameters } from "@storybook/addon-outline";
20
```
21

22
Preview-specific imports:
23

24
```typescript
25
import { decorators, initialGlobals } from "@storybook/addon-outline/preview";
26
```
27

28
## Basic Usage
29

30
### Configuration
31

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

34
```javascript
35
export default {
36
  addons: ['@storybook/addon-outline'],
37
};
38
```
39

40
### Activation
41

42
- **Toolbar Button**: Click the outline icon in the Storybook toolbar
43
- **Keyboard Shortcut**: Press `Alt+O` (Windows/Linux) or `Option+O` (Mac)
44
- **Programmatic**: Set the global parameter `outline: true`
45

46
### Basic Example
47

48
```typescript
49
// .storybook/preview.js
50
export default {
51
  globals: {
52
    outline: false, // Default state
53
  },
54
};
55
```
56

57
## Capabilities
58

59
### Addon Configuration
60

61
Configure the outline addon for preview integration.
62

63
```typescript { .api }
64
/**
65
 * Default export factory function that configures the addon for preview
66
 * Returns a preview configuration with decorator and global annotations
67
 */
68
declare function addonOutline(): PreviewAnnotations;
69
```
70

71
**Usage Example:**
72

73
```typescript
74
// .storybook/preview.js
75
import addonOutline from '@storybook/addon-outline';
76

77
export default addonOutline();
78
```
79

80
### Type Definitions
81

82
Configuration interface for addon parameters.
83

84
```typescript { .api }
85
/**
86
 * Addon configuration parameters interface
87
 */
88
interface OutlineParameters {
89
  /**
90
   * Outline configuration
91
   * @see https://storybook.js.org/docs/essentials/measure-and-outline#parameters
92
   */
93
  outline: {
94
    /** Remove the addon panel and disable the addon's behavior */
95
    disable?: boolean;
96
  };
97
}
98
```
99

100
**Usage Example:**
101

102
```typescript
103
// In a story file
104
export default {
105
  title: 'Example/Button',
106
  component: Button,
107
  parameters: {
108
    outline: {
109
      disable: true, // Disable outline for this story
110
    },
111
  },
112
};
113
```
114

115
### Preview Integration
116

117
Core decorator and global configuration exported from preview entry point.
118

119
```typescript { .api }
120
/**
121
 * Array of decorators including the outline decorator
122
 */
123
declare const decorators: DecoratorFunction[];
124

125
/**
126
 * Initial global state configuration
127
 * Sets the outline parameter to false by default
128
 */
129
declare const initialGlobals: {
130
  outline: boolean;
131
};
132
```
133

134
**Usage Example:**
135

136
```typescript
137
// .storybook/preview.js
138
import { decorators, initialGlobals } from '@storybook/addon-outline/preview';
139

140
export default {
141
  decorators,
142
  initialGlobals,
143
};
144
```
145

146
## Architecture
147

148
The addon is built around several key components:
149

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

156
## Advanced Configuration
157

158
### Story-Level Configuration
159

160
```typescript
161
// In a story file
162
export const MyStory = {
163
  parameters: {
164
    outline: {
165
      disable: true, // Disable for this specific story
166
    },
167
  },
168
};
169
```
170

171
### Global Configuration
172

173
```typescript
174
// .storybook/preview.js
175
export default {
176
  globals: {
177
    outline: true, // Enable by default for all stories
178
  },
179
};
180
```
181

182
### Manual Integration
183

184
For custom preview configurations:
185

186
```typescript
187
// .storybook/preview.js
188
import { decorators, initialGlobals } from '@storybook/addon-outline/preview';
189

190
export default {
191
  decorators: [...decorators, /* your other decorators */],
192
  initialGlobals: {
193
    ...initialGlobals,
194
    // your other globals
195
  },
196
};
197
```