Storybook Deeper Sort

Fine-grained control of Storybook story sorting and story order.

Storybook's built-in options.storySort.order stops at two levels of nesting. storybook-deeper-sort lets you keep nesting arrays and even use wildcards, so large libraries can maintain a predictable, hand-crafted order.

Storybook 10 support is ESM-only and requires Node 18+. For Storybook 7–9, stay on storybook-deeper-sort@1.1.5. For Storybook 6, use storybook-deeper-sort@0.x.

Compatibility matrix

• Storybook 10: storybook-deeper-sort (ESM build, this branch)
• Storybook 7–9: storybook-deeper-sort@1.1.5
• Storybook 6: storybook-deeper-sort@0.x

Table of Contents

• Compatibility matrix
• Why
• Installation
• Quick start
• Options
• License

Why

Storybook's native order array provides only two levels of control:

// .storybook/preview.js
export const parameters = {
  options: {
    storySort: {
      order: ["Intro", "Pages", ["Home", "Login", "Admin"], "Components"],
    },
  },
};

The example above renders the following tree:

Intro/
├─ Welcome
Pages/
├─ Home
├─ Login
├─ Admin
Components/
├─ PackageA/
│  ├─ A
│  ├─ B
│  ├─ C
├─ PackageB/
│  ├─ A
│  ├─ B
│  ├─ C

Installation

# npm
npm install --save-dev storybook-deeper-sort

# yarn
yarn add --dev storybook-deeper-sort

Quick start

1. Register your desired order in .storybook/main.js.

// .storybook/main.js
import deeperSortSetup from "storybook-deeper-sort";

deeperSortSetup([
  "Intro",
  "Pages",
  ["Home", "Login", "Admin"],
  "Components",
  ["*", ["C"]],
]);

2. Use the generated sort function in .storybook/preview.js.

// .storybook/preview.js
const preview = {
  parameters: {
    options: {
      storySort: (a, b) => globalThis.deeperSort(a, b),
    },
  },
};

export default preview;

This setup produces the following ordering:

Intro/
├─ Welcome
Pages/
├─ Home
├─ Login
├─ Admin
Components/
├─ PackageA/
│  ├─ C
│  ├─ A
│  ├─ B
├─ PackageB/
│  ├─ C
│  ├─ A
│  ├─ B

Storybook v7 limits storySort to inline functions; exposing the function on globalThis allows us to reuse the configuration defined in main.js.

Options

deeperSortSetup(orderArray, config) accepts an optional config object.

docsFirst (default: true)

Docs stories are listed before other story types. Disable this behaviour:

deeperSortSetup(
  ["Pages", ["Admin", "Login", "Home"], "Components", ["*", ["C", "*"]]],
  { docsFirst: false }
);

With { docsFirst: false } all stories are sorted solely by the provided orderArray without prioritising docs.

License

MIT