Hierarchy #

You can customize the story explorer tree.

Using the title #

By default, Histoire uses the title of your stories to create the hierarchy. If you want to put a story in a specific folder or subfolder, just write the path as the title of your Story.

<Hst.Story title="Folder/Sub Folder/My story" >
  <!-- Your story goes here -->
</Hst.Story>

Using the file path #

If you want to use the real path of your story files, you can change that in your Histoire configuration file.

// histoire.config.ts

export default defineConfig({
  tree: {
    file: 'path',
  },
})

Custom logic #

If you want a custom hierarchy, you can define your own function that takes an object with the title and the path of your story as an argument, and returns an array of string being the path of your story in the app.

// histoire.config.ts

export default defineConfig({
  tree: {
    file: ({ title, path }) => title.split('/'), // equivalent to default behavior
  },
})

Sorting #

By default, files and stories are sorted by ascending order. But you might want to sort things differently, for example display some stories at the beginning. You can do so by providing a sorting function in your configuration file.

// histoire.config.ts

export default defineConfig({
  tree: {
    order: (a, b) => a.localeCompare(b), // equivalent to default behavior
  },
})

Groups #

Sometimes, you might have additional organization needs for the stories. Besides folders, Histoire also provides groups, which are little different:

• expanded by default
• only root level
• manual order
• independant from the hierarchy defined thanks to tree.file (see above)

You can define groups in your configuration with the groups property. It's an array of group objects with the following properties:

• title: the title of the group (use an empty string to have an untoggable group)
• id (optional): the id of the group, useful to reference it using the Story group prop
• include (optional): function that takes a file object [1] and returns a boolean, true if the file should be included in the group.

[1]: the file objects have the following properties:

• title: the title of the story
• path: the path of the story file

The stories are distributed in groups according to the following rules in this order:

• group prop of the <Story>
• include function of the groups, respecting the order in the groups array (a story may only appear in one group maximum)

Files not included in a group are always displayed after the last group.

Example:

// histoire.config.ts

export default defineConfig({
  tree: {
    groups: [
      {
        id: 'top',
        title: '', // No toggle
      },
      {
        title: 'My Group',
        include: file => /Code gen|Controls|Docs/.test(file.title),
      },
      {
        title: 'Components',
        include: file => !file.title.includes('Serialize'),
      },
      {
        title: 'Others',
        include: file => true,
      },
    ],
  },
})

You can use the group prop to reference a group in your stories using its id.

<Hst.Story group="top">
  This is a demo book using Svelte 3.
</Hst.Story>