storybook-addon-tanstack-router

Storybook addon that provides TanStack Router context for your stories. Configure route params, search params, and loader data declaratively.

Install

pnpm add -D storybook-addon-tanstack-router

Quick Start

Global decorator (recommended)

// .storybook/preview.ts
import { withTanStackRouter } from "storybook-addon-tanstack-router";

export const decorators = [withTanStackRouter];

Or register as an addon to auto-apply:

// .storybook/main.ts
export default {
  addons: ["storybook-addon-tanstack-router"],
};

Per-story configuration

import type { Meta, StoryObj } from "@storybook/react";
import { tanstackRouterParameters } from "storybook-addon-tanstack-router";
import { UserProfile } from "./UserProfile";

const meta: Meta<typeof UserProfile> = {
  component: UserProfile,
};
export default meta;

type Story = StoryObj<typeof UserProfile>;

export const Default: Story = {
  parameters: {
    tanstackRouter: tanstackRouterParameters({
      location: {
        path: "/users/$userId",
        params: { userId: "42" },
        search: { tab: "settings" },
      },
      loader: {
        data: { user: { id: "42", name: "Alice" } },
      },
    }),
  },
};

API

withTanStackRouter

A Storybook decorator that wraps stories with RouterProvider and a memory-based router. Apply globally or per-story.

tanstackRouterParameters(config)

Type-safe helper for configuring the addon. Returns the config as-is — it exists purely for TypeScript autocompletion.

config.location

Property	Type	Description
path	string	Route path pattern, e.g. '/users/$userId'
params	Record<string, string>	Route params to substitute into the path
search	Record<string, unknown>	Search/query params
hash	string	URL hash fragment

config.loader

Property	Type	Description
data	unknown	Static data returned by the route's loader

How It Works

The addon creates a minimal TanStack Router setup for each story:

1. Builds a route tree with createRootRoute + createRoute
2. Creates a createMemoryHistory with the configured location
3. Wraps the story in RouterProvider

This means your components can use all TanStack Router hooks (useParams, useSearch, useLoaderData, useNavigate, etc.) without any manual setup.

TanStack Start

This addon handles the Router side. If you're using TanStack Start (the full-stack framework), you also need to mock server-side code (server functions, SSR, Cloudflare workers) at the Vite config level. See the storybook-play-testing skill for a complete TanStack Start + Storybook setup guide.

License

MIT