Switch branches/tags
3407-repro 3972-options-knob-on-next 4848-new-example-format add-navbar add-polymer3-support add-react-error-overlay add-typings addon-api-concept addon-knob-vue-decoratorless addon-readme addon-resources core/remove-basic-config dd/babel-plugin-react-docgen-2 dependabot/npm_and_yarn/docs/gatsby-plugin-sharp-2.0.15 dependabot/npm_and_yarn/react-native-modal-datetime-picker-6.0.0 docs-v2-babel docs-v2-highlights docs-v2-monaco docs-v2 docs-v2.1 docs/add-versions-json docusaurus feature/add-navbar-refactor feature/add-navbar feature/custom-react-scripts fix/husky-deprecation fix/react-scripts-latest-fixture issue-3972-options-knob knobs-objects knobs/v2 master ndelange/hoisting-rn ndelangen/RN-fixattempt1 ndelangen/RN-fixattempt2 ndelangen/RN-fixattempt3 ndelangen/RN-fixattempt4 ndelangen/RN-fixattempt5 ndelangen/config-refactor ndelangen/docs-in-official ndelangen/hoisting-rn-attempt1 ndelangen/new-layoutsystem ndelangen/nicer-official-demo ndelangen/reactnext ndelangen/replace-html-webpack-plugin-v2 ndelangen/replace-html-webpack-plugin ndelangen/revert-tgz-file-dependencies ndelangen/temp2 new-docs next ng-dynamic-template oblador/fix-metro-flags-rn-57 on-device-addons on-device-ui-all-prs patch-1 patch-2 poc/addon-editor poc/liveedit-addon poc/liveedit-in-storysource-old poc/liveedit-in-storysource pr/JalilArfaoui/3909 pr/hipstersmoothie/4704 pr/kkemple/4482 pr/maacky/4856 presets/default-webpack react-native-on-device react-native/use-core-for-server redux-ui refactoring/remove-mantra-ui-overhaul-routing refactoring/remove-mantra-ui-overhaul refactoring/remove-mantra release/3.3 release/3.4 release/4.0 release/4.1-merged release/4.1 repro-instruction-update rn-tab-open shilman/angular-cli-example shilman/remove-withevents shilman/3.2.12-release snyk-fix-1n1s5x snyk-fix-iu4xwt snyk-fix-m3aahq snyk-fix-ncwvxj snyk-fix-pek1pb snyk-fix-q1x0k4 snyk-fix-rum9x7 snyk-fix-wmry50 storysource-with-deps tech/emotion10 tech/overhaul-ui-addon-notes-ts tech/overhaul-ui-store tech/overhaul-ui tech/try-github-workflos tmeasday/add-refs-to-stories tmeasday/check-react-access-3.4 tmeasday/embed-preview-context try-to-fix-master ts-migration/channels
Nothing to show
Find file History
Pull request Compare This branch is 17 commits ahead, 143 commits behind next.
Latest commit 03eaf5f Dec 13, 2018

README.md

Storybook Viewport Addon

Storybook Viewport Addon allows your stories to be displayed in different sizes and layouts in Storybook. This helps build responsive components inside of Storybook.

Framework Support

Screenshot

Installation

Install the following npm module:

npm i --save-dev @storybook/addon-viewport

or with yarn:

yarn add -D @storybook/addon-viewport

Then, add following content to .storybook/addons.js

import '@storybook/addon-viewport/register';

Configuration

Import and use the configureViewport function in your config.js file.

import { configureViewport } from '@storybook/addon-viewport';

defaultViewport : String


Setting this property to, let say iphone6, will make iPhone 6 the default device/viewport for all stories. Default is 'responsive' which fills 100% of the preview area.

viewports : Object


A key-value pair of viewport's key and properties (see Viewport definition below) for all viewports to be displayed. Default is INITIAL_VIEWPORTS

Viewport Model

{
  /**
   * name to display in the dropdown
   * @type {String}
   */
  name: 'Responsive',

  /**
   * Inline styles to be applied to the story (iframe).
   * styles is an object whose key is the camelCased version of the style name, and whose
   * value is the style’s value, usually a string
   * @type {Object}
   */
  styles: {
    width: '100%',
    height: '100%',
  },

  /**
   * type of the device (e.g. desktop, mobile, or tablet)
   * @type {String}
   */
  type: 'desktop',
}

Decorators

Sometimes you want to show collection of mobile stories, and you know those stories look horible on desktop (responsive), so you think you need to change the default viewport only for those?

Here is the answer, with withViewport decorator, you can change the default viewport of single, multiple, or all stories.

withViewport accepts either

  • A String, which represents the default viewport, or
  • An Object, which looks like
{
  name: 'iphone6', // default viewport
  onViewportChange({ viewport }) { // called whenever different viewport is selected from the dropdown

  }
}

Examples

Basic Usage

Simply import the Storybook Viewport Addon in the addons.js file in your .storybook directory.

import '@storybook/addon-viewport/register'

This will register the Viewport Addon to Storybook and will show up in the action area.

Use Custom Set of Devices

This will replace all previous devices with Kindle Fire 2 and Kindle Fire HD by simply calling configureViewport with the two devices as viewports in config.js file in your .storybook directory.

import { configureViewport } from '@storybook/addon-viewport';

const newViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px'
    }
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px'
    }
  }
};

configureViewport({
  viewports: newViewports
});

Add New Device

This will add both Kindle Fire 2 and Kindle Fire HD to the list of devices. This is acheived by making use of the exported INITIAL_VIEWPORTS property, by merging it with the new viewports and pass the result as viewports to configureViewport function

import { configureViewport, INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

const newViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px'
    }
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px'
    }
  }
};

configureViewport({
  viewports: {
    ...INITIAL_VIEWPORTS,
    ...newViewports
  }
});

Change The Default Viewport

This will make iPhone 6 the default viewport for all stories.

import { configureViewport } from '@storybook/addon-viewport';

configureViewport({
  defaultViewport: 'iphone6'
});

withViewport Decorator

Change the default viewport for single/multiple/global stories, or listen to viewport selection changes

import React from 'react';
import { storiesOf, addDecorator } from '@storybook/react';
import { withViewport } from '@storybook/addon-viewport';

// Globablly
addDecorator(withViewport('iphone5'));

// Collection
storiesOf('Decorator with string', module)
  .addDecorator(withViewport('iphone6'))
  .add('iPhone 6', () => (
    <h1>
      Do I look good on <b>iPhone 6</b>?
    </h1>
  ));

// Single
storiesOf('Parameterized story', module)
  .addDecorator(withViewport())
  .add(
    'iPad',
    () => (
      <h1>
        Do I look good on <b>iPad</b>?
      </h1>
    ),
    { viewport: 'ipad' }
  );

storiesOf('Decorator with object', module)
  .addDecorator(
    withViewport({
      onViewportChange({ viewport }) {
        console.log(`Viewport changed: ${viewport.name} (${viewport.type})`); // e.g. Viewport changed: iphone6 (mobile)
      },
    })
  )
  .add('onViewportChange', () => <MobileFirstComponent />);