or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdreact-component.md
tile.json

tessl/npm-storybook--addon-links

Storybook addon that enables navigation between stories through programmatic links and declarative data attributes.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/addon-links@9.1.x

To install, run

npx @tessl/cli install tessl/npm-storybook--addon-links@9.1.0

index.mddocs/

Storybook Addon Links

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.

Package Information

  • Package Name: @storybook/addon-links
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @storybook/addon-links

Core Imports

import { linkTo, hrefTo, withLinks, navigate } from "@storybook/addon-links";

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

For CommonJS:

const { linkTo, hrefTo, withLinks, navigate, ADDON_ID, PARAM_KEY } = require("@storybook/addon-links");
const EVENTS = require("@storybook/addon-links").default;

React component import:

import LinkTo from "@storybook/addon-links/react";

Basic Usage

import { linkTo, hrefTo, withLinks } from "@storybook/addon-links";

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

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

// Use decorator for automatic link handling
export const decorators = [withLinks];

Architecture

Storybook Addon Links is built around several key components:

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

Capabilities

Programmatic Navigation

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

/**
 * Creates event handler for programmatic story navigation
 * @param idOrTitle - Story ID or title, can be static string or dynamic function
 * @param nameInput - Story name, can be static string or dynamic function  
 * @returns Event handler function that navigates to the specified story
 */
function linkTo(
  idOrTitle: string | ((...args: any[]) => string),
  nameInput?: string | ((...args: any[]) => string)
): (...args: any[]) => void;

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

interface ParamsId {
  storyId: StoryId;
}

interface ParamsCombo {
  kind?: StoryKind;
  title?: ComponentTitle;
  story?: StoryName;
  name?: StoryName;
}

URL Generation

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

/**
 * Generates URL for specific story
 * @param title - Story component title
 * @param name - Story name
 * @returns Promise resolving to story URL
 */
function hrefTo(title: ComponentTitle, name: StoryName): Promise<string>;

Declarative Link Handling

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

/**
 * Decorator that adds click listener for declarative link handling
 * Automatically handles elements with data-sb-kind and data-sb-story attributes
 */
const withLinks: StoryDecorator;

Usage with data attributes:

<!-- Navigate to specific story -->
<button data-sb-kind="Example" data-sb-story="Button">
  Go to Button story
</button>

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

React Component Integration

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

interface Props {
  kind?: StoryKind;
  title?: ComponentTitle; 
  story?: StoryName;
  name?: StoryName;
  children: ReactNode;
}

interface State {
  href: string;
}

class LinkTo extends React.PureComponent<Props, State>;

React LinkTo Component

Types

type ComponentTitle = string;
type StoryId = string;
type StoryKind = string;
type StoryName = string;
type ReactNode = React.ReactNode;

interface ParamsId {
  storyId: StoryId;
}

interface ParamsCombo {
  kind?: StoryKind;
  title?: ComponentTitle;
  story?: StoryName;
  name?: StoryName;
}

// Note: React types need to be imported from React
// import type { ReactNode } from 'react';
type ReactNode = React.ReactNode;

Constants

/**
 * Addon identifier constant
 */
const ADDON_ID: string;

/**
 * Parameter key for addon configuration
 */
const PARAM_KEY: string;

/**
 * Event names object for addon communication
 * Default export containing NAVIGATE, REQUEST, and RECEIVE event names
 */
interface EventsObject {
  NAVIGATE: string;
  REQUEST: string;
  RECEIVE: string;
}

const EVENTS: EventsObject;