UNPKG

8.52 kBMarkdownView Raw
1# Storybook Info Addon
2
3Storybook Info Addon will show additional information for your stories in [Storybook](https://storybook.js.org).
4Useful when you want to display usage or other types of documentation alongside your story.
5
6[Framework Support](https://github.com/storybookjs/storybook/blob/master/ADDONS_SUPPORT.md)
7
8![Screenshot](https://raw.githubusercontent.com/storybookjs/storybook/master/addons/info/docs/home-screenshot.png)
9
10## Installation
11
12Install the following npm module:
13
14```sh
15npm i -D @storybook/addon-info
16```
17
18## Basic usage
19
20Then, add `withInfo` as a decorator to your book of stories.
21It is possible to add `info` by default to all or a subsection of stories by using a global or story decorator.
22
23It is important to declare this decorator as **the first decorator**, otherwise it won't work well.
24
25```js
26// Globally in your .storybook/preview.js.
27import { addDecorator } from '@storybook/react';
28import { withInfo } from '@storybook/addon-info';
29
30addDecorator(withInfo);
31```
32
33or
34
35```js
36export default {
37 title: 'Component',
38 decorators: [withInfo],
39};
40```
41
42Then, you can use the `info` parameter to either pass certain options or specific documentation text to your stories.
43A complete list of possible configurations can be found [in a later section](#setting-global-options).
44This can be done per book of stories:
45
46```js
47import Component from './Component';
48
49export default {
50 title: 'Component',
51 parameters: {
52 info: {},
53 },
54};
55```
56
57...or for each story individually:
58
59```js
60import Component from './Component';
61
62export default {
63 title: 'Component',
64};
65
66export const defaultView = () => <Component />;
67defaultView.story = {
68 parameters: {
69 info: { inline: true },
70 },
71};
72```
73
74It is also possible to disable the `info` addon entirely.
75Depending on the scope at which you want to disable the addon, pass the following parameters object either to an individual story or to an `addParameters` call.
76
77```
78info: {
79 disable: true,
80}
81```
82
83## Markdown
84
85The `info` addon also supports markdown.
86To use markdown as additional textual documentation for your stories, either pass it directly as a String to the `info` parameters, or use the `text` option.
87
88```js
89info: {
90 text: `
91 description or documentation about my component, supports markdown
92
93 ~~~js
94 <Button>Click Here</Button>
95 ~~~
96 `,
97}
98```
99
100## Setting Global Options
101
102To configure default options for all usage of the info addon, pass a option object along with the decorator in `.storybook/preview.js`.
103
104```js
105import { withInfo } from '@storybook/addon-info';
106
107addDecorator(
108 withInfo({
109 header: false,
110 })
111);
112```
113
114Configuration parameters can be set at 3 different locations: passed as default options along the `addDecorator` call, passed as an object of parameters to a book of stories to the `addParameters` call, and passed as direct parameters to each individual story.
115In order, all of them will be combined together, with a later call overriding the previous set configurations on a per-key basis.
116
117## Options and Defaults
118
119```js
120{
121 /**
122 * Text to display with storybook component
123 */
124 text?: string;
125 /**
126 * Displays info inline vs click button to view
127 * @default false
128 */
129 inline: boolean,
130 /**
131 * Toggles display of header with component name and description
132 * @default true
133 */
134 header: boolean,
135 /**
136 * Displays the source of story Component
137 * @default true
138 */
139 source: boolean,
140 /**
141 * Components used in story
142 * Displays Prop Tables with these components
143 * @default []
144 */
145 propTables: Array<React.ComponentType>,
146 /**
147 * Exclude Components from being shown in Prop Tables section
148 * Accepts an array of component classes or functions
149 * @default []
150 */
151 propTablesExclude: Array<React.ComponentType>,
152 /**
153 * Overrides styles of addon. The object should follow this shape:
154 * https://github.com/storybookjs/storybook/blob/master/addons/info/src/components/Story.js#L19.
155 * This prop can also accept a function which has the default stylesheet passed as an argument
156 */
157 styles: Object | Function,
158 /**
159 * Overrides components used to display markdown
160 * @default {}
161 */
162 components: { [key: string]: React.ComponentType },
163 /**
164 * Max props to display per line in source code
165 * @default 3
166 */
167 maxPropsIntoLine: number,
168 /**
169 * Displays the first 10 characters of the prop name
170 * @default 3
171 */
172 maxPropObjectKeys: number,
173 /**
174 * Displays the first 10 items in the default prop array
175 * @default 3
176 */
177 maxPropArrayLength: number,
178 /**
179 * Displays the first 100 characters in the default prop string
180 * @default 50
181 */
182 maxPropStringLength: number,
183 /**
184 * Override the component used to render the props table
185 * @default PropTable
186 */
187 TableComponent: React.ComponentType,
188 /**
189 * Will exclude any respective properties whose name is included in array
190 * @default []
191 */
192 excludedPropTypes: Array<string>,
193}
194```
195
196### Rendering a Custom Table
197
198The `TableComponent` option allows you to define how the prop table should be rendered. Your component will be rendered with the following props.
199
200```js
201 {
202 propDefinitions: Array<{
203 property: string, // The name of the prop
204 propType: Object | string, // The prop type. TODO: info about what this object is...
205 required: boolean, // True if the prop is required
206 description: string, // The description of the prop
207 defaultValue: any // The default value of the prop
208 }>
209 }
210```
211
212Example:
213
214```js
215// button.js
216// @flow
217import React from 'react';
218
219const paddingStyles = {
220 small: '4px 8px',
221 medium: '8px 16px',
222};
223
224const Button = ({
225 size,
226 ...rest
227}: {
228 /** The size of the button */
229 size: 'small' | 'medium',
230}) => {
231 const style = {
232 padding: paddingStyles[size] || '',
233 };
234 return <button style={style} {...rest} />;
235};
236Button.defaultProps = {
237 size: 'medium',
238};
239
240export default Button;
241```
242
243```js
244// stories.js
245import React from 'react';
246
247import { storiesOf } from '@storybook/react';
248import Button from './button';
249
250export default {
251 title: 'Button',
252 component: Button,
253 parameters: {
254 info: TableComponent,
255 },
256};
257
258const Red = props => <span style={{ color: 'red' }} {...props} />;
259
260const TableComponent = ({ propDefinitions }) => {
261 const props = propDefinitions.map(
262 ({ property, propType, required, description, defaultValue }) => {
263 return (
264 <tr key={property}>
265 <td>
266 {property}
267 {required ? <Red>*</Red> : null}
268 </td>
269 <td>{propType.name}</td>
270 <td>{defaultValue}</td>
271 <td>{description}</td>
272 </tr>
273 );
274 }
275 );
276
277 return (
278 <table>
279 <thead>
280 <tr>
281 <th>name</th>
282 <th>type</th>
283 <th>default</th>
284 <th>description</th>
285 </tr>
286 </thead>
287 <tbody>{props}</tbody>
288 </table>
289 );
290};
291
292export const defaultView = () => <Button />;
293```
294
295### React Docgen Integration
296
297React Docgen is included as part of the @storybook/react package through the use of `babel-plugin-react-docgen` during babel compile time.
298When rendering a story with a React component commented in this supported format, the Addon Info description will render the comments above the component declaration and the prop table will display the prop's comment in the description column.
299
300```js
301import React from 'react';
302import PropTypes from 'prop-types';
303
304/** Button component description */
305const DocgenButton = ({ disabled, label, style, onClick }) => (
306 <button disabled={disabled} style={style} onClick={onClick}>
307 {label}
308 </button>
309);
310
311DocgenButton.defaultProps = {
312 disabled: false,
313 onClick: () => {},
314 style: {},
315};
316
317DocgenButton.propTypes = {
318 /** Boolean indicating whether the button should render as disabled */
319 disabled: PropTypes.bool,
320 /** button label. */
321 label: PropTypes.string.isRequired,
322 /** onClick handler */
323 onClick: PropTypes.func,
324 /** component styles */
325 style: PropTypes.shape,
326};
327
328export default DocgenButton;
329```
330
331Comments above flow types are also supported. Storybook Info Addon should now render all the correct types for your component if the PropTypes are in the same file as the React component.
332
333## The FAQ
334
335**Components lose their names on static build**
336
337Component names also get minified with other javascript code when building for production.
338When creating components, set the `displayName` static property to show the correct component name on static builds.