0
# Storybook Addon Links
1

2
Storybook Links enables navigation between stories through programmatic links and declarative data attributes. It provides multiple integration approaches including event-driven navigation, URL generation, and React components for connecting related UI component states and scenarios.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-links
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/addon-links`
10

11
## Core Imports
12

13
```typescript
14
import { linkTo, hrefTo, withLinks, navigate } from "@storybook/addon-links";
15

16
// Constants are also available (commonly used for Storybook addons)
17
import EVENTS, { ADDON_ID, PARAM_KEY } from "@storybook/addon-links";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { linkTo, hrefTo, withLinks, navigate, ADDON_ID, PARAM_KEY } = require("@storybook/addon-links");
24
const EVENTS = require("@storybook/addon-links").default;
25
```
26

27
React component import:
28

29
```typescript
30
import LinkTo from "@storybook/addon-links/react";
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { linkTo, hrefTo, withLinks } from "@storybook/addon-links";
37

38
// Create event handler for button click
39
const handleClick = linkTo("Example", "Button");
40

41
// Get URL for a specific story
42
const storyUrl = await hrefTo("Example", "Button");
43

44
// Use decorator for automatic link handling
45
export const decorators = [withLinks];
46
```
47

48
## Architecture
49

50
Storybook Addon Links is built around several key components:
51

52
- **Navigation Functions**: Core functions (`linkTo`, `navigate`) for programmatic story navigation
53
- **URL Generation**: `hrefTo` function for generating story URLs without navigation
54
- **Decorator System**: `withLinks` decorator for automatic handling of data-attribute links
55
- **React Integration**: `LinkTo` component providing native link behavior for React projects
56
- **Event System**: Manager-side addon registration for handling navigation events
57

58
## Capabilities
59

60
### Programmatic Navigation
61

62
Core navigation functionality for creating event handlers that navigate between stories programmatically.
63

64
```typescript { .api }
65
/**
66
 * Creates event handler for programmatic story navigation
67
 * @param idOrTitle - Story ID or title, can be static string or dynamic function
68
 * @param nameInput - Story name, can be static string or dynamic function  
69
 * @returns Event handler function that navigates to the specified story
70
 */
71
function linkTo(
72
  idOrTitle: string | ((...args: any[]) => string),
73
  nameInput?: string | ((...args: any[]) => string)
74
): (...args: any[]) => void;
75

76
/**
77
 * Direct story navigation via channel events
78
 * @param params - Navigation parameters with story ID or kind/story combination
79
 */
80
function navigate(params: ParamsId | ParamsCombo): void;
81

82
interface ParamsId {
83
  storyId: StoryId;
84
}
85

86
interface ParamsCombo {
87
  kind?: StoryKind;
88
  title?: ComponentTitle;
89
  story?: StoryName;
90
  name?: StoryName;
91
}
92
```
93

94
### URL Generation
95

96
Generate URLs for stories without triggering navigation, useful for creating proper href attributes.
97

98
```typescript { .api }
99
/**
100
 * Generates URL for specific story
101
 * @param title - Story component title
102
 * @param name - Story name
103
 * @returns Promise resolving to story URL
104
 */
105
function hrefTo(title: ComponentTitle, name: StoryName): Promise<string>;
106
```
107

108
### Declarative Link Handling
109

110
Decorator that enables automatic link handling through HTML data attributes, eliminating the need for manual event binding.
111

112
```typescript { .api }
113
/**
114
 * Decorator that adds click listener for declarative link handling
115
 * Automatically handles elements with data-sb-kind and data-sb-story attributes
116
 */
117
const withLinks: StoryDecorator;
118
```
119

120
**Usage with data attributes:**
121

122
```html
123
<!-- Navigate to specific story -->
124
<button data-sb-kind="Example" data-sb-story="Button">
125
  Go to Button story
126
</button>
127

128
<!-- Navigate to story kind (first story) -->
129
<a data-sb-kind="Components/Form">View Form Examples</a>
130
```
131

132
### React Component Integration
133

134
React component providing native link behavior while preventing page reloads, ideal for story navigation within React applications.
135

136
```typescript { .api }
137
interface Props {
138
  kind?: StoryKind;
139
  title?: ComponentTitle; 
140
  story?: StoryName;
141
  name?: StoryName;
142
  children: ReactNode;
143
}
144

145
interface State {
146
  href: string;
147
}
148

149
class LinkTo extends React.PureComponent<Props, State>;
150
```
151

152
[React LinkTo Component](./react-component.md)
153

154
## Types
155

156
```typescript { .api }
157
type ComponentTitle = string;
158
type StoryId = string;
159
type StoryKind = string;
160
type StoryName = string;
161
type ReactNode = React.ReactNode;
162

163
interface ParamsId {
164
  storyId: StoryId;
165
}
166

167
interface ParamsCombo {
168
  kind?: StoryKind;
169
  title?: ComponentTitle;
170
  story?: StoryName;
171
  name?: StoryName;
172
}
173

174
// Note: React types need to be imported from React
175
// import type { ReactNode } from 'react';
176
type ReactNode = React.ReactNode;
177
```
178

179
## Constants
180

181
```typescript { .api }
182
/**
183
 * Addon identifier constant
184
 */
185
const ADDON_ID: string;
186

187
/**
188
 * Parameter key for addon configuration
189
 */
190
const PARAM_KEY: string;
191

192
/**
193
 * Event names object for addon communication
194
 * Default export containing NAVIGATE, REQUEST, and RECEIVE event names
195
 */
196
interface EventsObject {
197
  NAVIGATE: string;
198
  REQUEST: string;
199
  RECEIVE: string;
200
}
201

202
const EVENTS: EventsObject;
203
```