Viewport

Purpose and Scope

The Viewport feature is the Storybook Essentials tool for checking how a story behaves at different iframe dimensions. A story renders inside Storybook’s preview iframe, and Viewport changes that iframe’s size so responsive layouts can be reviewed without leaving the component workshop. This is useful when a component has breakpoints, fluid layouts, overflow behavior, or mobile-specific affordances that should be validated alongside the same args, decorators, loaders, and documentation used elsewhere in Storybook.

Sources: docs/essentials/viewport.mdx

Viewport is not a replacement for browser responsive mode or device testing. Instead, it gives teams a repeatable, story-level way to exercise common sizes while developing components in isolation. Because the selected viewport lives in Storybook’s UI state, a designer, developer, or tester can open the same story and quickly switch between presets such as small mobile, tablet, and desktop. That makes responsive review part of normal story browsing rather than a separate manual setup step.

Sources: docs/essentials/viewport.mdx

Relevant Source Files

• docs/essentials/viewport.mdx - Defines the public Viewport documentation page, the configuration model, the default minimal preset set, and the relationship between viewport options, Storybook parameters, and initial globals.

Core Concepts

Viewport configuration has two related concepts: the set of selectable viewport presets and the initial selection. The selectable presets are configured with the viewport parameter in .storybook/preview.*. The initial selection is configured with initialGlobals, which sets global UI state before a user changes it from the toolbar. Keeping those responsibilities separate matters because a project may offer many presets but still want stories to open in a predictable default size during development, demos, or review.

Sources: docs/essentials/viewport.mdx

A viewport preset is identified by a key and describes a named screen size. The documented default minimal set is designed for common responsive scenarios rather than exhaustive device simulation. It includes mobile1 for small mobile at 320 × 568, mobile2 for large mobile at 414 × 896, tablet at 834 × 1112, and desktop at 1024 × 1280. These presets are also available through the MINIMAL_VIEWPORTS export, which lets a project opt into or compose from Storybook’s standard baseline rather than redefining those dimensions by hand.

Sources: docs/essentials/viewport.mdx

When the minimal set is not enough, Storybook exposes a larger device catalog through the INITIAL_VIEWPORTS export. The documentation describes it as a more detailed set of devices and begins with iPhone-oriented presets such as iphone5, iphone6, iphone6p, iphone8p, iphonex, iphonexr, and related device keys. Use this detailed catalog when a product team needs device-specific review vocabulary, while using the minimal set when the goal is simply to cover representative breakpoints with less toolbar noise.

Sources: docs/essentials/viewport.mdx

Configuration Flow

Configure project-wide viewport behavior in .storybook/preview.*, because that file controls story rendering defaults for the preview. The docs show that the viewport parameter is the place to define the available options, while initialGlobals sets the initial viewport. In practice, this means the toolbar knows which presets can be selected, and the first render can start from a particular preset without each story having to repeat the same setup.

Sources: docs/essentials/viewport.mdx

// .storybook/preview.ts
import type { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    viewport: {
      options: {
        smallMobile: {
          name: 'Small mobile',
          styles: { width: '320px', height: '568px' },
        },
        desktop: {
          name: 'Desktop',
          styles: { width: '1024px', height: '1280px' },
        },
      },
    },
  },
  initialGlobals: {
    viewport: { value: 'smallMobile' },
  },
};
 
export default preview;

The important design choice is that Viewport is parameter-driven. Parameters are Storybook’s configuration channel for global, component, and story-level behavior, and addons consume those parameters to adjust how stories are rendered or displayed. For Viewport, the project-level parameter defines the menu of viewport options. A team can then treat those options as part of its UI development contract: if a component supports mobile and desktop layouts, the relevant presets should exist in the shared preview configuration.

Sources: docs/essentials/viewport.mdx

Selecting and Overriding Presets

Once configured, the user selects a viewport from the Storybook toolbar while viewing a story. The selected value changes the preview iframe dimensions, so the story re-renders inside the chosen width and height. This interaction is especially helpful while tuning CSS, container queries, layout components, and stories that demonstrate responsive states. Because the feature operates around the iframe, it applies across supported renderers in the same conceptual way: the component still renders as a story, but the containing viewport changes.

Sources: docs/essentials/viewport.mdx

The default set is intentionally small, so many projects should start there and only add detail when it improves review quality. Too many presets can make the toolbar harder to use and can encourage teams to chase device names instead of validating layout behavior. A good pattern is to define presets around product breakpoints, then optionally import Storybook’s built-in exports when the team wants familiar device labels. The docs explicitly call out both the minimal preset set and the more detailed INITIAL_VIEWPORTS catalog, giving teams a clear migration path from simple to comprehensive coverage.

Sources: docs/essentials/viewport.mdx

Story-level overrides should be reserved for cases where a component is meaningful only in a particular responsive context. For example, a mobile navigation drawer story may open at a mobile viewport by default, while a data table story may demonstrate desktop overflow behavior. In those cases, keep the global preset list in .storybook/preview.*, then use story or component configuration to steer the initial context when the story’s purpose requires it. This keeps the Storybook consistent while still allowing responsive examples to be self-explanatory.

Sources: docs/essentials/viewport.mdx

Compact Reference

Practical Next Steps

Start by running Storybook and opening a responsive story. Use the toolbar to verify whether the built-in minimal sizes cover the component’s important breakpoints. If they do, keep the configuration simple and rely on the default experience. If your product has named breakpoints or device review requirements, add viewport.options in .storybook/preview.* and set an initialGlobals value that matches your most common review size. For broader context, read the Parameters page next, because Viewport depends on Storybook’s parameter model, then review Toolbars and Globals to understand how global UI state is selected and shared.