Permalink
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 Copy path
Fetching contributors…
Cannot retrieve contributors at this time
195 lines (136 sloc) 6 KB
id title
api
API

Core Addon API

This is the core addon API. This is how to get the addon API:

import addonAPI from '@storybook/addons';

Have a look at the API methods for more details:

addonAPI.getChannel()

Get an instance to the channel where you can communicate with the manager and the preview. You can find this in both the addon register code and in your addon’s wrapper component (where used inside a story).

It has a NodeJS EventEmitter compatible API. So, you can use it to emit events and listen for events.

addonAPI.register()

This method allows you to register an addon and get the storybook API. You can do this only in the Manager App. See how we can use this:

import addonAPI from '@storybook/addons';

// Register the addon with a unique name.
addonAPI.register('my-organisation/my-addon', storybookAPI => {});

Now you'll get an instance to our StorybookAPI. See the api docs for Storybook API regarding using that.

addonAPI.addPanel()

This method allows you to add a panel to Storybook. (Storybook's Action Logger is a panel). You can do this only in the Manager App. See how you can use this method:

import addonAPI from '@storybook/addons';

const MyPanel = () => <div>This is a panel.</div>;

// give a unique name for the panel
addonAPI.addPanel('my-organisation/my-addon/panel', {
  title: 'My Addon',
  render: () => <MyPanel />,
});

As you can see, you can set any React Component as the panel. Currently, it's just a text. But you can do anything you want. You should specify the panel title. It could be a plain text or a function returning any React Component.

You also pass the channel and the Storybook API into that. See:

import addonAPI from '@storybook/addons';

import Notes from './notes';

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  // Also need to set a unique name to the panel.
  addonAPI.addPanel('my-organisation/my-addon/panel', {
    title: 'Notes',
    render: () => <Notes channel={addonAPI.getChannel()} api={storybookAPI} />,
  });
});

Storybook API

Storybook API allows you to access different functionalities of Storybook UI. You can move an instance to the Storybook API when you register an addon.

Let's have a look at API methods.

storybookAPI.selectStory()

With this method, you can select a story via an API. This method accepts two parameters.

  1. story kind name
  2. story name (optional)

Let's say you've got a story like this:

import { storiesOf } from '@storybook/react';

storiesOf('heading', module).add('with text', () => <h1>Hello world</h1>);

This is how you can select the above story:

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.selectStory('heading', 'with text');
});

storybookAPI.selectInCurrentKind()

Same as selectStory, but accepts a story inside current kind as the only parameter:

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.selectInCurrentKind('with text');
});

storybookAPI.setQueryParams()

This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you set query params.

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.setQueryParams({
    abc: 'this is abc',
    bbc: 'this is bbc',
  });
});

If you need to remove a query param, use null for that. For an example, let's say we need to remove bbc query param. This is how we do it:

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.setQueryParams({
    bbc: null,
  });
});

storybookAPI.getQueryParam()

This method allows you to get a query param set by above API setQueryParams. For example, let's say we need to get the bbc query param. Then this how we do it:

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.getQueryParam('bbc');
});

storybookAPI.getUrlState(overrideParams)

This method allows you to get application url state with some changed params. For example, if you want to get a link to a particular story:

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  const href = storybookAPI.getUrlState({
    selectedKind: 'kind',
    selectedStory: 'story',
  }).url;
});

storybookAPI.onStory(fn)

This method allows you to register a handler function which will be called whenever the user navigates between stories.

addonAPI.register('my-organisation/my-addon', storybookAPI => {
  storybookAPI.onStory((kind, story) => console.log(kind, story));
});

makeDecorator API

The makeDecorator API can be used to create decorators in the style of the official addons easily. Use it like so:

import { makeDecorator } from '@storybook/addons';

export makeDecorator({
  name: 'withSomething',
  parameterName: 'something',
  wrapper: (storyFn, context, { parameters }) => {
    // Do something with `parameters`, which are set via { something: ... }

    // Note you may alter the story output if you like, although generally that's
    // not advised
    return storyFn(context);
  }
})

The options to makeDecorator are:

  • name: The name of the export (e.g. withNotes)
  • parameterName: The name of the parameter your addon uses. This should be unique.
  • skipIfNoParametersOrOptions: Don't run your decorator if the user hasn't set options (via .addDecorator(withFoo(options)))) or parameters (.add('story', () => <Story/>, { foo: 'param' }), or .addParameters({foo: 'param'})).
  • allowDeprecatedUsage: support the deprecated "wrapper" usage (.add('story', () => withFoo(options)(() => <Story/>))).
  • wrapper: your decorator function. Takes the storyFn, context, and both the options and parameters (as defined in skipIfNoParametersOrOptions above).

Note if the parameters to a story include { foo: {disable: true } } (where foo is the parameterName of your addon), your decorator will note be called.