Storybook · Writing and testing · all subjects

args

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

Args composition for presentational screens

When building screens with presentational components, the inputs of a composite component are typically a combination of the inputs of the various sub-components it renders. You can use args composition to build the stories for the page based on the stories of the sub-components, which allows you to pick and choose to build realistic scenarios for your screen-level stories without repeating yourself.

Args re-render behavior

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.

Args object composition and JSON serializability

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-level args definition

To define the args of a single story, use the args CSF story key. These args will only apply to the story for which they are attached, although you can reuse them via JavaScript object spread syntax.

Component-level args definition

You can define args at the component level using the args key on the default CSF export. Component-level args will apply to all the component's stories unless you overwrite them with story-level args.

Global args definition

You can define args at the global level by defining the args property in the default export of preview.*. Global args will apply to every component's stories unless you overwrite them.

Globals better than global args for theme and settings

For most uses of global args, globals are a better tool for defining globally-applied settings, such as a theme. Using globals enables users to change the value with the toolbar menu.

Args composition for composite components

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.

Reuse component-level args for most stories

If you find yourself re-using the same args for most of a component's stories, you should consider using component-level args instead of repeating them in each story.

Args for modifying component appearance

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

URL args query parameter syntax

You can override the set of initial args for the active story by adding an args query parameter to the URL. The format is key:value pairs delimited with semicolons. For example: ?path=/story/avatar--default&args=style:rounded;size:100

URL args XSS protection restrictions

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 panel and within your story using argTypes mapping.

URL args special values: null and undefined

Special values null and undefined can be set in URL args by prefixing with a bang !. For example, args=nil:!null will set nil to null.

URL args special formats 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.

URL args extend and override defaults

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

useArgs hook for setting args within a story

Interactive components often need to be controlled by their containing component or page to respond to events, modify their state and reflect those changes in the UI. You can use the useArgs API exported by storybook/preview-api to enable this in React stories.

Do not mix Storybook hooks with React hooks

If you are using Storybook's hooks API in the story's render function, do not mix them with React's hooks such as useState, useEffect, or useRef. This is because side effects and re-rendering triggered by React's hooks do not run through Storybook's hook context, which can cause an error on re-render. To manage state and side effects within a story, you must use Storybook's equivalent hooks from storybook/preview-api.

Mapping complex arg values with argTypes

Complex values such as JSX elements cannot be serialized to the manager (e.g., the Controls panel) or synced with the URL. Arg values can be mapped from a simple string to a complex type using the mapping property in argTypes. 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.

useArgs hook for addon development

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

Args definition: what they are

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

Arguments (args) terminology

Storybook uses the generic term arguments (args for short) when talking about React's props, Vue's props, Angular's @Input, and other similar concepts.

Reusing args across components

You can import args to reuse when writing stories for other components, which is helpful when building composite components. When a child component's signature changes, you only need to change that component's stories, and dependent component stories are automatically updated.

Controls panel interactivity

Each of the args from the story function are live editable using Storybook's Controls panel. This allows your team to dynamically change components in Storybook to stress test and find edge cases. You can also use the Controls panel to edit or save a new story after adjusting control values.

Addons enhancing args

Addons can enhance args. For instance, the Actions addon auto-detects which args are callbacks and appends a logging function to them, so interactions like clicks get logged in the actions panel.

children arg JSON serialization requirement

The children arg, like all args, must be JSON serializable to avoid errors. Avoid using empty values, use mapping if you want to adjust the value with controls, and use caution with components that include third-party libraries.

Use intersection types for custom args in TypeScript stories

Sometimes stories need to define args that aren't included in the component's props. For this case, you can use an intersection type to combine a component's props type and your custom args' type.

Give your agent this brain