Document withViewport decorator

addons/viewport/README.md

@@ -33,6 +33,24 @@ Setting this property to, let say `iphone6`, will make `iPhone 6` the default de
 ----
 A key-value pair of viewport's key and properties for all viewports to be displayed. Default is [`INITIAL_VIEWPORTS`](src/shared/index.js)
 
+## 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
+```js
+{
+  name: 'iphone6', // default viewport
+  onViewportChange({ viewport }) { // called whenever different viewport is selected from the dropdown
+
+  }
+}
+```
+
 ## Examples
 
 ### Basic Usage
@@ -120,3 +138,36 @@ configure({
   defaultViewport: 'iphone6'
 });
 ```
+
+## withViewport Decorator
+
+Change the default viewport for single/multiple/global stories, or listen to viewport selection changes
+
+```js
+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>
+  ));
+
+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 />);
+
+```