Storybook overview

I. What is storybook

Storybook is an open source tool for building UI components and pages in isolation. This means that you can create something similar to a UI library, deploy it and import it to use in different projects.

I think it’s a great tool for company that has their own products, where they have similar design system across their apps. It is good because storybook not only help the process of creating component easier but it also help to manage and document the component.

But even if you just want to create a reusable component within your project, it’s worth the try because to my own experience, using an existing UI library isn’t ideal, the component layout adjustment is not always easy and most of the time, we install the whole library but use only a few components.

II. Overview

1. Workshop

3 main parts of a component created with Storybook

Normally, if you just create a component, you’ll only need a .js and a stylesheet. Then, to see if how the component look like, you need to import it in your page to see changes.
However, with Storybook, after installing and run, a page (i’ll call it workshop) will run locally on a certain port which will help you see how your component looks like and all the changes while you’re developing it. That’s what the .stories.js does.

Storybook workshop

A *.stories.js file defines all the stories for a component. Each story has a corresponding sidebar item. When you click on a story, it renders in the Canvas an isolated preview iframe.

① The Button and Header from the side menu below are the component that were created as an example from strorybook, these are called stories.
② Inside each component are variants , just like you see on Material UI or Bootstrap.
③ is how your component looks like.

And, the Controls and Actions tabs are for you to experiment your component. The properies in Controls section can be adjusted as you wish.

2. Inside the main component

The main component is like any other reusable component that you know.
It receive the props so that layout and actions of the component would be in correspondence to them.

Button.jsx

As mentioned earlier, the Controls and Actions tab from the “workshop” can be adjusted. Check below, FYR, all the propTypes that were included in the main component will appear in the Controlstab. These propTypes are neccessary for controlling the props that was tranfer from parent component because we don’t want to break anything.

The “hoverColor” prop was added by me to demontrate how this works

Last part is default value for those props, if nothing was passed to this Button component, these values will be used.

3. Inside the story

The story is the file that Storybook uses to render your component to the “workshop” page.

In “export default” object:
- The title is the directory that you can see on the “workshop” page. This is especially helpful if you’re creating a whole design system to keep everything in order, and everyone in the team no matter if they’re newcomers or not can easily check how many components existing, what are the variant they can use and so on.

Sidebar directory follow title pattern

- The component is just the component that you want Storybook to render on “workshop” page
- The argTypes are something that you don’t need to have, because it will refer to the propTypes that you have declare in the main component. This argTypes are for changing the control type of the props on “workshop” page.
As you can see, button size was defined as one of the specific options in Button.jsx propTypes, so on the “workshop” page, it appears to be radio button and you don’t have to define it again in the argTypes in Button.stories.js file.

size: PropTypes.oneOf([‘small’, ‘medium’, ‘large’]),

If you want to change the way it appears on “workshop” page, change control type of the argTypes, like this. Now you can see, the size display as a select dropdown.

argTypes: {
backgroundColor: { control: 'color' },
size: { control: 'select'}
},

Last but not least in the story file is the variant.
This is also not obligatory, but one of the main reason to use storybook is to help document all the component you created, which is easy for someone else in your team to read and understand.
Variant is a copy of the main component with some predefined arguments. Once you declared, it’ll show up on the sidebar.

Variants

4. Writting documents using .mdx

If you want to create a document for you component, you can use .mdx file, the file allows you to write markdown syntax together with you component in the same file.
Storybook has dedicated a whole page for this, you can check it out.
https://storybook.js.org/docs/react/writing-docs/mdx

III. Get started

It’s not difficult to set up basic storybook to your project, just install it and you’re good to go, unless you’re want other advanced setup.

npx -p @storybook/cli sb init

This CLI will detect project and does installation on it’s own.

Here’s what the step looks like:

Step 1: Install Storybook on existing project.
Step 2: Delete uneccessary components and stories from storybook example or keep it FYR.
Step 3: Create you component.
Step 4: Create story to render your component on “workshop” page.
Step 5: Adjust your component and see the change on “workshop” page.

IV. Conclusion

I didn’t want to create a tutorial on how to create somehting with storybook because there’re plenty of them and the storybook’s document itself is very clear and well written. The point is to understand what storybook does and why it’s worth the try. I hope this helps you get the main idea of Storybook so you can decide whether to use it or not.