controls & argtypes

25 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Controls basic purpose

Storybook Controls provides a graphical UI to interact with a component's arguments dynamically without needing to code. The Controls panel lets you edit story inputs and see results in real-time, making it useful for exploring components and testing different states.

Controls require args to function

To use Controls, you must write your stories using args. Storybook will automatically generate UI controls based on your args and what it can infer about your component. Controls can be further configured using argTypes.

Custom control type matchers regex defaults

Controls can automatically be inferred from arg names using regex. Default matchers are: color control uses /(background|color)$/i to display a color picker UI; date control uses /Date$/ to display a date picker UI.

Custom control type matchers configuration

To define custom regex patterns for control matchers, use the matchers property in the controls parameter in .storybook/preview.ts|tsx. This allows matching arg names to specific control types beyond the defaults.

All available control types by data type

Controls table: boolean → boolean (toggle); number → number (numeric input with min/max/step) or range (range slider); object → object (JSON editor); array → object (JSON editor) or file (file input returning URL array); enum → radio, inline-radio, check, inline-check, select, multi-select; string → text (freeform input), color (color picker), date (datepicker).

Mapping primitive values to complex values

When working with complex values, use a mapping property to convert primitive values to their complex counterpart before rendering. You can also use control.labels to configure custom labels for checkbox, radio, or select inputs. Mapping and control.labels do not need to be exhaustive; unmapped values are used verbatim.

Controls parameters API reference

Controls parameters in .storybook/preview.ts|tsx: disable (boolean, disable feature); exclude (string[] | RegExp, exclude properties); expanded (boolean, show full documentation); include (string[] | RegExp, include properties); presetColors ((string | { color: string; title?: string })[], color swatches); sort ('none' | 'alpha' | 'requiredFirst', default 'none'); disableSaveFromUI (boolean, default false, prevent creating/editing stories from UI).

Conditional controls with if operator

Controls supports conditional exclusion using the if property with a query object. The query object must contain either an arg or global target (string, the ID to test). It may contain one operator: truthy (boolean), exists (boolean), eq (any value), or neq (any value). If no operator is provided, it defaults to { truthy: true }.

Disable controls for specific properties

To disable controls for individual properties, set the control property to false in the argTypes for that property. To show property documentation without a control, set control to false while keeping the prop documented.

Sorting controls

Controls can be sorted using the sort parameter with values: none (default, unsorted), alpha (alphabetically by name), or requiredFirst (alphabetically with required args first).

Filtering controls with include/exclude

Use the include and exclude parameters in the controls configuration to control which properties appear in the Controls panel. Both accept either an array of strings or a regular expression to match property names.

Expanded controls mode

Enable expanded mode in Controls to show full property documentation including description and default value alongside controls. Set the expanded parameter to true in .storybook/preview.ts|tsx or per-story in parameters.controls.

Create stories from Controls panel

You can create new stories directly from the Controls panel by adjusting control values and saving them as a new story. For components without stories, React allows clicking the ➕ button in the sidebar to search for the component and have a basic story created.

Edit stories from Controls panel

You can edit existing stories by updating control values in the Controls panel and saving the changes. The story file code will be updated automatically.

Disable story creation/editing from Controls

To prevent creating or editing stories from the Controls panel, set disableSaveFromUI to true in the parameters.controls parameter in .storybook/preview.ts|tsx.

React auto-generates controls with react-docgen

For React, add the component annotation to the meta (default export) of your story file. Storybook will use react-docgen, a documentation generator for React components with TypeScript support, to infer controls and auto-generate matching argTypes.

Vue auto-generates controls with vue-docgen-api

For Vue, add the component annotation to the meta (default export) of your story file. Storybook will use vue-docgen-api to infer controls and auto-generate matching argTypes, with first-class support for props, events, and slots.

Angular auto-generates controls with Compodoc

For @storybook/angular, Storybook uses Compodoc to extract component metadata including inputs, outputs, properties, methods, and view/content children. Set it up by installing Compodoc, configuring angular.json, and updating .storybook/preview.ts|tsx to import Compodoc metadata.

Angular-Vite auto-generates controls from TypeScript

For @storybook/angular-vite, Storybook reads components directly from TypeScript sources on the server and infers inputs, outputs, properties, and methods with no setup required. See framework documentation for using Compodoc instead and known limitations.

Ember auto-generates controls with ember-cli-storybook adapter

For Ember, Storybook infers argTypes based on metadata from @storybook/ember-cli-storybook adapter. Update ember-cli-build.js to include the adapter, restart to generate storybook-docgen/index.json, and configure .storybook/preview.js to import it.

Web Components auto-generates controls from custom-elements.json

For Web Components, you can optionally generate a custom-elements.json file using @custom-elements-manifest/analyzer and configure it in .storybook/preview.ts|tsx to enable controls inference.

HTML/Svelte/Preact/Qwik/Solid auto-generate controls from initial values

For HTML, Svelte, Preact, Qwik, and Solid, Storybook chooses a control for each arg based on its initial value. Add the component annotation to meta to infer controls and auto-generate argTypes. If your framework doesn't support this, define argTypes manually.

Date control limitation converts to UNIX timestamp

The date control converts the date into a UNIX timestamp when the value changes. This is a known limitation that will be fixed in a future release. To represent the actual date object, update the story implementation to convert the value.

Complex values and URL sharing limitation

Complex values like JSX cannot be fully represented in the args param in the URL, losing the ability to share and deep link to such states. Complex values also cannot be synchronized between the Controls panel and the preview.

Numeric controls default to number type

Numeric data types default to a number control unless additional configuration is provided.

Give your agent this brain