Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.

Controls does not require any modification to your components. Stories for controls are:

  • Convenient. Auto-generate controls based on React/Vue/Angular/etc. components.
  • Portable. Reuse your interactive stories in documentation, tests, and even in designs.
  • Rich. Customize the controls and interactive data to suit your exact needs.

To use the Controls addon, you need to write your stories using args. Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using argTypes, see below.

๐Ÿ’ก If you have stories in the older pre-Storybook 6 style, check the args & controls migration guide to learn how to convert your existing stories for args.

Choosing the control type

By default, Storybook will choose a control for each arg based on the initial value of the arg. It works well with certain types of args, such as boolean values or free-text strings, but in other cases, you want a more restricted control.

For instance, suppose you have a variant arg on your story that should be primary or secondary:

By default, Storybook will render a free text input for the variant arg:

Essential addon Controls using a string

It works as long as you type a valid string into the auto-generated text control. Still, it's not the best UI for our scenario, given that the component only accepts primary or secondary as variants. Letโ€™s replace it with Storybookโ€™s radio component.

We can specify which controls get used by declaring a custom argType for the variant property. ArgTypes encode basic metadata for args, such as name, description, defaultValue for an arg. These get automatically filled in by Storybook Docs.

ArgTypes can also contain arbitrary annotations, which the user can override. Since variant is a property of the component, let's put that annotation on the default export.

This replaces the input with a radio group for a more intuitive experience.

Essential Control addon with a radio group

Custom control type matchers

For a few types, Controls will automatically infer them by using regex. You can change the matchers for a regex that suits you better.

Data typeDefault regexDescription
color/(background\|color)$/iWill display a color picker UI for the args that match it
date/Date$/Will display a date picker UI for the args that match it

To do so, use the matchers property in the controls parameter:

Fully custom args

Up until now, we only used auto-generated controls based on the component we're writing stories for. If we are writing complex stories, we may want to add controls for args that arenโ€™t part of the component.

By default, Storybook will add controls for all args that:

Using argTypes, you can change the display and behavior of each control.

Dealing with complex values

You'll notice that when dealing with non-primitive values, you'll run into some limitations. The most obvious issue is that not every value can be represented as part of the args param in the URL, losing the ability to share and deeplink to such a state. Beyond that, complex values such as JSX cannot be synchronized between the manager (e.g., Controls addon) and the preview (your story).

One way to deal with this is to use primitive values (e.g., strings) as arg values and add a custom render function to convert these values to their complex counterpart before rendering. It isn't the nicest way to do it (see below), but certainly the most flexible.

Unless you need the flexibility of a function, an easier way to map primitives to complex values before rendering is to define a mapping. Additionally, you can specify control.labels to configure custom labels for your checkbox, radio, or select input.

Note that both mapping and control.labels don't have to be exhaustive. If the currently selected option is not listed, it's used verbatim.


The Controls addon can be configured in two ways:

  • Individual controls can be configured via control annotations.
  • The addon's appearance can be configured via parameters.


As shown above, you can configure individual controls with the โ€œcontrol" annotation in the argTypes field of either a component or story.

Here is the full list of available controls you can use:

Data TypeControl TypeDescriptionOptions
booleanbooleancheckbox input-
numbernumbera numeric text box inputmin, max, step
rangea range slider inputmin, max, step
objectobjectjson editor text input-
arrayobjectjson editor text input-
filea file input that gives you a array of urlsaccept
enumradioradio buttons input-
inline-radioinline radio buttons input-
checkmulti-select checkbox input-
inline-checkmulti-select inline checkbox input-
selectselect dropdown input-
multi-selectmulti-select dropdown input-
stringtextsimple text input-
colorcolor picker input that assumes strings are color valuespresetColors
datedate picker input-

If you need to customize a control for a number data type in your story, you can do it like so:

๐Ÿ’ก If you don't provide a specific one, it defaults to the number control type.


Controls supports the following configuration parameters, either globally or on a per-story basis:

Show full documentation for each property

Since Controls is built on the same engine as Storybook Docs, it can also show property documentation alongside your controls using the expanded parameter (defaults to false). This means you embed a complete ArgsTable doc block in the controls panel. The description and default value rendering can be customized in the same way as the doc block.

To enable expanded mode globally, add the following to .storybook/preview.js:

And here's what the resulting UI looks like:

Controls addon expanded

Specify initial preset color swatches

For color controls, you can specify an array of presetColors, either on the control in argTypes, or as a parameter under the controls namespace:

Color presets can be defined as an object with color and title or a simple CSS color string. These will then be available as swatches in the color picker. When you hover over the color swatch, you'll be able to see its title. If none is specified, it will default to the nearest CSS color name instead.

Disable controls for specific properties

Aside from the features already documented here, Controls can also be disabled for individual properties.

Suppose you want to disable Controls for a property called foo in a component's story. The following example illustrates how:

Resulting in the following change in Storybook UI:

The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation, but without a control. The following example illustrates how:

๐Ÿ’ก As with other Storybook properties, such as decorators, you can apply the same pattern at a story level for more granular cases.

Hide NoControls warning

If you don't plan to handle the control args inside your Story, you can remove the warning with:

Filtering controls

In specific cases, you may require to display only a limited number of controls in the controls panel, or all of them except a particular set.

To make this possible, you can use optional include and exclude configuration fields in the controls parameter, which you can define as an array of strings, or as a regular expression.

Consider the following story snippets:

Sorting controls

By default, controls are unsorted and use whatever order the args data is processed in (none). Additionally, you can sort them alphabetically by the arg's name (alpha) or with the required args first (requiredFirst).

Consider the following snippet to force required args first:

Add Storybook to your project in less than a minute to build components faster and easier.
Learn Storybook with in-depth tutorials that teaches Storybook best practices. Follow along with code samples.
The MIT License (MIT). Website design by @domyen and the awesome Storybook community.
Get news, free tutorials, and Storybook tips emailed to you.

Maintained by
Continuous integration by
Hosting by