Args

Watch a video tutorial

A story is a component with a set of arguments that define how the component should render. “Args” are Storybook’s mechanism for defining those arguments in a single JavaScript object. Args can be used to dynamically change props, slots, styles, inputs, etc. It allows Storybook and its addons to live edit components. You do not need to modify your underlying component code to use args.

When an arg’s value changes, the component re-renders, allowing you to interact with components in Storybook’s UI via addons that affect args.

Learn how and why to write stories in the introduction. For details on how args work, read on.

Args object

The args object can be defined at the story, component and global level. It is a JSON serializable object composed of string keys with matching valid value types that can be passed into a component for your framework.

Story args

To define the args of a single story, use the args CSF story key:

Button.stories.ts|tsx

import React from 'react';
 
import { ComponentStory, ComponentMeta } from '@storybook/react';
 
import { Button, ButtonProps } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
} as ComponentMeta<typeof Button>;
 
//👇 We create a “template” of how args map to rendering
const Template: ComponentStory<typeof Button> = (args) => <Button {...args} />;
 
export const Primary = Template.bind({});
 
Primary.args = {
  primary: true,
  label: 'Button',
};

These args will only apply to the story for which they are attached, although you can reuse them via JavaScript object reuse:

Button.stories.js|jsx|ts|tsx

import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
};
 
const Template = () => ({
  //👇 Your template goes here
})
 
export const PrimaryLongName = Template.bind({});
 
PrimaryLongName.args = {
  ...Primary.args,
  label: 'Primary with a really long name',
};

In the above example, we use the object spread feature of ES 2015.

Component args

You can also define args at the component level; they will apply to all the component's stories unless you overwrite them. To do so, use the args key on the default CSF export:

Button.stories.ts|tsx

import React from 'react';
 
import { ComponentMeta } from '@storybook/react';
 
import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
  //👇 Creates specific argTypes
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: {
    //👇 Now all Button stories will be primary.
    primary: true,
  },
} as ComponentMeta<typeof Button>;

Global args

You can also define args at the global level; they will apply to every component's stories unless you overwrite them. To do so, export the args key in your preview.js:

preview.js

// All stories expect a theme arg
export const argTypes = { theme: { control: 'select', options: ['light', 'dark'] } };
 
// The default value of the theme arg to all stories
export const args = { theme: 'light' };

Args composition

You can separate the arguments to a story to compose in other stories. Here's how you can combine args for multiple stories of the same component.

Button.stories.js|jsx|ts|tsx

import { Button } from './Button';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Button',
  component: Button,
};
 
const Template = (args) => ({
  // 👈 Your template goes here
});
 
export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};
 
export const Secondary = Template.bind({});
Secondary.args = {
  ...Primary.args,
  primary: false,
};

If you find yourself re-using the same args for most of a component's stories, you should consider using component-level args.

Args are useful when writing stories for composite components that are assembled from other components. Composite components often pass their arguments unchanged to their child components, and similarly, their stories can be compositions of their child components stories. With args, you can directly compose the arguments:

Page.stories.ts|tsx

import React from 'react';
 
import { ComponentStory, ComponentMeta } from '@storybook/react';
 
import { Page } from './Page';
 
//👇 Imports all Header stories
import * as HeaderStories from './Header.stories';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Page',
  component: Page,
} as ComponentMeta<typeof Page>;
 
const Template: ComponentStory<typeof Page> = (args) => <Page {...args} />;
 
export const LoggedIn = Template.bind({});
LoggedIn.args = {
  ...HeaderStories.LoggedIn.args,
};

Args can modify any aspect of your component

You can use args in your stories to configure the component's appearance, similar to what you would do in an application. For example, here's how you could use a footer arg to populate a child component:

Page.stories.ts|tsx

import React from 'react';
 
import { ComponentStory, ComponentMeta } from '@storybook/react';
 
import { Page } from './Page';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'Page',
  component: Page,
} as ComponentMeta<typeof Page>;
 
const Template: ComponentStory<typeof Page> = (args) => (
  <Page {...args}>
    <footer>{args.footer}</footer>
  </Page>
);
 
export const CustomFooter = Template.bind({});
CustomFooter.args = {
  footer: 'Built with Storybook',
};

Setting args through the URL

You can also override the set of initial args for the active story by adding an args query parameter to the URL. Typically you would use the Controls addon to handle this. For example, here's how you could set a size and style arg in the Storybook's URL:

?path=/story/avatar--default&args=style:rounded;size:100

As a safeguard against XSS attacks, the arg's keys and values provided in the URL are limited to alphanumeric characters, spaces, underscores, and dashes. Any other types will be ignored and removed from the URL, but you can still use them with the Controls addon and within your story.

The args param is always a set of key: value pairs delimited with a semicolon ;. Values will be coerced (cast) to their respective argTypes (which may have been automatically inferred). Objects and arrays are supported. Special values null and undefined can be set by prefixing with a bang !. For example, args=obj.key:val;arr[0]:one;arr[1]:two;nil:!null will be interpreted as:

{
  obj: { key: 'val' },
  arr: ['one', 'two'],
  nil: null
}

Similarly, special formats are available for dates and colors. Date objects will be encoded as !date(value) with value represented as an ISO date string. Colors are encoded as !hex(value), !rgba(value) or !hsla(value). Note that rgb(a) and hsl(a) should not contain spaces or percentage signs in the URL.

Args specified through the URL will extend and override any default values of args set on the story.

Mapping to complex arg values

Complex values such as JSX elements cannot be serialized to the manager (e.g., the Controls addon) or synced with the URL. Arg values can be "mapped" from a simple string to a complex type using the mapping property in argTypes to work around this limitation. It works in any arg but makes the most sense when used with the select control type.

MyComponent.stories.js|jsx|ts|tsx

import { MyComponent } from './MyComponent';
 
export default {
  /* 👇 The title prop is optional.
  * See https://storybook.js.org/docs/6/configure#configure-story-loading
  * to learn how to generate automatic titles
  */
  title: 'MyComponent',
  component: MyComponent,
  argTypes: {
    label:{
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
};

Note that mapping does not have to be exhaustive. If the arg value is not a property of mapping, the value will be used directly. Keys in mapping always correspond to arg values, not their index in the options array.

Using args in addons

If you are writing an addon that wants to read or update args, use the useArgs hook exported by @storybook/api:

your-addon/manager.js

import { useArgs } from '@storybook/api';
 
const [args, updateArgs, resetArgs] = useArgs();
 
// To update one or more args:
updateArgs({ key: 'value' });
 
// To reset one (or more) args:
resetArgs((argNames: ['key']));
 
// To reset all args
resetArgs();

parameters.passArgsFirst

In Storybook 6+, we pass the args as the first argument to the story function. The second argument is the “context”, which includes story parameters, globals, argTypes, and other information.

In Storybook 5 and before we passed the context as the first argument. If you’d like to revert to that functionality set the parameters.passArgsFirst parameter in .storybook/preview.js:

.storybook/preview.js

export const parameter = { passArgsFirst : false }.

Note that args is still available as a key in the context.