Storybook · Writing and testing · all subjects

stories

88 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Multi-component stories rendering

When you have two or more components created to work together, like a parent List component requiring child ListItem components, you can customize the rendering to output the parent component with different numbers of child components.

Story file location

A component's stories are defined in a story file that lives alongside the component file. The story file is for development-only and won't be included in your production bundle. The filename follows the pattern Component.stories.js, Component.stories.ts, Component.stories.jsx, Component.stories.tsx, or Component.stories.svelte.

Story definition

A story captures the rendered state of a UI component. It's an object with annotations that describe the component's behavior and appearance given a set of arguments.

Parameters definition

Parameters are Storybook's method of defining static metadata for stories. A story's parameters can be used to provide configuration to various addons at the level of a story or group of stories.

Reusing story data across components

You can reuse story data from child components in your parent component stories. This is easier to maintain because you don't have to update data in multiple places.

Component Story Format (CSF) definition

Component Story Format is an ES6 module-based standard that is easy to write and portable between tools. For non-Svelte, the key ingredients are the meta (default export) that describes the component and named exports that describe the stories.

Default export metadata requirements

The default export metadata controls how Storybook lists your stories and provides information used by addons. Starting with Storybook version 7.0, the default export must contain a title property that can be read statically or a component property from which an automatic title can be computed. Using the id property to customize story URLs must also be statically readable.

Story export naming convention

Use UpperCamelCase for story exports. For example, export a story called Primary to render a component in the primary state.

Custom story name with name property

You can customize the name of your story by adding a name property to the story object. This is useful when you want to provide a more descriptive or user-friendly name for your story than the export name.

Custom rendering with render function

By default, stories render the component defined in the meta with the args passed to it. If you need to render something else, you can provide a function to the render property that returns the desired output. The render function must spread args onto the component to ensure features like Controls work as expected.

Render function context argument

Render functions receive a second context argument, which contains all other details for the story, including parameters, globals, and more.

Reusable render functions at meta level

You can define a render function in the meta (default export) and reuse it across multiple stories. Whatever you define at the meta level can be overridden at the story level, allowing you to customize individual stories if needed.

Building multiple stories for one component

You can have multiple stories per component that build upon one another. For example, you can create Secondary and Tertiary stories based on a Primary story, with each story defining different args.

Parameters configuration levels

Parameters can be configured at global, component, and story levels. Most features and addons are configured via a parameter-based API and can be influenced at any of these levels.

Two methods for organizing stories: implicit and explicit

Stories can be organized using two methods: the implicit method relies on the physical location of stories to position them in the sidebar, while the explicit method uses the `title` parameter to place stories.

storySort configuration in preview.js

Story sorting can be customized by adding `storySort` to the `options` parameter in the `preview.js` file. You can use the unique story identifier, `title`, `name`, or import path to sort stories.

storySort configuration object fields

The `storySort` function accepts a configuration object with the following fields: **method** (String, optional, default: Storybook configuration, example: `'alphabetical'`) - tells Storybook in which order stories are displayed; **order** (Array, optional, default: empty array `[]`, example: `['Intro', 'Components']`) - stories to be shown ordered by supplied name; **includeNames** (Boolean, optional, default: `false`, example: `true`) - include story name in sort calculation; **locales** (String, optional, default: system locale, example: `'en-US'`) - the locale required to be displayed.

Alphabetical sorting with method and locales

To sort stories alphabetically, set `method` to `'alphabetical'` and optionally set the `locales` string.

Custom sorting with order array

To sort stories using a custom list, use the `order` array. Stories that don't match an item in the `order` list will appear after the items in the list. The `order` array can accept nested arrays to sort 2nd-level story kinds.

Using wildcard in order array for remaining stories

Insert a `*` into the `order` array to indicate where 'all other stories' should appear in the sorted list. This is useful for placing specific categories at the end of the list.

order option is independent of method option

The `order` option is independent of the `method` option. Stories are sorted first by the `order` array and then by either `method: 'alphabetical'` or the default `configure()` import order.

Story hierarchy components: category, folder, component, docs, story

