Docs
Storybook Docs

Viewport

Watch a video tutorial

The Viewport toolbar item allows you to adjust the dimensions of the iframe your story is rendered in. It makes it easy to develop responsive UIs.

Configuration

Out of the box, the Viewport addon offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can set the global parameters.viewport parameter in your .storybook/preview.js:

.storybook/preview.ts
// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: newViewports, // newViewports would be an ViewportMap. (see below for examples)
      defaultViewport: 'someDefault',
    },
  },
};
 
export default preview;

The viewport global can take an object with the following keys:

FieldTypeDescriptionDefault Value
defaultViewportStringSets the default viewport'responsive'
defaultOrientationStringSets the default orientation (e.g. portrait or landscape)'portrait'
disableBooleanDisables the viewportN/A
viewportsObjectThe configuration objects for the viewport{}

The viewports object needs the following keys:

FieldTypeDescriptionExample values
nameStringName for the viewport'Responsive'
stylesObjectSets Inline styles to be applied to the story{ width:0, height:0 }
typeStringType of the device (e.g., desktop, mobile, or tablet)desktop

Use a detailed set of devices

The Viewport addon includes a selection of devices that you can use to test your components. Listed below are the available devices and examples of how to use them.

DeviceDescriptionDimensions
(wร—h, px)
iPhone 5Configures the iPhone 5 as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone5', }},
320 ร— 568
iPhone 6Enables the iPhone 6 to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone6', }},
375 ร— 667
iPhone 6 PlusIncludes the iPhone 6 Plus as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone6p', }},
414 ร— 736
iPhone 8 PlusSets the iPhone 8 Plus as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone8p', }},
414 ร— 736
iPhone XConfigures the iPhone X as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphonex', }},
375 ร— 812
iPhone XRIncludes the iPhone XR as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphonexr', }},
414 ร— 896
iPhone XS MaxSets the iPhone XS Max as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphonexsmax', }},
414 ร— 896
iPhone SE (2nd generation)Configures the iPhone SE (2nd generation) as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphonese2', }},
375 ร— 667
iPhone 12 miniEnables the iPhone 12 Mini to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone12mini', }},
375 ร— 812
iPhone 12Includes the iPhone 12 as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone12', }},
390 ร— 844
iPhone 12 Pro MaxConfigures the iPhone 12 Pro Max as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone12promax', }},
428 ร— 926
iPhone SE 3rd generationEnables the iPhone SE (3rd generation) to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphoneSE3', }},
375 ร— 667
iPhone 13Includes the iPhone 13 as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone13', }},
390 ร— 844
iPhone 13 ProEnables the iPhone 13 Pro to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone13pro', }},
390 ร— 844
iPhone 13 Pro MaxConfigures the iPhone 13 Pro Max as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone13promax', }},
428 ร— 926
iPhone 14Enables the iPhone 14 to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone14', }},
390 ร— 844
iPhone 14 ProIncludes the iPhone 14 Pro as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone14pro', }},
393 ร— 852
iPhone 14 Pro MaxSets the iPhone 14 Pro Max as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'iphone14promax', }},
430 ร— 932
Galaxy S5Configures the Galaxy S5 as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'galaxys5', }},
360 ร— 640
Galaxy S9Enables the Galaxy S9 to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'galaxys9', }},
360 ร— 740
Nexus 5XIncludes the Nexus 5x as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'nexus5x', }},
412 ร— 668
Nexus 6PSets the Nexus 6P as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'nexus6p', }},
412 ร— 732
PixelConfigures the Pixel as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'pixel', }},
540 ร— 960
Pixel XLEnables the Pixel XL to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'pixelxl', }},
720 ร— 1280
Small mobileEnabled by default.
Configures a small form factor generic mobile device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'mobile1', }},
320 ร— 568
Large mobileEnabled by default.
Configures a large form factor mobile device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'mobile2', }},
414 ร— 896
iPadIncludes the iPad as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'ipad', }},
768 ร— 1024
iPad Pro 10.5-inEnables the iPad Pro (10.5-inch) to be used with the Viewport addon.
parameters: { viewport: { defaultViewport: 'ipad10p', }},
834 ร— 112
iPad Pro 11-inConfigures the iPad Pro (11-inch) as a device for the Viewport addon.
parameters: { viewport: { defaultViewport: 'ipad11p', }},
834 ร— 1194
iPad Pro 12.9-inSets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'ipad12p', }},
1024 ร— 1366
TabletEnabled by default.
Configures a standard form factor tablet device to be used by the Viewport addon.
parameters: { viewport: { defaultViewport: 'tablet', }},
834 ร— 1112
.storybook/preview.ts
// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: {
        ...INITIAL_VIEWPORTS,
        ...MINIMAL_VIEWPORTS,
      },
      defaultViewport: 'iphone14promax',
    },
  },
};
 
