Controls panel for dynamic component interaction
Storybook Controls provides a graphical UI to interact with a component's arguments dynamically without coding. Use the Controls panel to edit story inputs and see results in real-time.
essentials/controls
36 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 require stories written with args
To use Controls, you must write your stories using args. Storybook will automatically generate UI controls based on your args and inferred component metadata.
Default control type matchers for color and date
Controls can be automatically inferred from arg names using regex. By default, the color control matches /(background|color)$/i and the date control matches /Date$/. These defaults are set in .storybook/preview.ts|tsx by the CLI.
argTypes for custom control configuration
ArgTypes encode basic metadata for args such as name, description, and defaultValue. They can contain arbitrary annotations to customize controls. Place argType annotations on the meta (or default export) of your story file to configure individual controls.
Controls matchers configuration in preview file
To define custom control type matchers, use the matchers property in the controls parameter in .storybook/preview.ts|tsx. This allows you to specify regex patterns for auto-detecting control types beyond the defaults.
Available control types for each data type
Controls support: boolean (boolean toggle), number (numeric input with min/max/step), range (range slider), object (JSON editor), array (JSON editor), file (file input returning URLs), enum (radio, inline-radio, check, inline-check, select, multi-select), and string (text, color picker, datepicker).
Boolean control example
argTypes: { active: { control: 'boolean' } } provides a toggle for switching between possible states.
Number control with range configuration
argTypes: { even: { control: { type: 'number', min: 1, max: 30, step: 2 } } } provides a numeric input with specified range and step.
Range slider control example
argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } } } provides a range slider component.
Object control example
argTypes: { user: { control: 'object' } } provides a JSON-based editor component with raw mode editing.
File control example
argTypes: { avatar: { control: { type: 'file', accept: '.png' } } } provides a file input component that returns an array of URLs.
Radio control example
argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] } } provides radio buttons based on available options.
Inline radio control example
argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] } } provides inlined radio buttons.
Inline checkbox control example
argTypes: { contact: { control: 'inline-check', options: ['email', 'phone', 'mail'] } } provides inlined checkbox components.
Select control example
argTypes: { age: { control: 'select', options: [20, 30, 40, 50] } } provides a dropdown list for single value selection.
Multi-select control example
argTypes: { countries: { control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] } } provides a dropdown allowing multiple selected values.
Text control example
argTypes: { label: { control: 'text' } } provides a freeform text input.
Color control example with presets
argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green'] } } } provides a color picker component with color presets.
Date control example
argTypes: { startDate: { control: 'date' } } provides a datepicker component. Note: the date control converts the date into a UNIX timestamp when the value changes.
Mapping primitive values to complex values
Use the mapping property to map primitives to complex values before rendering, avoiding URL serialization issues. Define control.labels to configure custom labels for checkbox, radio, or select inputs. Both mapping and control.labels do not need to be exhaustive.
Create and edit stories from Controls panel
You can create new stories or edit existing stories directly from the Controls panel by adjusting control values and saving changes. This feature can be disabled by setting disableSaveFromUI to true in parameters.controls.
Enable expanded Controls documentation
Set expanded to true in parameters.controls in .storybook/preview.ts|tsx to show full property documentation alongside controls, including descriptions and default values.
Configure preset color swatches
Specify presetColors in parameters.controls as an array of CSS color strings or objects with color and optional title properties. These appear as swatches in the color picker.
Filter controls with include and exclude
Use optional include and exclude fields in parameters.controls to display only specific controls. Define them as an array of strings or a regular expression.
Sort controls in the panel
Use the sort parameter in parameters.controls with values 'none' (default, unsorted), 'alpha' (alphabetically by arg name), or 'requiredFirst' (alphabetically with required args first).
Disable controls for individual properties
Set control to false in argTypes for a specific property to turn off controls for that property. To keep property documentation without a control, use control: false with the property still listed in argTypes.
Conditional controls with if operator
Use the if property in argTypes to conditionally exclude controls based on other control values. The query object must contain either arg or global target and may contain one operator: truthy (default if none provided), exists, eq, or neq.
Conditional controls query structure
Query objects for conditional controls contain: field 'arg' (string, the ID of the arg to test) or 'global' (string, the ID of the global to test). Operators: truthy (boolean, is target truthy), exists (boolean, is target defined), eq (any, is target equal to value), neq (any, is target NOT equal to value).
Controls parameters API reference
Controls parameters under the controls namespace: disable (boolean), exclude (string[] | RegExp), expanded (boolean), include (string[] | RegExp), presetColors ((string | { color: string; title?: string })[]), sort ('none' | 'alpha' | 'requiredFirst', default 'none'), disableSaveFromUI (boolean, default false).
Component annotation for automatic control inference
Add a component annotation to the meta (default export) of your story file to enable automatic control inference from the component definition. This works with react-docgen (React), vue-docgen-api (Vue), and framework-specific generators.
Framework-specific automatic control generation
React and Vue automatically choose controls based on arg initial values. Angular uses Compodoc, Ember uses ember-cli-storybook adapter, and Web Components uses custom-elements.json. Other frameworks (HTML, Svelte, Preact, Qwik, Solid) rely on framework-provided metadata or manual argTypes definition.
Complex values and URL serialization limitation
Non-primitive arg values cannot be represented in the URL, losing the ability to share and deep link to such states. Complex values like JSX cannot be synchronized between the Controls panel and the preview. Use primitive values with a custom render function or mapping to convert them before rendering.
Date control UNIX timestamp conversion
The date control converts the selected date into a UNIX timestamp when the value changes. This is a known limitation. To represent the actual date, update the story implementation to convert the UNIX timestamp to a date object.
Controls not updating in auto-generated documentation
If inline rendering is disabled for stories via the inline configuration option, associated controls will not update the story within the documentation page. This is a known limitation to be addressed in a future release.
Controls provides graphical UI for component arguments
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 migrated from addon-controls to core
The Controls functionality was migrated from the @storybook/addon-controls package into the core Storybook package as part of an effort to consolidate core functionality.