How to Use the Storybook Links Addon to Connect Stories

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 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.

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 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.

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 lines 39-55.

withLinks: Declarative HTML Attributes

The withLinks decorator enables declarative linking via HTML data attributes. When registered in .storybook/preview.js, it listens for clicks on elements containing data-sb-kind and data-sb-story attributes.

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

export const decorators = [withLinks];

<!-- 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 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. It renders an anchor element, resolves the href via hrefTo, and handles navigation on click.

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 (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:

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):

<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 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.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}