The story hierarchy consists of five parts: Category (top-level grouping), Folder (mid-level organizational unit representing a feature or section), Component (low-level organizational unit for the component being tested), Docs (automatically generated documentation page), and Story (individual story testing a specific component state).

Using title parameter to define story position in sidebar

The `title` parameter can be used explicitly to define a story's position in the sidebar and to group related components together in an expandable interface.

Using slash separator to group related components

Related components can be grouped in an expandable interface by using the `/` character as a separator in the `title` parameter.

Single-story hoisting behavior

Single-story components (component stories without siblings) whose display name exactly matches the component's name (the last part of `title`) are automatically hoisted up to replace their parent component in the UI. Story exports are automatically start-cased (e.g., `myStory` becomes `'My Story'`), so the component name should match that format. Alternatively, you can override the story name using `myStory.storyName = '...'` to match the component name.

Default story sorting order

By default, Storybook sorts stories based on the order in which they are imported.

children arg for subcomponent control

To enable control of subcomponents through the Controls panel, pull the rendered subcomponent out into a children arg. This makes the subcomponent reusable across different stories and allows modification through controls.

subcomponents property for parent-child components

Use the subcomponents property in the meta (or default export) to document parent and child components together. This is useful when the child component is not meant to be used on its own, but only as part of the parent component. Adding subcomponents generates an extra panel on the ArgTypes and Controls tables that lists the props of each subcomponent.

Reusing story definitions in composite component stories

You can reduce repetition in stories by reusing story definitions from child components. For example, you can reuse the args from a child component's story when rendering it as part of a parent component story.

subcomponents limitations with controls

The documentation table for each documented subcomponent does not include controls to change the value of the props, because controls always apply to the main component's args, not to subcomponents.

subcomponents limitations with argTypes

ArgTypes of subcomponents are inferred and cannot be manually defined or overridden. The subcomponents feature is intended for documentation purposes only.

Template component approach for composite stories

Create a special story-generating template component to handle composite component stories in a data-based way. This approach requires more setup but allows you to reuse args to each story in a composite component and alter the args with the Controls panel.

Two ways to create custom tags

Custom tags can be created by applying them to a story, component (meta), or project (.storybook/preview.*) level, or by defining them in the Storybook configuration file (.storybook/main.*) to provide more options like default filter selection.

Tags control story inclusion in Storybook

Tags allow you to control which stories are included in your Storybook, enabling different uses of the same set of stories. For example, tags can be used to include or exclude tests from the test runner.

Built-in tags reference

The following tags are available in every Storybook project: dev (applied by default, stories rendered in sidebar), manifest (applied by default, included in component or docs manifests for React), test (applied by default, included in test runner or Vitest addon runs), autodocs (not applied by default, included in docs page), play-fn (not applied by default, automatically applied to stories with a play function), test-fn (not applied by default, automatically applied to tests defined using the experimental .test method on CSF Factories).

dev tag applied by default to all stories

The dev, manifest, and test tags are automatically and implicitly applied to every story in a Storybook project.

Custom tags enable flexible categorization

Custom tags provide a flexible layer of categorization beyond Storybook's sidebar hierarchy. Example uses include status tags (experimental, new, stable, deprecated), user persona tags (admin, user, developer), and component/code ownership tags.

defaultFilterSelection controls tag default state

When configuring a custom tag in .storybook/main.*, the defaultFilterSelection property controls whether stories with the tag are selected as included (if set to 'include'), excluded (if set to 'exclude'), or have no default selection (if not set).

Apply tags as array of strings

Tags can be applied at the project, component (meta), or story level by assigning an array of strings to the tags property. A tag must be a static string, not created dynamically.

Remove tags with exclamation prefix

To remove a tag from a story, prefix it with an exclamation mark (!). Tags can be removed at all stories in a project (in .storybook/preview.*), all stories for a component (in the CSF file meta), or a single story.

Sidebar tag filtering includes multiple tags

Selecting multiple tags in the sidebar filter shows stories that contain any of those tags. Pressing the Exclude button for a tag excludes stories with that tag from the sidebar. You can mix inclusion and exclusion filters. When no tags are selected, all stories are shown.

Search applies tag filter first

