🎮 Storybook Controls

This article continues from “Storybook Doc Blocks customization cheatsheet” as a deep view on the Storybook Controls feature in a condensed summary accompanied by some concise examples.

🤔 The purpose and scope of Controls

Controls are the component documentation interface with a dynamic table of arg types. It gives us the chance to interact with the component properties dynamically and live.

To be able to tweak controls we need to use args at story level, component level or global level, so Storybook is able to generate UI controls based on them.

args: {
  variant: 'primary',
  label: 'Button'
  disabled: false,
  loading: false,
}

Moreover, controls can be further configured by using argTypes.

👩‍🏫 Examples with args and argTypes

We can define our component variant custom property like this on the story definition args:

export const Primary: Story = {  
  args: {    
    variant: 'primary',  
  },
};

On Storybook, the control will be rendered as a text input where we can write any text:

If we prefer to have a select with some predefined options, we would define this as argTypes on the meta definition:

const meta: Meta<typeof Button> = {  
  component: Button,  
    argTypes: {    
      variant: {      
	options: ['primary', 'secondary'],      
	control: { type: 'select' },    
     },  
   },
};

On Storybook, the text input will be replaced by the select dropdown:

Storybook has a bunch of argTypes such as color picker and radio buttons options to customize Controls.

On this link, you can find the complete list.

Take into account that argTypes defined at the meta level will affect all applicable stories of the file.

If we want the argTypes to affect a concrete story, we would define the argTypes on the desired story definition as you will find on “Basic example 5” 👇

🤓 Basic example 1: Custom action for event

On the Button component we can change onClick by handleClick and on Button.stories we would add this:

argTypes: { handleClick: { action: "myHandleClick" } },

It passes all the event information to “myHandleClick”.

💡 We can check all the information sent by the event on the Actions tab from Storybook, so each time we click the component, on the Action tab appears the log of the event.

🤓 Basic example 2: Change default input text to colour picker to select a color

argTypes: { backgroundColor: control: “color” }}

🤓 Basic example 3: Change the default control to a dropdown

argTypes: { size: control: “select” }}

🤓 Basic example 4: Remove the ability to edit a property control such as the number of rows of a table

argTypes: { rows: { control: { disable: true }, }}

🤓 Basic example 5: argTypes control for a single story

We want to pass just some colours to be able to tweak as well as the type of control to show them on a specific story:

MyStory.argTypes = { 
  backgroundColor: { 
    control: “inline-radio”, 
    options: [“red”, “blue”],
  }
}

🔗 All the available options for Controls API

🤓 Basic example 6: Add description to controls properties

We can also add a custom description to each of the component properties on the argTypes of the meta definition:

const meta: Meta<typeof Button> = {  
  component: Button,  
  argTypes: {
    label: {
      description: 'Button text content',
    },
    variant: {
      description: 'Button variant used from a list of values',
    },
    disabled: {
      description: 'Is the button in disabled state?',
    },
    loading: {
      description: 'Is the button in loading state?',
    },
  },
};

Besides description, Storybook offers some variety of argTypes to use, such as conditionals and options.

On this link, you can find the complete list.

Sources

Args * Storybook docs

Controls * Storybook docs

ArgTypes * Storybook docs