Adds deeper Storybook story sorting and story order control with wildcards.
npm install storybook-deeper-sort
!npm
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.
- 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
- Compatibility matrix
- Why
- Installation
- Quick start
- Options
- License
Storybook's native order array provides only two levels of control:
``js`
// .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
`bashnpm
npm install --save-dev storybook-deeper-sort
Quick start
1. Register your desired order in
.storybook/main.js.`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.`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.$3
Docs stories are listed before other story types. Disable this behaviour:
`js
deeperSortSetup(
["Pages", ["Admin", "Login", "Home"], "Components", ["", ["C", ""]]],
{ docsFirst: false }
);
`With
{ docsFirst: false } all stories are sorted solely by the provided
orderArray` without prioritising docs.MIT