This is a post about Storybook and conventions. It is based on my experience using Storybook over several years and from the experiences of other developers. The best practices I define here aren’t silver bullets that will fix and improve every project. They’re a baseline of ideas and conventions that I think are worth trying. Hopefully, they can help you and your team have a better developer experience and ultimately deliver better software to the world.

I assum you know what Storybook is and that you have some experience with it. The ideas here can be applied to apps of any size and are not particular to any specific framework (e.g. React or Vue), but I wrote them with a large app in mind with a large team and multiple contributors.

1. One Storybook File Per Component

The story file should have:

  • one _Default _story
  • a _Playground _story
  • and other stories that reflect a specific state or API of the component.

The default story displays the component with only its required props defined. This creates a visual baseline representation for everyone. So, when people think about a specific component, ideally they will remember what’s reproduced by the default story.

The playground story is used to help consumers of the component to try different combinations of props and see how the component responds. This can be implemented in Storybook version 5 and bellow using the knobs add-on. You provide knobs for all props of the component:

import React from "react";
import {storiesOf} from "@storybook/react";
import { withKnobs, text } from '@storybook/addon-knobs';
import Button from ".";

const storiesOf("Button", module).
    add("Default", () => {
        return <Button type="button" text="Click me" />
    add("Playground", () => {
        const typePropLabel = 'type';
        const typePropOptions = {
            submit: 'submit',
            input: 'input'
        const typePropDefaultValue = typePropOptions.submit;

        const textPropLabel = "text";
        const textDefaultValue = "Click me";

        return (
            <Button type={select(typePropLabel, typePropOptions, typePropDefaultValue)} text={text(textPropLabel, textDefaultValue)} />

For the latest version of Storybook (version 6), the playground story can be written using the new Args feature. It looks something like this:

import React from "react";
import Button from ".";

// Args Setup
const Template = (args) => <Button {...args} />;

export const Playground = Template.bind({});

const buttonTypes = {
  SUBMIT: 'submit',
  INPUT: 'input'

Playground.args = {
  type: buttonTypes.INPUT,
  text: "Primary",

Playground.argTypes = {
  type: {
    control: {
      type: "select",
      options: [buttonTypes.INPUT, buttonTypes.SUBMIT]
  text: {
    control: "text"

export const DefaultStory = () => <Button type="button" text="Click me" />;

DefaultStory.storyName = "Default";

export default {
  title: "Components/Button",
  component: DefaultStory,

#storybook #programming #javascript #reactjs #react #react native

10 Storybook Best Practices
23.80 GEEK