# How to Configure Story Parameters and Args in Storybook: A Complete Guide to CSF

> Master Storybook parameters and args to control static metadata and dynamic component props. Learn how to configure them for your stories with this comprehensive CSF guide.

- Repository: [Storybook/storybook](https://github.com/storybookjs/storybook)
- Tags: how-to-guide
- Published: 2026-02-27

---

**Storybook uses two distinct mechanisms to control stories: parameters for static metadata (layout, backgrounds, addon configuration) and args for dynamic component props that power interactive controls.** Both support a global → meta → story inheritance hierarchy where later levels override earlier ones.

The Component Story Format (CSF) in Storybook provides a structured way to define component examples through stories. Understanding how to configure story parameters and args is essential for controlling both the presentation environment and the interactive behavior of your components. This guide examines the actual implementation in the `storybookjs/storybook` repository to show you exactly how these configuration layers work.

## Understanding Parameters vs Args

Before configuring stories, you must distinguish between these two core concepts:

- **Parameters** are static, serializable metadata that affect Storybook itself. They control layout, backgrounds, viewport settings, and addon behavior. Parameters live in `export default { parameters: { … } }` or within decorators.

- **Args** are runtime values passed directly to your component’s props. They enable Storybook’s interactive controls panel and allow you to manipulate component state dynamically. Args are defined in `export const MyStory = { args: { … } }`.

Both are plain objects merged from **global → meta → story** levels, as implemented in [`code/core/src/preview-api/README-store.md`](https://github.com/storybookjs/storybook/blob/main/code/core/src/preview-api/README-store.md) and exercised by the CSF factories in `code/renderers/*/src/csf-factories.test.ts`.

## Configuring Parameters

### Global Parameters

Define global parameters in [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/preview.js) (or `.ts`) to apply settings to every story in your project:

```javascript
// .storybook/preview.js
export const parameters = {
  layout: 'centered',
  backgrounds: { default: 'light' },
  a11y: { config: { rules: [] } },
};

```

This configuration centers all stories, sets a default light background, and configures accessibility rules globally.

### Component-Level Parameters

Override global settings for all stories within a single file using the meta object:

```typescript
// src/stories/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react';

const meta: Meta = {
  title: 'UI/Button',
  component: Button,
  parameters: {
    backgrounds: { default: 'dark' },
    docs: { source: { type: 'code' } },
  },
};
export default meta;

```

Here, the dark background overrides the global light setting for every story in [`Button.stories.ts`](https://github.com/storybookjs/storybook/blob/main/Button.stories.ts).

### Story-Level Parameters

Fine-tune individual stories by adding parameters directly to the story export:

```typescript
export const Primary: Story = {
  args: { label: 'Primary' },
  parameters: {
    backgrounds: { default: 'light' },
    a11y: { disable: true },
  },
};

```

This story reverts to a light background and disables accessibility checks specifically for this example.

### Parameter-Driven Decorators

Decorators receive the fully merged context including parameters and can adjust rendering accordingly:

```typescript
export const withMargin = (Story, { parameters }) => {
  const size = parameters?.smallMargin ? '8px' : '24px';
  return <div style={{ margin: size }}>{Story()}</div>;
};

```

This pattern allows decorators to respond to parameter flags set at any level of the hierarchy.

## Configuring Args

### Default Args in Meta

Set `args` in the meta object to establish default prop values for every story in the file:

```typescript
const meta: Meta = {
  component: Button,
  args: { disabled: false, variant: 'primary' },
};

```

All stories inherit these defaults, reducing repetition and ensuring consistent initial states.

### Story-Level Args

Override meta defaults or add new props for specific stories:

```typescript
export const Disabled = {
  args: { disabled: true },
};

```

This story renders the button with the `disabled` prop set to `true`, overriding the meta default.

### Args Composition

Compose args from other stories to build complex scenarios without duplication:

```typescript
export const LoggedInPage = {
  render: Page,
  args: {
    ...HeaderStories.LoggedIn.args,
    content: 'Welcome back!',
  },
};

```

This pattern, demonstrated in [`code/renderers/web-components/template/cli/ts/Page.stories.ts`](https://github.com/storybookjs/storybook/blob/main/code/renderers/web-components/template/cli/ts/Page.stories.ts), allows you to inherit and extend args from shared story definitions.

### Type-Safe Args with TypeScript

Storybook’s type helpers infer args from your component’s interface, ensuring type safety:

```typescript
import { preview } from '@storybook/web-components';
type ButtonProps = { label: string; disabled?: boolean };

const meta = preview.type<{ args: ButtonProps }>().meta({
  component: 'my-button',
  args: { label: 'Click me' },
});
export const Primary = meta.story();

```

This approach, implemented in [`code/renderers/web-components/src/preview.ts`](https://github.com/storybookjs/storybook/blob/main/code/renderers/web-components/src/preview.ts), validates that all required props are provided and only valid optional props are used.

## How Storybook Merges Configuration

Storybook resolves the final parameters and args through a specific hierarchy:

1. Start with an empty object.
2. Apply global parameters/args from [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/preview.js).
3. Overlay meta (component) parameters/args.
4. Overlay story-level parameters/args.
5. Execute decorators, which receive the fully merged context (`{ args, parameters }`) and may mutate it.

The final result is passed to the renderer, which calls your component with the computed args. This merging algorithm is documented in [`code/core/src/preview-api/README-store.md`](https://github.com/storybookjs/storybook/blob/main/code/core/src/preview-api/README-store.md) and implemented in [`code/core/src/preview-api/store.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/preview-api/store.ts).

## Complete Working Example

Here is a comprehensive story file demonstrating all configuration levels:

```typescript
// src/stories/MyComponent.stories.ts
import type { Meta, StoryObj } from '@storybook/react';
import MyComponent from './MyComponent';

const meta: Meta = {
  title: 'Demo/MyComponent',
  component: MyComponent,
  args: {
    size: 'medium',
    disabled: false,
  },
  parameters: {
    layout: 'centered',
    backgrounds: { default: 'light' },
  },
};
export default meta;

export const Small: StoryObj = {
  args: { size: 'small' },
  parameters: { smallMargin: true },
  decorators: [
    (Story, { parameters }) => {
      const margin = parameters.smallMargin ? '8px' : '24px';
      return <div style={{ margin }}>{Story()}</div>;
    },
  ],
};

export const NoA11y: StoryObj = {
  args: { size: 'large' },
  parameters: { a11y: { disable: true } },
};

```

This example illustrates global-to-story inheritance, args composition, parameter-driven decorators, and addon-specific configuration.

## Summary

- **Parameters** control Storybook’s environment (layout, backgrounds, addons) and are defined at global, meta, or story levels.
- **Args** provide interactive props to components and follow the same global → meta → story inheritance pattern.
- **Merging** occurs in sequence: global defaults are overlaid by meta settings, then by story settings, with decorators receiving the final merged context.
- **Type safety** is enforced through Storybook’s type helpers that infer arg types from component interfaces.

## Frequently Asked Questions

### What is the difference between Storybook parameters and args?

**Parameters are static metadata that configure Storybook’s behavior**, such as layout positioning, background colors, or addon settings. They are not passed to your component. **Args are dynamic values that map directly to component props**, enabling interactive controls in the Storybook UI. While parameters affect how Storybook renders the story frame, args determine what data the component receives.

### How does Storybook merge parameters and args from different levels?

Storybook applies a **global → meta → story hierarchy** when resolving the final configuration. It starts with an empty object, applies settings from [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/preview.js), then overlays values from the meta (default export), and finally applies story-level settings. This merging strategy is implemented in [`code/core/src/preview-api/store.ts`](https://github.com/storybookjs/storybook/blob/main/code/core/src/preview-api/store.ts) and documented in [`code/core/src/preview-api/README-store.md`](https://github.com/storybookjs/storybook/blob/main/code/core/src/preview-api/README-store.md).

### Can I use TypeScript to ensure my args match my component props?

Yes, Storybook provides type helpers that **automatically infer arg types from your component’s interface**. When using `Meta` and `StoryObj` types from `@storybook/react` (or your framework’s package), TypeScript validates that args objects contain only valid props and that required props are provided. For web components, the `preview.type()` helper in [`code/renderers/web-components/src/preview.ts`](https://github.com/storybookjs/storybook/blob/main/code/renderers/web-components/src/preview.ts) provides similar type safety.

### How do I disable a specific addon for one story?

Use **story-level parameters** to override addon configuration. Most addons check for a `disable` flag within their parameter namespace. For example, to disable accessibility checks for a specific story, set `parameters: { a11y: { disable: true } }` on that story export. This follows the standard parameter merging rules, allowing granular control over addon behavior without affecting other stories.