UNPKG

4.2 kBMarkdownView Raw
1# Story Links Addon
2
3The Storybook Links addon can be used to create links that navigate between stories in [Storybook](https://storybook.js.org).
4
5[Framework Support](https://storybook.js.org/docs/react/api/frameworks-feature-support)
6
7## Getting Started
8
9Install this addon by adding the `@storybook/addon-links` dependency:
10
11```sh
12yarn add -D @storybook/addon-links
13```
14
15within `.storybook/main.js`:
16
17```js
18export default {
19 addons: ['@storybook/addon-links'],
20};
21```
22
23Then you can import `linkTo` in your stories and use like this:
24
25```js
26import { linkTo } from '@storybook/addon-links';
27
28export default {
29 title: 'Button',
30};
31
32export const first = () => <button onClick={linkTo('Button', 'second')}>Go to "Second"</button>;
33export const second = () => <button onClick={linkTo('Button', 'first')}>Go to "First"</button>;
34```
35
36Have a look at the linkTo function:
37
38```js
39import { linkTo } from '@storybook/addon-links';
40
41linkTo('Toggle', 'off');
42linkTo(
43 () => 'Toggle',
44 () => 'off'
45);
46linkTo('Toggle'); // Links to the first story in the 'Toggle' kind
47```
48
49With that, you can link an event in a component to any story in the Storybook.
50
51- First parameter is the story kind name (what you named with `title`).
52- Second (optional) parameter is the story name (what you named with `exported name`).
53 If the second parameter is omitted, the link will point to the first story in the given kind.
54
55You can also pass a function instead for any of above parameter. That function accepts arguments emitted by the event and it should return a string:
56
57```js
58import { linkTo } from '@storybook/addon-links';
59import LinkTo from '@storybook/addon-links/react';
60
61export default {
62 title: 'Select',
63};
64
65export const index = () => (
66 <select value="Index" onChange={linkTo('Select', (e) => e.currentTarget.value)}>
67 <option>index</option>
68 <option>first</option>
69 <option>second</option>
70 <option>third</option>
71 </select>
72);
73export const first = () => <LinkTo story="index">Go back</LinkTo>;
74export const second = () => <LinkTo story="index">Go back</LinkTo>;
75export const third = () => <LinkTo story="index">Go back</LinkTo>;
76```
77
78## hrefTo function
79
80If you want to get an URL for a particular story, you may use `hrefTo` function. It returns a promise, which resolves to string containing a relative URL:
81
82```js
83import { hrefTo } from '@storybook/addon-links';
84import { action } from '@storybook/addon-actions';
85
86export default {
87 title: 'Href',
88};
89
90export const log = () => {
91 hrefTo('Href', 'log').then(action('URL of this story'));
92
93 return <span>See action logger</span>;
94};
95```
96
97## withLinks decorator
98
99`withLinks` decorator enables a declarative way of defining story links, using data attributes.
100Here is an example in React, but it works with any framework:
101
102```js
103import { withLinks } from '@storybook/addon-links';
104
105export default {
106 title: 'Button',
107 decorators: [withLinks],
108};
109
110export const first = () => (
111 <button data-sb-kind="OtherKind" data-sb-story="otherStory">
112 Go to "OtherStory"
113 </button>
114);
115```
116
117## LinkTo component (React only)
118
119One possible way of using `hrefTo` is to create a component that uses native `a` element, but prevents page reloads on plain left click, so that one can still use default browser methods to open link in new tab.
120A React implementation of such a component can be imported from `@storybook/addon-links` package:
121
122```js
123import LinkTo from '@storybook/addon-links/react';
124
125export default {
126 title: 'Link',
127};
128
129export const first = () => <LinkTo story="second">Go to Second</LinkTo>;
130export const second = () => <LinkTo story="first">Go to First</LinkTo>;
131```
132
133It accepts all the props the `a` element does, plus `story` and `kind`. It the `kind` prop is omitted, the current kind will be preserved.
134
135```js
136<LinkTo
137 kind="Toggle"
138 story="off"
139 target="_blank"
140 title="link to second story"
141 style={{ color: '#1474f3' }}
142>
143 Go to Second
144</LinkTo>
145```
146
147To implement such a component for another framework, you need to add special handling for `click` event on native `a` element. See [`RoutedLink` sources](https://github.com/storybookjs/storybook/blob/next/code/addons/links/src/react/components/RoutedLink.tsx) for reference.