Connecting a Storybook Story to a Component Container
  • 09 Feb 2023
  • 6 Minutes to read
  • Dark
    Light

Connecting a Storybook Story to a Component Container

  • Dark
    Light

Article summary

The Live Components feature is currently limited to Enterprise users on a DSM Enterprise plan. Learn more about DSM Enterprise. 

After you have created a component container in DSM, it's time to connect the component to your Storybook story.

Obtaining the component container ID

To connect a Storybook story to its component container, you'll need to add the DSM component container ID in the third parameter of the options object of the story.

To find the component container ID:

  1. Open your design system documentation site and navigate to your component.
  2. Click the appropriate code tab (React, Vue, Angular, or HTML).
    Note: If you didn't add a code tab while creating a component container, you can do so by clicking Add tab and selecting the appropriate framework.
  3. Scroll to the Integration details section and copy the component container ID.
Demonstration of the steps for finding a DSM component container ID.

Adding IDs to different frameworks

Tip: You can see examples of DSM-connected stories in the example component library project. You’ll notice in the example stories that we have added an optional version number. This specifies per-component versioning rather than per-library versioning. To learn more, check out this article: Versioning DSM Live Components

If you're following along in the example project, you can insert the ID for your specific component container.

In the following section, click the tab associated with your chosen framework, and use the example code snippet to add the DSM component container ID to the story.

React

For React stories, add the following code and insert your DSM component container ID:

import React from 'react';
import { storiesOf } from '@storybook/react';
import { Button } from './Button.jsx';

storiesOf('Button', module)
  .add(
    'with emoji',
    () => (
      <button>πŸ˜€ 😎 πŸ‘ πŸ’―</button>
    ),
    {
      'in-dsm': {
        id: '<dsm component="" container="" id="">' 
      } 
    }
  );

Adding in-dsm properties

This table shows all required and optional in-dsm properties for React.

PropertyDescriptionOptional/Required
idThis is the component container ID used to connect the story to DSMRequired
versionWith version you can specify the version of a component, overriding the library version. If version is not provided, the version from the nearest package.json file is used.Optional
versionFilePathYou can provide a path to a JSON file with a field version and extract the version of the component.Optional
componentThis allows you to set the main component of the story explicitly. This is useful in case the component is not the root-level component of the story.Optional
componentPathThis is the path to the component file. It overrides the built-in component file resolution. The component file is used to generate properties and descriptions to show in DSM.Optional

Vue

For Vue stories, add the following code and insert your DSM component container ID:

import Vue from 'vue';
import { storiesOf } from '@storybook/vue';
import MyButton from './Button.vue';

storiesOf('Button', module)
  .add(
    'with emoji',
    () => ({
      components: { MyButton },
      template: '<my-button>πŸ˜€ 😎 πŸ‘ πŸ’―</my-button>'
    }), 
    {
      'in-dsm': { 
        id: β€˜<dsm component="" container="" id="">’, 
        componentPath: './Button.vue' 
      }
    }
  );
</dsm>

Adding in-dsm properties

This table shows all required and optional in-dsm properties available for Vue.

PropertyDescriptionOptional/Required
idThis is the component container ID used to connect the story to DSMRequired
versionWith version you can specify the version of a component, overriding the library version. If version is not provided, the version from the nearest package.json file is used.Optional
versionFilePathYou can provide a path to a JSON file with a field version and extract the version of the component.Optional
componentThis allows you to set the main component of the story explicitly. This is useful in case the component is not the root-level component of the story.Optional
componentPathThis is the path to the component file. It overrides the built-in component file resolution. The component file is used to generate properties and descriptions to show in DSM.Required

Angular

For Angular stories, add the following code and insert your DSM component container ID:

import { storiesOf } from '@storybook/angular';
import { ButtonComponent } from '../app/button.component';
 
storiesOf('Button', module)
  .add(
    'with emoji',
    () => ({
      component: ButtonComponent,
      template: '', 
      props: {
        buttonText: 'πŸ˜€ 😎 πŸ‘ πŸ’―'
      }
    }),
    {
      'in-dsm': {
        id: '<dsm component="" container="" id="">',
        componentPath: '../app/button.component'
      }
    }
  );</dsm>

Adding in-dsm properties

This table shows all required and optional in-dsm properties available for Angular.

PropertyDescriptionOptional/Required
idThis is the component container ID used to connect the story to DSMRequired
versionWith version you can specify the version of a component, overriding the library version. If version is not provided, the version from the nearest package.json file is used.Optional
versionFilePathYou can provide a path to a JSON file with a field version and extract the version of the component.Optional
componentThis allows you to set the main component of the story explicitly. This is useful in case the component is not the root-level component of the story.Required*
componentPathThis is the path to the component file. It overrides the built-in component file resolution. The component file is used to generate properties and descriptions to show in DSM.Required

*For Angular, the component property is only optional if the story has a single root element. Otherwise, it is required.

HTML

For HTML stories, add the following code and insert your DSM component container ID:

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

storiesOf('Button', module)
  .add(
    'with text', 
    () => '<button class="dsm-btn">πŸ˜€ 😎 πŸ‘ πŸ’―</button>', {
      'in-dsm': {
        id: '<dsm component="" container="" id="">',
        docFilePath: '../components/button.docs.json'
      }
    }
  );</dsm>

DSM enables adding a properties table to HTML stories. DSM will generate the table based on the properties information provided in a JSON file through the docFilePath property. For details, refer to the JSON file in the DSM example library on GitHub.

Adding in-dsm properties

This table shows all required and optional in-dsm properties available for HTML.

PropertyDescriptionOptional/Required
idThis is the component container ID used to connect the story to DSMRequired
versionWith version you can specify the version of a component, overriding the library version. If version is not provided, the version from the nearest package.json file is used.Optional
versionFilePathYou can provide a path to a JSON file with a field version and extract the version of the component.Optional
docFilePathThis is the path to a JSON file with metadata properties and descriptions about the component you want to show in DSM.Optional
containerClassThe class on the container wraps the code you want to use as sample code in DSM.Optional

After connecting your Storybook story to a DSM component container, it's finally time to publish your Storybook story to DSM.

Adding multiple framework tabs for a component

You can connect more than one Storybook project to a component, where each project uses a different framework (e.g., React, Vue, etc.). Each story will appear in the corresponding framework tab of the component container it’s connected to.

Additional notes

Here are a few things to note when connecting Storybook to a DSM component:

  • Any Storybook addons that are configured for your connected stories will also appear in DSM. This is helpful if you want to use features like Knobs in DSM. For a list of available addons, check out the Storybook Addon Gallery.
  • If you’d like to showcase different examples per component, you can connect multiple stories to the same component container. To do so, use the same component container ID for each story you connect to DSM.
    Note: Currently, it's not possible to simultaneously connect multiple component containers to a single Storybook story. If this is functionality you'd like to have in the future, please contact InVision Support and share your feedback with us.
  • With the release of Storybook v5.2, Storybook introduced Component Story Format (CSF). DSM fully supports this feature. For more information, visit the official CSF documentation. To view an example of a story written in Component Story Format, check out our example library on Github.

Was this article helpful?