Created by Adam Davarel Nostradatito from Notion
Storybook is a great tool for documenting a component library, as it allows you to visually develop and test individual components in isolation. Storybook is an essential tool for developers building scalable and reusable component libraries, as it improves the efficiency and quality of UI development. Here some advantage using Storybook for your projects :
Here’s how you can set it up to document your component library:
Install Storybook: If you haven't installed Storybook yet, you can do so by running the following command inside your project directory ( using npm ):
npx storybook@latest initCreate a Story for Each Component: For each component in your library, create a corresponding story file (with .stories.js or .stories.jsx extensions). These stories will showcase the different states and variations of your component. In this example, we are using Button component to create a stories. As you can see, there some stories is created. A story represent of 1 state of component.
// src/components/atoms/Button/Button.stories.jsx
import Button from '.';
export default {
component: Button,
argTypes: {
className: { control: 'text' },
},
tags: ['autodocs'],
parameters: {
layout: 'centered',
backgrounds: {
default: 'dark',
},
},
};
export const Primary = {
args: {
children: 'Primary Button',
variant: 'primary',
},
};
export const Secondary = {
args: {
children: 'Secondary Button',
variant: 'secondary',
},
};
export const LoadingState = {
args: {
children: 'Loading Button',
variant: 'primary',
isLoading: true,
},
};
export const DisabledState = {
args: {
children: 'Disabled Button',
variant: 'primary',
isDisabled: true,
},
};
Stories configuration such a args, parameters and etc can be defined at the story, component and global level. It is a JSON serializable object composed of string keys with matching valid value types that can be passed into a component for your framework, just like you passing a props when using the component on your project. Here’s how to define at each level :
Story Level
These args will only apply to the story for which they are attached
// src/components/atoms/Button/Button.stories.jsx
import { Button } from './Button';
export default {
component: Button,
};
export const Primary = {
args: {
label: 'Primary Button',
primary: true,
},
};
Component Level
This way will apply to all the component's stories unless you overwrite them.
// src/components/atoms/Button/Button.stories.jsx
import { Button } from './Button';
export default {
component: Button,
args: {
//👇 Now all Button stories will be primary.
primary: true,
},
};
export const Primary = {
args: {
label: 'Primary Button',
},
};
Global Level
This way will apply to every component's stories unless you overwrite them. To do so, define the args property in the default export of preview.js:
// .storybook/preview.js
export default {
// The default value of the theme arg for all stories
args: { theme: 'light' },
};
argsA story is a component with a set of arguments that define how the component should render. “Args” are Storybook’s mechanism for defining those arguments in a single JavaScript object. Args can be used to dynamically change props, slots, styles, inputs, etc. Read more the args documentation.
parametersParameters are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.
Storybook only accepts a few parameters directly, here are some parameters that most likely we used on our projects.
autodocsStorybook Autodocs is a powerful tool that can help you quickly generate comprehensive documentation for your UI components. By leveraging Autodocs, you're transforming your stories into living documentation which can be further extended with MDX and Doc Blocks to provide a clear and concise understanding of your components' functionality.
There is 2 ways to enable autodocs for our Storybook, component based and globally. But let’s use the component based :
Globally
// .storybook/preview.js
export default {
// ...rest of preview
//👇 Enables auto-generated documentation for all stories
tags: ['autodocs'],
};
Component base
// src/component/src/Button/Button.stories.jsx
import { Button } from './Button';
export default {
component: Button,
//👇 Enables auto-generated documentation for this component and includes all stories in this file
tags: ['autodocs'],
};
also we can disable autodocs for particular component or story. This is how we do it:
// src/component/src/Button/Button.stories.jsx
import { Button } from './Button';
export default {
component: Button,
//👇 Enables auto-generated documentation for this component and includes all stories in this file
tags: ['!autodocs'],
};
export const UndocumentedStory = {
// 👇 Removes this story from auto-generated documentation
tags: ['!autodocs'],
};
<aside> 💡