Viewports (legacy) for responsive UIs

🚨 The chromatic.viewports feature is now replaced by the new Modes API. With Modes, you can test your stories in various viewports and customize global settings. Additionally, you have the flexibility to define specific viewport heights for testing purposes.

To transition to the new API, please consult the migration guide.

UI components can respond to device width. Chromatic makes it easy to visual test these cases with the viewports parameter. This helps you define one or more viewport sizes to capture. Using viewports requires Storybook 4.0 or later.

Viewports for a story

To set a viewport, specify one or more screen widths to the chromatic.viewports parameter:

// MyComponent.stories.js|jsx

import { MyComponent } from "./MyComponent";

export default {
  component: MyComponent,
  title: "MyComponent",
};

export const StoryName = {
  args: {
    with: "props",
  },
  parameters: {
    //👇 Defines a list of viewport widths for a single story to be captured in Chromatic.
    chromatic: { viewports: [320, 1200] },
  },
};

When Chromatic captures your story, it will create two snapshots on your build, with the browser set at each viewports. These viewports will be treated separately, with independent baselines and distinct approvals.

Viewports for all stories of a component

Thanks to Storybook’s built in parameter API, you can also target viewport at a group of stories or even your entire Storybook. To apply a set of viewports to all component’s stories, use:

// MyComponent.stories.js|jsx

import { MyComponent } from "./MyComponent";

export default {
  component: MyComponent,
  title: "MyComponent",
  parameters: {
    //👇 Defines a list of viewport widths applied to all stories of a component to be captured in Chromatic.
    // Note only widths are supported, to control width and height, use the modes api
    // https://www.chromatic.com/docs/viewports
    chromatic: { viewports: [320, 1200] },
  },
};

export const StoryName = {
  args: {
    with: "props",
  },
};

export const SecondStoryName = {
  args: {
    with: "other-props",
  },
};

Frequently asked questions

What viewports can I choose?

A viewport can be any whole number between 200 and 2560 pixels. The maximum number of pixels per snapshot is 25,000,000.

Can I control the height of the viewport?

It is not possible to control height with this legacy API. However, you can achieve it using the Modes API.

How do I assign viewports globally to all components in my Storybook?

Use modes and set a project level mode.

If you’re still using the legacy API, then assign viewports for the entire Storybook using parameters in your .storybook/preview.js:

// .storybook/preview.js

const preview = {
  parameters: {
    //👇 Defines a list of viewport widths applied globally to all stories.
    // Note only widths are supported, to control width and height, use the modes api
    // https://www.chromatic.com/docs/viewports
    chromatic: { viewports: [320, 1200] },
  },
};

export default preview;