Skip to content

Latest commit

 

History

History
294 lines (206 loc) · 8.02 KB

parameters.md

File metadata and controls

294 lines (206 loc) · 8.02 KB
Raw
title
Parameters

Parameters are static metadata used to configure your stories and addons in Storybook. They are specified at the story, meta (component), project (global) levels.

Story parameters

ℹ️ Parameters specified at the story level will override those specified at the project level and meta (component) level.

Parameters specified at the story level apply to that story only. They are defined in the parameters property of the story (named export):

<CodeSnippets paths={[ 'angular/parameters-in-story.ts.mdx', 'web-components/parameters-in-story.js.mdx', 'web-components/parameters-in-story.ts.mdx', 'common/parameters-in-story.js.mdx', 'common/parameters-in-story.ts.mdx', ]} />

Meta parameters

ℹ️ Parameters specified at the meta (component) level will override those specified at the project level.

Parameter's specified in a CSF file's meta configuration apply to all stories in that file. They are defined in the parameters property of the meta (default export):

<CodeSnippets paths={[ 'angular/parameters-in-meta.ts.mdx', 'web-components/parameters-in-meta.js.mdx', 'web-components/parameters-in-meta.ts.mdx', 'common/parameters-in-meta.js.mdx', 'common/parameters-in-meta.ts.mdx', ]} />

Project parameters

Parameters specified at the project (global) level apply to all stories in your Storybook. They are defined in the parameters property of the default export in your .storybook/preview.js|ts file:

<CodeSnippets paths={[ 'common/parameters-in-preview.js.mdx', 'common/parameters-in-preview.ts.mdx', ]} />

Available parameters

Storybook only accepts a few parameters directly.

layout

Type: 'centered' | 'fullscreen' | 'padded'

Default: 'padded'

Specifies how the canvas should lay out the story.

  • centered: Center the story within the canvas
  • padded: (default) Add padding to the story
  • fullscreen: Show the story as-is, without padding

options

Type:

{
  storySort?: StorySortConfig | StorySortFn;
}

The options parameter can only be applied at the project level.

options.storySort

Type: StorySortConfig | StorySortFn

type StorySortConfig = {
  includeNames?: boolean;
  locales?: string;
  method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
  order?: string[];
};

type Story = {
  id: string;
  importPath: string;
  name: string;
  title: string;
};

type StorySortFn = (a: Story, b: Story) => number;

Specifies the order in which stories are displayed in the Storybook UI.

When specifying a configuration object, the following options are available:

  • includeNames: Whether to include the story name in the sorting algorithm. Defaults to false.
  • locales: The locale to use when sorting stories. Defaults to your system locale.
  • method: The sorting method to use. Defaults to alphabetical.
    • alphabetical: Sort stories alphabetically by name.
    • alphabetical-by-kind: Sort stories alphabetically by kind, then by name.
    • custom: Use a custom sorting function.
  • order: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components'].

When specifying a custom sorting function, the function behaves like a typical JavaScript sorting function. It accepts two stories to compare and returns a number. For example:

(a, b) => (a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }));

See the guide for usage examples.

test

Type:

{
  clearMocks?: boolean;
  mockReset?: boolean;
  restoreMocks?: boolean;
  dangerouslyIgnoreUnhandledErrors?: boolean;
}

clearMocks

Type: boolean

Default: false

Similar to Vitest, it will call .mockClear() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history, but not reset its implementation to the default one.

mockReset

Type: boolean

Default: false

Similar to Vitest, it will call .mockReset() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history and reset its implementation to an empty function (will return undefined).

restoreMocks

Type: boolean

Default: true

Similar to Vitest, it will call .restoreMocks() on all spies created with fn() from @storybook/test when a story unmounts. This will clear mock history and reset its implementation to the original one.

dangerouslyIgnoreUnhandledErrors

Type: boolean

Default: false

Setting this to true will prevent the play function from failing and showing a warning when unhandled errors are thrown during rendering or playing.

Unhandled errors might cause false positive assertions. They can be ignored by setting this parameter to true.

Essential addons

All other parameters are contributed by addons. The essential addon's parameters are documented on their individual pages:

Parameter inheritance

No matter where they're specified, parameters are ultimately applied to a single story. Parameters specified at the project (global) level are applied to every story in that project. Those specified at the meta (component) level are applied to every story associated with that meta. And parameters specified for a story only apply to that story.

When specifying parameters, they are merged together in order of increasing specificity:

  1. Project (global) parameters
  2. Meta (component) parameters
  3. Story parameters

ℹ️ Parameters are merged, so objects are deep-merged, but arrays and other properties are overwritten.

In other words, the following specifications of parameters:

// .storybook/preview.js|ts

const preview = {
  // 👇 Project-level parameters
  parameters: {
    layout: 'centered',
    demo: {
      demoProperty: 'a',
      demoArray: [1, 2],
    },
  },
  // ...
};
export default preview;
// Dialog.stories.js|ts

const meta = {
  component: Dialog,
  // 👇 Meta-level parameters
  parameters: {
    layout: 'fullscreen',
    demo: {
      demoProperty: 'b',
      anotherDemoProperty: 'b',
    },
  },
};
export default meta;

// (no additional parameters specified)
export const Basic = {};

export const LargeScreen = {
  // 👇 Story-level parameters
  parameters: {
    layout: 'padded',
    demo: {
      demoArray: [3, 4],
    },
  },
};

Will result in the following parameter values applied to each story:

// Applied story parameters

// For the Basic story:
{
  layout: 'fullscreen',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [1, 2],
  },
}

// For the LargeScreen story:
{
  layout: 'padded',
  demo: {
    demoProperty: 'b',
    anotherDemoProperty: 'b',
    demoArray: [3, 4],
  },
}