@storybook/addon-links

What is @storybook/addon-links?

The @storybook/addon-links package allows you to create links between your stories in Storybook. This can be used to navigate from one story to another, simulating user flows and providing a more connected and interactive experience when showcasing components.

What are @storybook/addon-links's main functionalities?

Link to another story

This feature allows you to create a link that navigates to a different story within Storybook. The 'linkTo' function takes two arguments: the first is the name of the component (or 'kind' in Storybook terminology), and the second is the specific story name. When the element is clicked, Storybook will navigate to the specified story.

{"<MyButton onClick={linkTo('Button', 'secondary')}>Next Story</MyButton>"}

Link with parameters

This feature extends the basic linking functionality by allowing you to pass additional parameters to the target story. These parameters can be used within the target story to modify its state or display certain data, making it a powerful tool for creating interactive and dynamic story flows.

{"<MyButton onClick={linkTo('Button', 'secondary', { userId: '12345' })}>User Profile</MyButton>"}

Other packages similar to @storybook/addon-links

@storybook/addon-actions

The @storybook/addon-actions package can be used to log actions performed on UI components within Storybook. While it doesn't provide direct linking between stories like @storybook/addon-links, it is often used in conjunction with links to provide a more interactive storytelling experience.

@storybook/addon-knobs

The @storybook/addon-knobs package allows you to add dynamic variables to your stories in Storybook. Similar to @storybook/addon-links, it enhances the interactivity of stories by allowing users to manipulate props in real-time. However, it does not provide functionality for linking between stories.

README

Story Links Addon

The Storybook Links addon can be used to create links that navigate between stories in Storybook.

Framework Support

Getting Started

Install this addon by adding the @storybook/addon-links dependency:

yarn add -D @storybook/addon-links

within .storybook/main.js:

export default {
  addons: ['@storybook/addon-links'],
};

Then you can import linkTo in your stories and use like this:

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

Have a look at the linkTo function:

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

linkTo('Toggle', 'off');
linkTo(
  () => 'Toggle',
  () => 'off'
);
linkTo('Toggle'); // Links to the first story in the 'Toggle' kind

With that, you can link an event in a component to any story in the Storybook.

• First parameter is the story kind name (what you named with title).
• Second (optional) parameter is the story name (what you named with exported name). If the second parameter is omitted, the link will point to the first story in the given kind.

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:

import { linkTo } from '@storybook/addon-links';
import LinkTo from '@storybook/addon-links/react';

export default {
  title: 'Select',
};

export const index = () => (
  <select value="Index" onChange={linkTo('Select', (e) => e.currentTarget.value)}>
    <option>index</option>
    <option>first</option>
    <option>second</option>
    <option>third</option>
  </select>
);
export const first = () => <LinkTo story="index">Go back</LinkTo>;
export const second = () => <LinkTo story="index">Go back</LinkTo>;
export const third = () => <LinkTo story="index">Go back</LinkTo>;

hrefTo function

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:

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

export default {
  title: 'Href',
};

export const log = () => {
  hrefTo('Href', 'log').then(action('URL of this story'));

  return <span>See action logger</span>;
};

withLinks decorator

withLinks decorator enables a declarative way of defining story links, using data attributes. Here is an example in React, but it works with any framework:

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

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

export const first = () => (
  <button data-sb-kind="OtherKind" data-sb-story="otherStory">
    Go to "OtherStory"
  </button>
);

LinkTo component (React only)

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. A React implementation of such a component can be imported from @storybook/addon-links package:

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

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.

<LinkTo
  kind="Toggle"
  story="off"
  target="_blank"
  title="link to second story"
  style={{ color: '#1474f3' }}
>
  Go to Second
</LinkTo>

To implement such a component for another framework, you need to add special handling for click event on native a element. See RoutedLink sources for reference.

Changelog

7.0.7 (April 24, 2023)

Bug Fixes

• Core: Pass parameters in SET_INDEX for docs entries #22154
• Addon-actions: Fix ESM by upgrading from uuid-browser to uuid #22037
• Addon-actions: Fix decorator type #22175
• Core: Add new tags to distinguish docs attachment #22120
• Core: Restore Docs useParameter using DOCS_PREPARED #22118

Maintenance

• CSF: Improve error message for bad default export #22190
• CLI: Add addon query-params to list of SB7 incompatible addons #22095
• UI: Add remount story shortcut #21401

Build

• Build: Fix lit sandboxes #22201
• Build: Fix sandbox publish script #22206