When using tag filters in Storybook's sidebar, search results are limited to the currently filtered tags, as the filter is applied before searching.

Create docs-only stories with autodocs and !dev tags

To create a story that appears only in the docs page and not in Storybook's sidebar, enable the autodocs tag and remove the dev tag by using !dev. This is useful for providing example stories for documentation purposes while keeping the sidebar focused on development stories.

Test variant combinations individually with tags

For components with many variants, you can create a combo story that shows all variants together for visualization, while using tags to ensure each variant is still tested individually.

Experimental _test tag excludes tests from sidebar

The experimental _test tag (used with the experimental .test method on CSF Factories) can be configured with defaultFilterSelection set to 'exclude' to exclude tests from the sidebar by default, reducing clutter while still allowing tests to be run or shown via filter.

Web Components CSF Next infers optional types

The inferred types for web components in CSF Next will be optional (i.e. Partial<T>). In other words, required props will not be enforced.

Meta and StoryObj are generic types for prop type parameters

Meta and StoryObj types are both generics, so you can provide them with an optional prop type parameter for the component type or the component's props type (e.g., the typeof Button portion of Meta<typeof Button>). By doing so, TypeScript will prevent you from defining an invalid arg, and all decorators, play functions, or loaders will type their function arguments.

Use Meta and StoryObj utility types for typing stories

Storybook provides utility types for typing story files, named Meta and StoryObj. Meta is used to type the component meta (default export in a CSF file), which describes and configures the component and its stories. StoryObj is used to type the stories themselves.

CSF Next provides improved TypeScript support for stories

CSF Next (currently in preview) provides significantly improved TypeScript support, which infers component types automatically and requires no explicit typing for most cases. You only need to add types when using custom args.

Storybook infers component types to auto-generate Controls table

Storybook infers component types from TypeScript to auto-generate the Controls table.

TypeScript enables component prop autocomplete in stories

Writing stories in TypeScript makes you more productive because your code editor will alert you about missing required props and even autocomplete prop values, just like when using your components within your app.

TypeScript support in Storybook requires zero configuration

Storybook has built-in TypeScript support, so you can get started with zero configuration required.

Web Components enforce required props using preview.type

If you wish to have required props enforced in web components stories, you can explicitly provide the component's props type to preview.type as shown in the following example: const meta = preview.type<{ args: MyElementProps }>().meta({ component: 'my-element' });

Use satisfies operator for stricter TypeScript type checking in stories

If you are using TypeScript 4.9+, you can take advantage of the new satisfies operator to get stricter type checking. Now you will receive type errors for missing required args, not just invalid ones. Using satisfies to apply a story's type helps maintain type safety when sharing a play function across stories. Without it, TypeScript will throw an error that the play function may be undefined. Finally, use of satisfies allows you to pass typeof meta to the StoryObj generic, which informs TypeScript of the connection between the meta and StoryObj types, allowing it to infer the args type from the meta type. TypeScript will understand that args can be defined both at the story and meta level and won't throw an error when a required arg is defined at the meta level, but not at the story level.

Vue TypeScript support via vue-tsc and Volar extension

You can type check Vue SFC files with vue-tsc and get editor support in VSCode by installing the official Vue extension (Volar). This setup will add type support for *.vue imports to your *.stories.ts files, providing the same type safety and autocomplete features.

CSF Next supports Generic Vue components with type parameters

CSF Next adds support for Generic Vue components (using <script lang="ts" setup generic="T">). Simply pass the type parameter directly to the component when defining the meta.

Vue generics type inference issue in prior CSF versions

Prior CSF versions to CSF Next suffer from a long-standing type inference issue where the generic type T would default to unknown.

Svelte TypeScript support via svelte-check and VSCode extension

You can run type checks using svelte-check and add VSCode editor support with the Svelte for VSCode extension. The same setup works with Svelte stories files too, providing both type safety and autocompletion.

Angular CSF 3 does not infer component types

CSF 3 offers basic TypeScript support for Angular components, but it does not infer component types.

CSF Next for Angular infers types but makes them optional

CSF Next is able to infer types for Angular components, but the inferred types will be optional (i.e. Partial<T>). In other words, required props will not be enforced.

Give your agent this brain