# How to Configure Viewport Addon for Responsive Testing in Storybook

> Learn to configure the Storybook Viewport addon for effective responsive testing. Simulate various screen sizes easily by setting parameters in your preview file.

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

---

**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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/code/core/src/viewport/manager.tsx), which renders the `ViewportTool` component from [`code/core/src/viewport/components/Tool.tsx`](https://github.com/storybookjs/storybook/blob/main/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.

```javascript
// .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.

```javascript
// .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.

```javascript
// 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`](https://github.com/storybookjs/storybook/blob/main/preview.ts)** – Registers default globals and preview-side logic
- **[`manager.tsx`](https://github.com/storybookjs/storybook/blob/main/manager.tsx)** – Registers the toolbar button in the manager UI
- **[`components/Tool.tsx`](https://github.com/storybookjs/storybook/blob/main/components/Tool.tsx)** – Renders the viewport selector dropdown
- **[`types.ts`](https://github.com/storybookjs/storybook/blob/main/types.ts)** – Defines TypeScript interfaces for viewport objects
- **[`constants.ts`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/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`](https://github.com/storybookjs/storybook/blob/main/preview.ts) and UI components in [`manager.tsx`](https://github.com/storybookjs/storybook/blob/main/manager.tsx) and [`Tool.tsx`](https://github.com/storybookjs/storybook/blob/main/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.