1 | # Story Links Addon
|
2 |
|
3 | The 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 |
|
9 | Install this addon by adding the `@storybook/addon-links` dependency:
|
10 |
|
11 | ```sh
|
12 | yarn add -D @storybook/addon-links
|
13 | ```
|
14 |
|
15 | within `.storybook/main.js`:
|
16 |
|
17 | ```js
|
18 | export default {
|
19 | addons: ['@storybook/addon-links'],
|
20 | };
|
21 | ```
|
22 |
|
23 | Then you can import `linkTo` in your stories and use like this:
|
24 |
|
25 | ```js
|
26 | import { linkTo } from '@storybook/addon-links';
|
27 |
|
28 | export default {
|
29 | title: 'Button',
|
30 | };
|
31 |
|
32 | export const first = () => <button onClick={linkTo('Button', 'second')}>Go to "Second"</button>;
|
33 | export const second = () => <button onClick={linkTo('Button', 'first')}>Go to "First"</button>;
|
34 | ```
|
35 |
|
36 | Have a look at the linkTo function:
|
37 |
|
38 | ```js
|
39 | import { linkTo } from '@storybook/addon-links';
|
40 |
|
41 | linkTo('Toggle', 'off');
|
42 | linkTo(
|
43 | () => 'Toggle',
|
44 | () => 'off'
|
45 | );
|
46 | linkTo('Toggle'); // Links to the first story in the 'Toggle' kind
|
47 | ```
|
48 |
|
49 | With 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 |
|
55 | You 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
|
58 | import { linkTo } from '@storybook/addon-links';
|
59 | import LinkTo from '@storybook/addon-links/react';
|
60 |
|
61 | export default {
|
62 | title: 'Select',
|
63 | };
|
64 |
|
65 | export 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 | );
|
73 | export const first = () => <LinkTo story="index">Go back</LinkTo>;
|
74 | export const second = () => <LinkTo story="index">Go back</LinkTo>;
|
75 | export const third = () => <LinkTo story="index">Go back</LinkTo>;
|
76 | ```
|
77 |
|
78 | ## hrefTo function
|
79 |
|
80 | If 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
|
83 | import { hrefTo } from '@storybook/addon-links';
|
84 | import { action } from '@storybook/addon-actions';
|
85 |
|
86 | export default {
|
87 | title: 'Href',
|
88 | };
|
89 |
|
90 | export 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.
|
100 | Here is an example in React, but it works with any framework:
|
101 |
|
102 | ```js
|
103 | import { withLinks } from '@storybook/addon-links';
|
104 |
|
105 | export default {
|
106 | title: 'Button',
|
107 | decorators: [withLinks],
|
108 | };
|
109 |
|
110 | export 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 |
|
119 | One 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.
|
120 | A React implementation of such a component can be imported from `@storybook/addon-links` package:
|
121 |
|
122 | ```js
|
123 | import LinkTo from '@storybook/addon-links/react';
|
124 |
|
125 | export default {
|
126 | title: 'Link',
|
127 | };
|
128 |
|
129 | export const first = () => <LinkTo story="second">Go to Second</LinkTo>;
|
130 | export const second = () => <LinkTo story="first">Go to First</LinkTo>;
|
131 | ```
|
132 |
|
133 | It 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 |
|
147 | To 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.
|