Autogenerated all components overview page

[chbiel]

Summary

I an looking for an efficient way to create a component overview page, that lists all available components with the primary story as a preview.

I tried to find other discussions or issues but the keywords are hard to search :)
I also digged through the code to see if I can find APIs but was not successful.

See PoC below..

My questions:

• Is there a built in way to get a list of all available components? Maybe in one of the APIs?
• Is there a way to get the primary story of a stories import?
• Did I miss something and there are already solutions for my goal?

Additional information

I have a PoC ready, but it's very inefficient, takes long to load and increases the bundle size unnecessarily:

import { extractTitle } from '@storybook/addon-docs/blocks';
import { useEffect, useState } from 'react';

// Get all the story imports to iterate them later
const availableStoryImports = import.meta.glob('../../components/**/*.stories.tsx');

export const ComponentOverview: React.FC = () => {
  const [availableStories, setAvailableStories] = useState<[string, any][]>([]);

  useEffect(() => {
    // First we fetch all available stories from /index.json that is considered a stable API
    fetch('/index.json')
      .then((res) => res.json())
      .then((data) => data)
      // Then we create a mapping between the stories from /index.json and all imported stories from `availableStoryImports`
      // And filter them, to ensure we have stories that can really be rendered
      .then((components) => {
        Promise.all(
          Object.entries(availableStoryImports)
            .filter(([k]) =>
              Object.entries(components.entries)
                // TODO filtering for Playground, as a bad "Primary" story workaround
                .filter(([key, value]) => key.startsWith('components') && value.name === 'Playground')
                .some(([, e]) => k.includes(e.importPath.replace('./src', '')))
            )
            .map(async ([path, resolver]): Promise<[string, unknown]> => {
              return [path, await resolver()];
            })
        ).then((entries) => {
          setAvailableStories(entries);
        });
      });
  }, []);

  return (
    <>
      <div style={{ flexWrap: 'wrap', display: 'flex', gap: 20, padding: 20 }}>
        {availableStories.map(([, module]) => {
          const PlaygroundStoryComponent = module.default.component;

          const getStoryUrlKey = (title: string) =>
            title
              .split('/')
              .map((t) => t.trim().replaceAll(' ', '-'))
              .join('-')
              .toLowerCase();
          return (
            <div
              key={module.default.title}
              style={{
                display: 'flex',
                flexDirection: 'column',
                alignItems: 'center',
                width: 300,
                height: 300,
                border: '1px solid black',
                overflow: 'hidden',
              }}
              onClick={() => {
                window.parent.location.href = `/?path=/docs/${getStoryUrlKey(module.default.title)}--overview`;
              }}
            >
              <div
                style={{
                  pointerEvents: 'none',
                  flex: 1,
                  display: 'flex',
                  alignItems: 'center',
                  justifyContent: 'center',
                  maxHeight: '77%',
                }}
              >
                <PlaygroundStoryComponent {...module.default.args} />
              </div>
              <div
                style={{
                  height: '15%',
                  margin: '4px',
                  padding: 16,
                  flexShrink: 0,
                  borderTop: '2px solid black',
                  width: '100%',
                  boxSizing: 'border-box',
                }}
              >
                <span>{extractTitle(module.default.title)}</span>
              </div>
            </div>
          );
        })}
      </div>
    </>
  );
};

and using it in a MDX:

import { Title, Meta } from '@storybook/addon-docs/blocks';
import { ComponentOverview } from '../.storybook/doc-blocks/ComponentOverview';

<Meta title="Component Library Overview PoC" parameters={{ docs: { toc: false } }} />

<Title>Component Library Overview PoC</Title>

<ComponentOverview />

Will result in something like this:

But as said, loading is slow with many stories and it feels inefficient overall.
Are there APIs in storybook I could use to get a similar outcome?

Create a reproduction

No response

[dosubot[bot]]

Hi @chbiel! I'm Dosu and I’m helping the storybook team.

Storybook doesn't have a built-in overview page, but you can efficiently list all components and their stories using the story index (/index.json). This file contains metadata for every story, including its component (title), story name (name), and import path. You can fetch and parse this file to group stories by component and avoid loading all story modules upfront, which will help with performance and bundle size.

For identifying the "primary" story, Storybook's docs use the first story defined in each file as the primary one for previews (via the Primary Doc Block) — but this is a convention, not enforced by the API. If you want to follow Storybook's autodocs logic, you can either use the first story per component or look for a specific name like "Primary" or "Playground" if you use that convention in your codebase reference.

If you want more control, you can customize the docs template using the docs parameter or MDX templates to generate your own overview page reference. There was an attempt to add an "All UI" page to Storybook, but it was not merged reference.

For best performance, use /index.json to get the list of components and stories, then dynamically import only the modules you need for previews. Avoid globbing all stories at once. If you need to programmatically group stories by component, check out how Storybook's sidebar and internal APIs like transformStoryIndexToStoriesHash and getComponentLookupList work reference.

Let me know if you want code examples for grouping stories or customizing the docs page!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[chbiel]

@dosu most things you suggested are already implemented...
the PR was closed for reasons and used another approach then I do (actually solving the manual handling and autogenerating the overview).
only potential direction are the internal APIs but as you mentioned they are internal. To use them I would need access to the story/component index. is there a way, e.g. in plugins or so?

[dosubot[bot]]

There isn't a public runtime API for plugins/addons to access the internal story/component index directly—at runtime, your options are limited to fetching /index.json and processing it yourself, as you already do. However, Storybook does provide an experimental indexers API in main.js|ts that lets you customize how stories are indexed at build time. With custom indexers, you can influence what gets included in the story index, add metadata, or even generate stories from non-standard sources.

Internally, Storybook's manager and preview hold the story index in their store state and expose it to core modules, but this is not officially supported for external plugins and may break or be removed in future versions. If you want to hook into the index at runtime, you can listen for channel events like SET_INDEX in the manager context, but this is also considered internal and not stable for public use reference.

For most use cases, the recommended and stable approach is to fetch /index.json and process it as needed. If you need to change how the index is built, use the experimental indexers API at build time. If you have a specific use case that requires deeper integration, let me know and I can help dig into possible workarounds.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[chbiel]

@dosu ok, I would give the experimental index a try, but there is no way documented how I can access a custom index. Without a way to access an index the API is not helpful...

[dosubot[bot]]

You're right—there isn't a documented or supported way to access a custom story index directly at runtime. The only stable method is to fetch and process /index.json, which will include any entries generated by your custom indexers. The experimental indexers API lets you customize how the index is built at build time, but it doesn't expose a separate runtime API or direct access to the index beyond this endpoint docs.

If you need to work with your custom index, you'll need to read /index.json and filter/group the entries as needed for your overview page. If you have a specific scenario or need more control, let me know—there may be workarounds depending on your setup.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[chbiel]

@dosu ok, but wouldnt that be a nice feature to allow read access to the current story / component index at runtime?

[dosubot[bot]]

Yes, exposing the story/component index at runtime could unlock a lot of flexibility for addons, plugins, and custom pages—like building efficient overview pages or dynamic navigation. Right now, Storybook only exposes this data via the /index.json endpoint, and while the manager API does hold the index in memory, it's not a public or stable API for external use and is subject to change without notice reference.

There aren't any recent feature requests or plans to make this a public runtime API. If you have a concrete use case, sharing it (and the pain points with current workarounds) would help the maintainers understand the demand and shape a possible API. Exposing the index at runtime would need careful consideration for stability and security, but your scenario is a strong example of why it could be valuable.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}