0
# Story Decoration
1

2
Core decorator functionality for adding info panels to Storybook stories with flexible configuration options and parameter-based customization.
3

4
## Capabilities
5

6
### withInfo Decorator
7

8
Main decorator function that wraps stories with info addon functionality.
9

10
```javascript { .api }
11
/**
12
 * Main decorator for adding info addon to stories
13
 * @param {Object|string} options - Configuration options or simple text content
14
 * @returns {Function} Storybook decorator function that can be used globally or per-story
15
 */
16
function withInfo(options);
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import { withInfo } from "@storybook/addon-info";
23
import { addDecorator } from "@storybook/react";
24

25
// Global decorator with default options
26
addDecorator(withInfo);
27

28
// Global decorator with custom options
29
addDecorator(
30
  withInfo({
31
    inline: true,
32
    header: false,
33
    source: true,
34
    propTables: [Button, Input],
35
  })
36
);
37

38
// Per-story usage
39
export default {
40
  title: "Components/Button",
41
  decorators: [withInfo],
42
};
43

44
// Per-story with options
45
export default {
46
  title: "Components/Button", 
47
  decorators: [
48
    withInfo({
49
      text: "Button component documentation",
50
      inline: true,
51
    }),
52
  ],
53
};
54
```
55

56
### Story Component
57

58
Core React component that renders the story with additional info panel, handling both inline and overlay display modes.
59

60
```javascript { .api }
61
/**
62
 * Core component that renders story information panels
63
 * @param {Object} props - Story component props
64
 */
65
function Story(props);
66

67
interface StoryProps {
68
  /** Story context with kind and name */
69
  context?: StoryContext;
70
  /** Info text content (string or React node) */
71
  info?: string | React.ReactNode;
72
  /** Components to show prop tables for */
73
  propTables?: Array<Function>;
74
  /** Components to exclude from prop tables */
75
  propTablesExclude?: Array<Function>;
76
  /** Function to compare prop table components */
77
  propTableCompare: Function;
78
  /** Display info inline vs overlay */
79
  showInline?: boolean;
80
  /** Show story header */
81
  showHeader?: boolean;
82
  /** Show source code */
83
  showSource?: boolean;
84
  /** Styles function or object */
85
  styles: Function;
86
  /** Story children (the actual story content) */
87
  children?: React.ReactNode;
88
  /** Custom markdown components */
89
  components?: Object;
90
  /** Prop table component to use */
91
  PropTable: React.ComponentType;
92
  /** Max object keys in prop display */
93
  maxPropObjectKeys: number;
94
  /** Max array length in prop display */
95
  maxPropArrayLength: number;
96
  /** Max props per line in source */
97
  maxPropsIntoLine: number;
98
  /** Max string length in prop display */
99
  maxPropStringLength: number;
100
  /** Props to exclude from tables */
101
  excludedPropTypes?: Array<string>;
102
}
103

104
interface StoryContext {
105
  /** Story category/group name */
106
  kind: string;
107
  /** Individual story name */
108
  name: string;
109
}
110
```
111

112
### Configuration Options
113

114
Complete configuration interface with all available options for customizing the info addon behavior.
115

116
```javascript { .api }
117
interface InfoOptions {
118
  /** Display info inline instead of overlay button (default: false) */
119
  inline?: boolean;
120
  /** Show header with component name and description (default: true) */
121
  header?: boolean;
122
  /** Display the source code of story component (default: true) */
123
  source?: boolean;
124
  /** Array of components to show prop tables for (default: []) */
125
  propTables?: Array<React.ComponentType>;
126
  /** Array of components to exclude from prop tables (default: []) */
127
  propTablesExclude?: Array<React.ComponentType>;
128
  /** Custom function to compare components for prop tables */
129
  propTableCompare?: PropTableCompareFunction;
130
  /** Custom styles object or function to override default styles */
131
  styles?: Object | StylesFunction;
132
  /** Custom markdown component overrides for text rendering */
133
  components?: { [key: string]: React.ComponentType };
134
  /** Maximum props to display per line in source code (default: 3) */
135
  maxPropsIntoLine?: number;
136
  /** Maximum object keys to display in prop values (default: 3) */
137
  maxPropObjectKeys?: number;
138
  /** Maximum array length to display in prop values (default: 3) */
139
  maxPropArrayLength?: number;
140
  /** Maximum string length to display in prop values (default: 50) */
141
  maxPropStringLength?: number;
142
  /** Custom prop table component to replace default PropTable */
143
  TableComponent?: React.ComponentType;
144
  /** Array of prop names to exclude from prop tables (default: []) */
145
  excludedPropTypes?: Array<string>;
146
  /** Text content to display in info panel (supports markdown) */
147
  text?: string;
148
}
149

150
interface PropTableCompareFunction {
151
  /**
152
   * Custom function to determine if an element matches a component for prop table display
153
   * @param element - React element from the story
154
   * @param Component - Component type to compare against
155
   * @returns Boolean indicating if they match
156
   */
157
  (element: React.ReactElement, Component: React.ComponentType): boolean;
158
}
159

160
interface StylesFunction {
161
  /**
162
   * Function to customize addon styles
163
   * @param defaultStyles - Default style object
164
   * @returns Modified styles object
165
   */
166
  (defaultStyles: Object): Object;
167
}
168
```
169

170
### Legacy API (Deprecated)
171

172
```javascript { .api }
173
/**
174
 * @deprecated Use withInfo options parameter instead
175
 * Sets global default options for the info addon
176
 * @param {Object} newDefaults - Default options to merge
177
 * @returns {Function} Deprecated function
178
 */
179
function setDefaults(newDefaults);
180
```
181

182
**Migration Example:**
183

184
```javascript
185
// OLD (deprecated)
186
import { setDefaults } from "@storybook/addon-info";
187
setDefaults({ inline: true });
188

189
// NEW (recommended) 
190
import { withInfo } from "@storybook/addon-info";
191
addDecorator(withInfo({ inline: true }));
192
```
193

194
## Advanced Usage
195

196
### Custom Prop Table Comparison
197

198
```javascript
199
// Custom comparison for React Hot Loader compatibility
200
const customPropTableCompare = (element, Component) => {
201
  return typeof reactHotLoaderGlobal === 'undefined'
202
    ? element.type === Component
203
    : reactHotLoaderGlobal.areComponentsEqual(element.type, Component);
204
};
205

206
addDecorator(
207
  withInfo({
208
    propTableCompare: customPropTableCompare,
209
  })
210
);
211
```
212

213
### Custom Styling
214

215
```javascript
216
// Style function approach
217
const customStyles = (defaultStyles) => ({
218
  ...defaultStyles,
219
  button: {
220
    ...defaultStyles.button,
221
    base: {
222
      ...defaultStyles.button.base,
223
      backgroundColor: '#ff0000',
224
      color: 'white',
225
    },
226
  },
227
  infoBody: {
228
    ...defaultStyles.infoBody,
229
    fontFamily: 'monospace',
230
  },
231
});
232

233
addDecorator(withInfo({ styles: customStyles }));
234
```
235

236
### Conditional Display
237

238
```javascript
239
// Disable info for specific stories
240
export const HiddenInfo = () => <Component />;
241
HiddenInfo.story = {
242
  parameters: {
243
    info: { disable: true },
244
  },
245
};
246
```