- 09 Feb 2023
- 6 Minutes to read
- DarkLight
Connecting a Storybook Story to a Component Container
- Updated on 09 Feb 2023
- 6 Minutes to read
- DarkLight
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:
- Open your design system documentation site and navigate to your component.
- 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.
- Scroll to the Integration details section and copy the component container ID.
Adding IDs to different frameworks
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.
Property | Description | Optional/Required |
---|---|---|
id | This is the component container ID used to connect the story to DSM | Required |
version | With 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 |
versionFilePath | You can provide a path to a JSON file with a field version and extract the version of the component. | Optional |
component | This 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 |
componentPath | This 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.
Property | Description | Optional/Required |
---|---|---|
id | This is the component container ID used to connect the story to DSM | Required |
version | With 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 |
versionFilePath | You can provide a path to a JSON file with a field version and extract the version of the component. | Optional |
component | This 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 |
componentPath | This 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.
Property | Description | Optional/Required |
---|---|---|
id | This is the component container ID used to connect the story to DSM | Required |
version | With 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 |
versionFilePath | You can provide a path to a JSON file with a field version and extract the version of the component. | Optional |
component | This 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* |
componentPath | This 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.
Property | Description | Optional/Required |
---|---|---|
id | This is the component container ID used to connect the story to DSM | Required |
version | With 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 |
versionFilePath | You can provide a path to a JSON file with a field version and extract the version of the component. | Optional |
docFilePath | This is the path to a JSON file with metadata properties and descriptions about the component you want to show in DSM. | Optional |
containerClass | The 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.