CSF Next is preview feature for React, Vue, Angular, Web Components
CSF Next is currently in preview and only supported in React, Vue, Angular, and Web Components projects. The API may change in future releases.
Storybook · API · all subjects
csf/next
34 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
defineMain function for main config
The defineMain function specifies your main Storybook config and is type-safe. Import it from '@storybook/your-framework/node'. Example: import { defineMain } from '@storybook/your-framework/node'; export default defineMain({ framework: '@storybook/your-framework', stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: ['@storybook/addon-a11y'] });
definePreview function for preview config
The definePreview function specifies your project's story configuration and is type-safe. By specifying addons here, their types will be available throughout your project. Import it from '@storybook/your-framework'. Example: import { definePreview } from '@storybook/your-framework'; import addonA11y from '@storybook/addon-a11y'; export default definePreview({ addons: [addonA11y()], parameters: { a11y: { options: { xpath: true } } } });
preview.meta creates story metadata
The meta function on the preview object is used to define metadata for your stories. It accepts an object containing component, title, parameters, and other story properties. Example: const meta = preview.meta({ component: Button, parameters: { layout: 'centered' } });
preview.type for custom component types
The preview.type function allows you to specify custom types for your component's props when the default inference needs modification. Example: const meta = preview.type<{ args: CustomProps }>().meta({ component: Button, render: ({ customProp, ...args }) => <>{customProp} <Button {...args} /></> });
meta.story defines individual stories
The story function on the meta object defines individual stories. It accepts an object containing name, args, parameters, and other story properties. Example: export const Primary = meta.story({ args: { primary: true } });
Story.extend method for reusing stories
The .extend method creates a new story based on an existing one. Args are shallow merged, parameters are deep merged (except arrays which are replaced), decorators and tags are concatenated. Example: export const PrimaryDisabled = Primary.extend({ args: { disabled: true } });
Story.test method for attaching tests
The .test method (experimental) provides an ergonomic way to define tests for stories. It must be enabled via the experimentalTestSyntax feature flag. Example: PrimaryDisabled.test('should be disabled', async ({ canvas, userEvent, args }) => { const button = await canvas.findByRole('button'); await userEvent.click(button); await expect(button).toHaveAttribute('aria-disabled', 'true'); await expect(args.onClick).not.toHaveBeenCalled(); });
Automatic upgrade from CSF 3 to CSF Next
You can automatically upgrade CSF 3 stories to CSF Next using the command: npx storybook@latest migrate csf-factories --glob 'src/**/*.stories.*'. For monorepos, use: npx storybook@latest migrate csf-factories --glob 'src/**/*.stories.*' -c <config-directory>.
Story.composed property for accessing composed values
Story properties are now contained in a composed property. Access composed args with Story.composed.args and composed parameters with Story.composed.parameters. There is also a Story.input property for accessing direct input to the story.
Portable stories no longer require composeStories
With CSF Next, portable stories can be reused directly without calling composeStories. Stories can be imported and used directly in test files. Example: import * as stories from './Button.stories'; const { Primary } = stories; await Primary.run();
Story.Component property for custom rendering
CSF Next stories provide a Component property enabling you to render the component with any method you choose, such as Testing Library. You can also access composed properties via the composed property.
Subpath imports for preview config
You can use subpath imports for absolute imports of the preview config instead of relative imports. Configure in package.json with: { "imports": { "#*": ["./", "./*.ts", "./*.tsx"] } }. This allows import preview from '#.storybook/preview' instead of relative paths.
Addon imports for preview config
For official Storybook addons that provide annotations, import the default export: import addonName from '@storybook/addon-name'. For community addons, import the entire module and access the addon from there: import * as addonName from 'community-addon-name'.
Preview addons automatically updated on install
When installing an addon via 'npx storybook add <addon-name>' or running 'storybook dev', the preview configuration will be automatically updated to reference the necessary addons.
CSF Next incremental adoption supported
CSF Next is designed to be usable incrementally. You do not have to upgrade all story files at once. However, you cannot mix story formats within the same file.
CSF Next supports MDX doc blocks without changes
Doc blocks used to reference stories in MDX files support the CSF Next format with no changes needed.
Prior CSF formats remain supported
Storybook will continue to support CSF 1, CSF 2, and CSF 3 for the foreseeable future. None of these prior formats are deprecated.
Property merging in Story.extend
When using Story.extend, properties merge as follows: args are shallow merged, parameters are deep merged except arrays which are replaced, decorators and tags are concatenated.
Vitest setup file changes for CSF Next
For CSF Next with portable stories in Vitest, the setup file must be updated. Replace setProjectAnnotations with: import preview from './.storybook/preview'; beforeAll(preview.composed.beforeAll);. This only applies if all tested stories use CSF Next.
CSF default export defines component metadata
The default export in a CSF story file defines metadata about the component, including the component itself, its title (for navigation UI story hierarchy), decorators, and parameters. The component field is required and used by addons for automatic prop table generation and component metadata display. The title field is optional and should be unique across files.
CSF named exports represent story objects
In CSF, every named export in the file represents a story object by default. The exported identifiers are converted to start case using Lodash's startCase function. Story objects can be annotated with fields to define story-level decorators, parameters, and the story name.
CSF export identifier transformation to story names
Named exports are transformed to start case for story display names. Examples: 'name' becomes 'Name', 'someName' becomes 'Some Name', 'someNAME' becomes 'Some NAME', 'some_custom_NAME' becomes 'Some Custom NAME', 'someName1234' becomes 'Some Name 1 2 3 4'. Best practice is to start all export names with a capital letter.
CSF name field overrides export identifier
Storybook uses the named export to determine the story ID and URL. If the name field is specified in the story object, it is used as the story display name in the UI; otherwise, it defaults to the named export processed through Storybook's storyNameFromExport and lodash.startCase functions.
When to use CSF name configuration element
Use the name configuration element in these cases: (1) when you want the name to show in the Storybook UI in a way not possible with a named export, such as reserved keywords like 'default', special characters like emoji, or specific spacing/capitalization; (2) when you want to preserve the story ID independently from changing the display name, which is helpful for integration with third-party tools.
CSF Args are dynamic named inputs for stories
Starting in Storybook 6.0, stories accept named inputs called Args. Args are dynamic data provided by Storybook and its addons. Using Args makes stories shorter, more accessible, and more portable since the code does not depend on specific features like actions.
CSF play function executes code when story renders
The play function is a small snippet of code executed when the story renders in the UI. It is a convenient helper method to test use cases that otherwise were not possible or required user intervention. Common use case is testing form components by programmatically interacting with them and running assertions.
CSF render function provides custom rendering control
Starting in Storybook 6.4, you can write stories as JavaScript objects with a render function to reduce boilerplate and give additional control over how the story renders. When Storybook detects a render function, it adjusts component rendering based on what is defined in that function.
CSF includeStories and excludeStories configuration
The optional configuration fields includeStories and excludeStories in the default export allow exporting a mixture of stories and non-stories (e.g., mocked data). Both can be defined as arrays of strings or regular expressions. Recommended option is includeStories: /^[A-Z]/ if following the best practice of starting story exports with an uppercase letter.
CSF 3 named exports are objects, not functions
In CSF 3, named exports are objects instead of functions as in CSF 2. This allows more efficient story reuse with the JavaScript spread operator to carry over all annotations when creating derived stories.
CSF 3 provides default render functions
CSF 3 provides default render functions for each renderer. If you are only spreading args into your component (the most common case), you do not need to specify a render function at all. The default render function handles this automatically.
CSF 3 can automatically generate story titles
CSF 3 can automatically generate story titles. If a title is not specified in the default export, it can be inferred from the story's path on disk. The title field is optional and can still be specified explicitly.
CSF is an open standard based on ES6 modules
Component Story Format (CSF) is the recommended way to write stories and is an open standard based on ES6 modules. It is portable beyond Storybook. In CSF, stories and component metadata are defined as ES Modules with a required default export and one or more named exports.
CSF definition
Component Story Format (CSF) is the API for writing stories. It is an open standard based on ES6 modules that is portable beyond Storybook.