export default preview;

The generic devices are enabled by default as they are the most common for testing responsive UIs. You don't need to include them in your configuration if you want to use them. For the implementation details, see the source code for the Viewport addon.

Add new devices

If you have either a specific viewport or a list of viewports that you need to use, you can modify your .storybook/preview.js file and include them:

.storybook/preview.js|ts
const customViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};

Make the following changes to use them in your Storybook:

.storybook/preview.ts
// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    viewport: { viewports: customViewports },
  },
};
 
export default preview;

Once you start Storybook, you'll see your new viewports and devices.

You can add these two to another list of viewports if needed.

For instance, if you want to use these two with the minimal set of viewports, you can do it like so:

.storybook/preview.ts
// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
const customViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: {
        ...MINIMAL_VIEWPORTS,
        ...customViewports,
      },
    },
  },
};
 
export default preview;

Both viewports (Kindle Fire 2 and Kindle Fire HD) will feature in the list of devices by merging them into the MINIMAL_VIEWPORTS.

Configuring per component or story

In some cases, it's not practical for you to use a specific visual viewport on a global scale, and you need to adjust it to an individual story.

Update your story through parameters to include your viewports at a component level or for a specific story:

MyComponent.stories.ts|tsx
import type { Meta, StoryObj } from '@storybook/react';
 
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  parameters: {
    //๐Ÿ‘‡ The viewports object from the Essentials addon
    viewport: {
      //๐Ÿ‘‡ The viewports you want to use
      viewports: INITIAL_VIEWPORTS,
      //๐Ÿ‘‡ Your own default viewport
      defaultViewport: 'iphone6',
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const MyStory: Story = {
  parameters: {
    viewport: {
      defaultViewport: 'iphonex',
    },
  },
};

Keyboard shortcuts

  • Previous viewport: shift + v
  • Next viewport: v
  • Reset viewport: alt + v

If you need, you can edit them on the shortcuts page.

API

Parameters

This addon contributes the following parameters to Storybook, under the viewport namespace:

defaultOrientation

Type: 'portrait' | 'landscape'

Default: 'portrait'

Specifies the default orientation used when viewing a story.

defaultViewport

Type: string

Specifies the default viewport used when viewing a story. Must match a key in the viewports object.

disable

Type: boolean

Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could then be re-enabled by setting it to false at the meta (component) or story level.

viewports

Type:

{
  [key: string]: {
    name: string,
    styles: { height: string, width: string },
    type: 'desktop' | 'mobile' | 'tablet',
  },
};

Specify the available viewports. The key is used to reference the viewport and the value is an object to define it. See usage example, above. The width and height values must include the unit, e.g. '320px'.

Exports

This addon contributes the following exports to Storybook:

import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewports';

INITIAL_VIEWPORTS

Type: object

The default set of viewports provided by the Viewport addon, listed above.

MINIMAL_VIEWPORTS

Type: object

A minimal set of viewports provided by the Viewport addon, listed below:

DeviceDescriptionDimensions
(wร—h, px)
Small mobileA small mobile device size
parameters: { viewport: { defaultViewport: 'mobile1', }},
320 ร— 568
Large mobileA large mobile device size
parameters: { viewport: { defaultViewport: 'mobile2', }},
414 ร— 896
TabletA tablet device size
parameters: { viewport: { defaultViewport: 'tablet', }},
834 ร— 1112