How to Configure Viewport Addon for Responsive Testing in Storybook

The Viewport addon lets you simulate different screen sizes by setting the viewport parameter and initialGlobals in your .storybook/preview.{js,ts} file, exposing device presets through the toolbar.

The viewport addon in the storybookjs/storybook repository enables responsive testing directly within Storybook’s preview pane. By configuring viewport options and globals, you can configure viewport addon for responsive testing without external browser tools.

How the Viewport Addon Works

The addon operates through a coordinated system of globals (the selected viewport state) and parameters (the available viewport catalog). This architecture separates the preview simulation from the manager UI.

Preview-Side Registration

When Storybook initializes, the preview loads configuration from .storybook/preview.{js,ts} and merges viewport parameters with initialGlobals. The addon registers its default globals in code/core/src/viewport/preview.ts, establishing the communication layer between your configuration and the iframe rendering.

Manager-Side UI

The manager interface registers a toolbar button via code/core/src/viewport/manager.tsx, which renders the ViewportTool component from code/core/src/viewport/components/Tool.tsx. This UI reads the viewport globals and parameters, presenting a dropdown of available devices while reflecting the currently active selection.

Configure Viewport Addon for Responsive Testing in Preview

You control responsive testing behavior through the viewport parameter and initialGlobals in your preview configuration file.

Use Built-in Viewport Presets

Storybook provides two built-in viewport collections: INITIAL_VIEWPORTS (comprehensive device list) and MINIMAL_VIEWPORTS (essential breakpoints). Import these from storybook/viewport to quickly populate your options.

// .storybook/preview.js
import { INITIAL_VIEWPORTS } from 'storybook/viewport';

export default {
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};

Add Custom Devices

Extend the default collections by spreading existing viewports and appending custom definitions. Each viewport requires a name, styles object with width and height, and a type categorization.

// .storybook/preview.js
import { MINIMAL_VIEWPORTS } from 'storybook/viewport';

export default {
  parameters: {
    viewport: {
      options: {
        ...MINIMAL_VIEWPORTS,
        kindle: {
          name: 'Kindle',
          styles: { width: '600px', height: '800px' },
          type: 'other',
        },
      },
    },
  },
};

Set Default Viewport

Use initialGlobals.viewport to specify which device loads by default when Storybook starts. This global state persists across stories until manually changed via the toolbar.

Lock Viewports for Specific Stories

You can constrain responsive testing to a specific viewport for individual stories by setting the globals.viewport value in the story export. When you define a viewport globally at the story level, the toolbar disables selection to prevent accidental changes.

// Button.stories.ts
export const Mobile = {
  parameters: {
    viewport: { disable: false },
  },
  globals: {
    viewport: { value: 'mobile1', isRotated: false },
  },
};

Key Source Files

Understanding the implementation helps debug configuration issues. The viewport addon source resides in code/core/src/viewport/:

• preview.ts – Registers default globals and preview-side logic
• manager.tsx – Registers the toolbar button in the manager UI
• components/Tool.tsx – Renders the viewport selector dropdown
• types.ts – Defines TypeScript interfaces for viewport objects
• constants.ts – Contains addon IDs and configuration keys

Documentation references include docs/essentials/viewport.mdx and code snippets in docs/_snippets/addon-viewport-options-in-preview.md.

Summary

• Configure the viewport addon by setting the viewport parameter and initialGlobals in .storybook/preview.{js,ts}.
• Import INITIAL_VIEWPORTS or MINIMAL_VIEWPORTS from storybook/viewport to use predefined device sets.
• Extend options with custom viewports by defining name, styles (width/height), and type properties.
• Lock stories to specific viewports using globals.viewport to disable toolbar selection.
• The addon implementation lives in code/core/src/viewport/, with preview logic in preview.ts and UI components in manager.tsx and Tool.tsx.

Frequently Asked Questions

How do I disable the viewport addon globally?

Set viewport.disable: true in your preview parameters. This removes the toolbar button and prevents viewport simulation across all stories.

Can I rotate viewports to test landscape mode?

Yes. When setting initialGlobals or story-level globals, include isRotated: true in the viewport object. The addon swaps the width and height values to simulate device rotation.

What is the difference between INITIAL_VIEWPORTS and MINIMAL_VIEWPORTS?

INITIAL_VIEWPORTS provides a comprehensive list of popular mobile and tablet devices, while MINIMAL_VIEWPORTS contains only essential responsive breakpoints (small, medium, large). Import from storybook/viewport based on your testing needs.

Why is the viewport toolbar disabled for some stories?

The toolbar disables automatically when you define a globals.viewport value at the story level. This lock prevents users from accidentally changing the viewport during targeted responsive testing for that specific component state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}