# How to Use the Storybook Links Addon to Connect Stories

> Learn to use the Storybook Links addon to connect stories programmatically or declaratively. Integrate navigation easily with linkTo, hrefTo, withLinks, and LinkTo.

- Repository: [Storybook/storybook](https://github.com/storybookjs/storybook)
- Tags: how-to-guide
- Published: 2026-02-27

---

**The Storybook Links addon provides `linkTo`, `hrefTo`, `withLinks`, and the `LinkTo` component to navigate between stories programmatically or declaratively using HTML data attributes.**

The Links addon is a core Storybook utility that enables seamless navigation between isolated component states. According to the `storybookjs/storybook` source code, it works by emitting the `SELECT_STORY` event over the preview channel, allowing any framework to trigger story changes from the UI or code.

## Core APIs for Connecting Stories

The addon exposes several APIs in [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts) and React-specific components to handle different linking scenarios.

### linkTo: Programmatic Navigation

The `linkTo` function returns a click handler that navigates to a specific story. It accepts `kind` (title) and `story` (name) as strings or resolver functions, then delegates to the internal `navigate` helper.

```javascript
import { linkTo } from '@storybook/addon-links';

export default {
  title: 'Button',
};

export const first = () => (
  <button onClick={linkTo('Button', 'second')}>Go to “Second”</button>
);

export const second = () => (
  <button onClick={linkTo('Button', 'first')}>Go to “First”</button>
);

```

*Implementation reference*: [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts) lines 61-80.

### hrefTo: Generating Story URLs

Use `hrefTo` when you need the actual URL string rather than immediate navigation. This async function returns a Promise that resolves to the Storybook URL for the specified story, useful for logging or external systems.

```javascript
import { hrefTo } from '@storybook/addon-links';
import { action } from '@storybook/addon-actions';

export const logUrl = () => {
  hrefTo('Button', 'second').then(action('URL of this story'));
  return <span>Check the actions panel for the URL</span>;
};

```

*Implementation reference*: [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts) lines 39-55.

### withLinks: Declarative HTML Attributes

The `withLinks` decorator enables declarative linking via HTML data attributes. When registered in [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/preview.js), it listens for clicks on elements containing `data-sb-kind` and `data-sb-story` attributes.

```javascript
// .storybook/preview.js
import { withLinks } from '@storybook/addon-links';

export const decorators = [withLinks];

```

```html
<!-- In any story template -->
<button data-sb-kind="Button" data-sb-story="second">
  Go to “Second”
</button>

```

*Implementation reference*: [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts) lines 110-118.

### LinkTo Component: React Integration

For React users, the addon provides a pre-built `LinkTo` component in [`code/addons/links/src/react/components/link.tsx`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/react/components/link.tsx). It renders an anchor element, resolves the href via `hrefTo`, and handles navigation on click.

```javascript
import LinkTo from '@storybook/addon-links/react';

export default {
  title: 'Link',
};

export const first = () => <LinkTo story="second">Go to Second</LinkTo>;
export const second = () => <LinkTo story="first">Go to First</LinkTo>;

```

## How the Links Addon Works Under the Hood

The addon operates by emitting the `SELECT_STORY` event defined in `storybook/internal/core-events`. When `navigate` is called in [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts) (lines 36-38), it accesses the preview channel via `addons.getChannel()` and emits the event with the target story ID.

The `withLinks` decorator adds a global click listener (`linksListener`) that intercepts clicks on elements with `data-sb-kind` and `data-sb-story` attributes, preventing default browser navigation and calling `navigate` instead.

## Complete Code Examples

### Mixed Declarative and Programmatic Links

Combine `withLinks` decorator with `linkTo` for complex navigation scenarios:

```javascript
import { withLinks, linkTo } from '@storybook/addon-links';

export default {
  title: 'Mixed',
  decorators: [withLinks],
};

export const mixed = () => (
  <div>
    <button data-sb-kind="Button" data-sb-story="first">
      Declarative link
    </button>
    <button onClick={linkTo('Button', 'second')}>
      Imperative link
    </button>
  </div>
);

```

### Framework-Agnostic HTML Links

Use data attributes in any template system (Vue, Angular, Svelte, HTML):

```html
<a href="#" data-sb-kind="Components/Button" data-sb-story="Primary">
  View Primary Button
</a>

```

Ensure the `withLinks` decorator is registered in [`.storybook/preview.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/preview.js) for this to function.

## Summary

- The **Storybook Links addon** enables navigation between stories via the `SELECT_STORY` event emitted on the preview channel.
- **`linkTo`** provides imperative navigation through click handlers defined in [`code/addons/links/src/utils.ts`](https://github.com/storybookjs/storybook/blob/main/code/addons/links/src/utils.ts).
- **`hrefTo`** asynchronously generates Storybook URLs for external linking or logging purposes.
- **`withLinks`** offers declarative navigation via HTML data attributes (`data-sb-kind`, `data-sb-story`).
- **`LinkTo`** delivers a ready-to-use React component for anchor-based navigation.

## Frequently Asked Questions

### How do I install the Storybook Links addon?

The Links addon is included by default in Storybook 6.0 and later. If you need to install it manually, run `npm install @storybook/addon-links` and add `'@storybook/addon-links'` to the `addons` array in your [`.storybook/main.js`](https://github.com/storybookjs/storybook/blob/main/.storybook/main.js) configuration file.

### Can I use the Links addon with non-React frameworks?

Yes. While the `LinkTo` component is React-specific, the `linkTo` function and `withLinks` decorator work with any framework Storybook supports, including Vue, Angular, Svelte, and plain HTML. The `withLinks` decorator specifically uses standard DOM APIs to intercept clicks on elements with data attributes.

### What is the difference between `linkTo` and `hrefTo`?

`linkTo` returns a function that immediately triggers navigation to the target story when invoked, making it ideal for click handlers. `hrefTo` returns a Promise that resolves to the URL string for the story, which is useful when you need the URL itself—for example, to display it in the UI, log it to analytics, or open it in a new tab programmatically.

### How does the `withLinks` decorator handle navigation?

The `withLinks` decorator registers a global click listener on the document that checks for `data-sb-kind` and `data-sb-story` attributes on clicked elements. When found, it prevents the default browser navigation and calls the internal `navigate` function, which emits the `SELECT_STORY` event on the Storybook preview channel to switch the active story.