ArgTypes
ArgTypes specify the behavior of args. By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., description).
You can also use argTypes to “annotate” args with information used by addons that make use of those args. For instance, to instruct the controls addon to render a color picker, you could specify the 'color'
control type.
The most concrete realization of argTypes is the ArgTypes
doc block (Controls
is similar). Each row in the table corresponds to a single argType and the current value of that arg.
Automatic argType inference
If you are using the Storybook docs addon (installed by default as part of essentials), then Storybook will infer a set of argTypes for each story based on the component
specified in the default export of the CSF file.
To do so, Storybook uses various static analysis tools depending on your framework.
Framework | Static analysis tool |
---|---|
React | react-docgen (default) or react-docgen-typescript |
Vue | vue-docgen-api |
Angular | compodoc |
WebComponents | custom-element.json |
Ember | YUI doc |
The data structure of argTypes
is designed to match the output of the these tools. Properties specified manually will override what is inferred.
Manually specifying argTypes
For most Storybook projects, argTypes are automatically inferred from your components. Any argTypes specified manually will override the inferred values.
ArgTypes are most often specified at the meta (component) level, in the default export of the CSF file:
They can apply to all stories when specified at the project (global) level, in the preview.js|ts
configuration file:
Or they can apply only to a specific story:
argTypes
Type:
You configure argTypes using an object with keys matching the name of args. The value of each key is an object with the following properties:
control
Type:
Default:
Specify the behavior of the controls addon for the arg. If you specify a string, it's used as the type
of the control. If you specify an object, you can provide additional configuration. Specifying false
will prevent the control from rendering.
control.type
Type: ControlType | null
Default: Inferred; 'select'
, if options
are specified; falling back to 'object'
Specifies the type of control used to change the arg value with the controls addon. Here are the available types, ControlType
, grouped by the type of data they handle:
Data type | ControlType | Description |
---|---|---|
array | 'object' | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.{ control: 'object' } |
boolean | 'boolean' | Provides a toggle for switching between possible states.{ control: 'boolean' } |
enum | 'check' | Provides a set of stacked checkboxes for selecting multiple options.{ control: 'check', options: ['email', 'phone', 'mail'] } |
'inline-check' | Provides a set of inlined checkboxes for selecting multiple options.{ control: 'inline-check', options: ['email', 'phone', 'mail'] } | |
'radio' | Provides a set of stacked radio buttons based on the available options.{ control: 'radio', options: ['email', 'phone', 'mail'] } | |
'inline-radio' | Provides a set of inlined radio buttons based on the available options.{ control: 'inline-radio', options: ['email', 'phone', 'mail'] } | |
'select' | Provides a select to choose a single value from the options.{ control: 'select', options: [20, 30, 40, 50] } | |
'multi-select' | Provides a select to choose multiple values from the options.{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] } | |
number | 'number' | Provides a numeric input to include the range of all possible values.{ control: { type: 'number', min:1, max:30, step: 2 } } |
'range' | Provides a range slider to include all possible values.{ control: { type: 'range', min: 1, max: 30, step: 3 } } | |
object | 'file' | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.{ control: { type: 'file', accept: '.png' } } |
'object' | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.{ control: 'object' } | |
string | 'color' | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.{ control: { type: 'color', presetColors: ['red', 'green']} } |
'date' | Provides a datepicker to choose a date.{ control: 'date' } | |
'text' | Provides a freeform text input.{ control: 'text' } |
The date
control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object.
control.accept
Type: string
When type
is 'file'
, you can specify the file types that are accepted. The value should be a string of comma-separated MIME types.
control.labels
Type: { [option: string]: string }
Map options
to labels. labels
doesn't have to be exhaustive. If an option is not in the object's keys, it's used verbatim.
control.max
Type: number
When type
is 'number'
or 'range'
, sets the maximum allowed value.
control.min
Type: number
When type
is 'number'
or 'range'
, sets the minimum allowed value.
control.presetColors
Type: string[]
When type
is 'color'
, defines the set of colors that are available in addition to the general color picker. The values in the array should be valid CSS color values.
control.step
Type: number
When type
is 'number'
or 'range'
, sets the granularity allowed when incrementing/decrementing the value.
description
Type: string
Default: Inferred
Describe the arg. (If you intend to describe the type of the arg, you should use table.type
, instead.)
if
Type:
Conditionally render an argType based on the value of another arg or global.
mapping
Type: { [key: string]: { [option: string]: any } }
Map options
to values.
When dealing with non-primitive values, you'll notice that 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).
mapping
doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with control.labels
.
name
Type: string
The argTypes
object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a name
property.
Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed.
For this reason, the name
property is best used when defining an argType
that is only used for documentation purposes and not an actual property of the component. For example, when providing argTypes for each property of an object.
options
Type: string[]
Default: Inferred
If the arg accepts a finite set of values, you can specify them with options
. If those values are complex, like JSX elements, you can use mapping
to map them to string values. You can use control.labels
to provide custom labels for the options.
table
Type:
Default: Inferred
Specify how the arg is documented in the ArgTypes
doc block, Controls
doc block, and Controls addon panel.
table.category
Type: string
Default: Inferred, in some frameworks
Display the argType under a category heading, with the label specified by category
.
table.defaultValue
Type: { detail?: string; summary: string }
Default: Inferred
The documented default value of the argType. summary
is typically used for the value itself, while detail
is used for additional information.
table.disable
Type: boolean
Set to true
to remove the argType's row from the table.
table.readonly
Type: boolean
Set to true
to indicate that the argType is read-only.
table.subcategory
Type: string
Display the argType under a subcategory heading (which displays under the [category
] heading), with the label specified by subcategory
.
table.type
Type: { detail?: string; summary: string }
Default: Inferred from type
The documented type of the argType. summary
is typically used for the type itself, while detail
is used for additional information.
If you need to specify the actual, semantic type, you should use type
, instead.
type
Type: 'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType
The full type of SBType
is:
SBType
Default: Inferred
Specifies the semantic type of the argType. When an argType is inferred, the information from the various tools is summarized in this property, which is then used to infer other properties, like control
and table.type
.
If you only need to specify the documented type, you should use table.type
, instead.
defaultValue
(⛔️ Deprecated)
Type: any
Define the default value of the argType. Deprecated in favor of defining the arg
value directly.