Storybook Deeper Sort
Provides more flexibility and more levels of control to story sort.
Note: This package is compatible with Storybook v7 and above. If you need compatibility with older versions of Storybook, please use deeperSort prior to v1.0.0.
Table of Contents
About
This package provides a function to sort stories with an API similar to the storybooks' order array but providing more than two levels of control.
Using the Storybook's built-in order array, you can have 2 levels of control:
// .storybook/preview.js
export const parameters = {
options: {
storySort: {
order: ["Intro", "Pages", ["Home", "Login", "Admin"], "Components"],
},
},
};
The code above would generate:
Intro/
├─ Welcome
Pages/
├─ Home
├─ Login
├─ Admin
Components/
├─ PackageA/
│ ├─ A
│ ├─ B
│ ├─ C
├─ PackageB/
│ ├─ A
│ ├─ B
│ ├─ C
To achieve deeper control over the story sort order, you can use the deeperSort
function provided by this package.
Using deeperSort
, the following levels of control become possible:
// .storybook/main.js
import deeperSortSetup from "storybook-deeper-sort";
deeperSortSetup([
"Intro",
"Pages",
["Home", "Login", "Admin"],
"Components",
["*", ["C"]],
]);
Here's an example of the sort order achieved using deeperSort
:
Intro/
├─ Welcome
Pages/
├─ Home
├─ Login
├─ Admin
Components/
├─ PackageA/
│ ├─ C
│ ├─ A
│ ├─ B
├─ PackageB/
│ ├─ C
│ ├─ A
│ ├─ B
Installation
# npm
npm i -D storybook-deeper-sort
# yarn
yarn add -D storybook-deeper-sort
Usage
- In your
.storybook/main.js
file, importdeeperSortSetup
function and call it with the desired order array. For example:
import deeperSortSetup from "storybook-deeper-sort";
deeperSortSetup([
"Intro",
"Pages",
["Home", "Login", "Admin"],
"Components",
["*", ["C"]],
]);
- In your
.storybook/preview.js
file, assign thestorySort
option to a function that usesglobalThis.deeperSort
for sorting the stories. For example:
const preview = {
parameters: {
options: {
storySort: (a, b) => globalThis.deeperSort(a, b),
},
},
};
export default parameters;
The deeperSort
function takes into account the order array provided in deeperSortSetup
to determine the sort order of your stories. It enables more levels of control, allowing you to specify custom sorting for different sections and even individual stories.
Please note that due to restrictions in Storybook v7, it's not possible to define the
storySort
function externally. The use ofglobalThis
allows us to access thedeeperSort
function from thepreview.js
file.
Options
The deeperSortSetup
function accepts an optional config
parameter that allows you to customize its behavior.
Currently, the only available option is docsFirst
. By default, deeperSort
prioritizes docs
, placing them before other story types.
To disable the prioritization of docs
, you can setdocsFirst
tofalse
:
// .storybook/main.js
import deeperSortSetup from "storybook-deeper-sort";
deeperSortSetup(
["Pages", ["Admin", "Login", "Home"], "Components", ["*", ["C", "*"]]],
{ docsFirst: false }
);
By setting { docsFirst: false }
, deeperSort
will sort all story types based on their order in the provided order array without giving special priority to docs
stories.