Improve search bar with grouped results, filters and recently viewed stories

[StefanG1102]

Is your feature request related to a problem? Please describe.

As Storybooks grow, it can become difficult to quickly find and navigate between related components and stories.

Currently, search results focus mainly on individual matches. When searching for a component such as Button, I would expect to be able to easily see and navigate through its related stories, such as Default, Rainbow, or Danger.

It would also be useful to further narrow down search results based on story variants, tags, contexts, or recently viewed stories.

This is related to the search bar improvements discussed in #29010, but focuses more specifically on improving search results, filtering, and navigation.

Describe the solution you'd like

I would like to extend the Storybook search experience with a few related improvements:

1. Group related stories under their component

When searching for a component such as Button, the results could display the component together with its related stories:

• Button
  • Default
  • Rainbow
  • Danger

This would make it easier to explore all available stories of a component directly from the search results.

2. Search/filter for specific stories or variants

Users could further narrow down the results by searching for a specific story or variant.

For example, searching for Button Danger could prioritize or directly show:

• Button
  • Danger

This could potentially integrate with Storybook's existing tag system, for example using a danger tag.

3. Add filters based on project-defined contexts/tags

The search could provide filters such as:

All | Profile | Homepage | Dashboard

These should not be hardcoded categories. Instead, they could be based on existing Storybook tags, allowing each project to define its own contexts.

For example:

tags: ['profile'];

Selecting Profile would then limit the search results to stories/components associated with that context.

This could also work with other project-specific tags such as homepage, checkout, mobile, or experimental.

4. Add a "Most Recent" filter

A Most Recent filter could show recently opened stories, making it easier to return to components a developer was just working with.

For example:

• Button / Danger
• UserCard / Default
• Navigation / Mobile
• Input / Error

Ideally, this could also be combined with the normal search. Searching for Button while the Most Recent filter is active would only show recently viewed Button stories.

The overall goal is to make the search bar more useful as a navigation tool, especially in larger Storybooks.

Describe alternatives you've considered

Some of these use cases can already be partially handled through the existing sidebar structure and Storybook tags.

However, these approaches require users to navigate the sidebar or use filtering separately from the search experience.

Instead of introducing a completely new categorization system, I think reusing existing Storybook concepts such as tags and the component/story hierarchy could provide these capabilities while keeping the search experience consistent with Storybook.

Are you able to assist to bring the feature to reality?

Yes, I can.

Additional context

I would be happy to work on the implementation of this feature.

Before starting, I would appreciate feedback from the maintainers on whether this direction fits Storybook's plans for the search experience and which parts of the proposal would make the most sense to focus on first.

Related discussion: #29010

I worked on this idea together with @akuumaa, @Vazaril, and @Thodorr.

[Kin230k]

I like the goal here, especially for larger Storybooks. One useful distinction is that the current search already shows “Recently opened” items when the empty field is focused, and existing sidebar tag filters already apply before search. So I would treat this less as four new features and more as improving how those existing primitives are surfaced and composed.

For a first slice, I’d focus on grouped component/story results while preserving the current search and filter model. A component match could expose its best-matching stories beneath it, but the ranking and keyboard model should remain predictable: one active option at a time, arrow-key navigation across every selectable row, Enter to open, Escape to clear first and then return focus, and an announced result/group count for screen readers. The current “Recently opened” list could remain the empty-query state rather than adding a separate filter immediately.

Tags may only need better visibility near the search field, since they already constrain search results. If query syntax such as Button Danger is added later, it would help to define whether terms match names, paths, or tags and how that interacts with the existing include/exclude tag behavior.

Would grouped results plus the accessibility contract be a useful first implementation slice before changing filter or query semantics?

[StefanG1102]

Thanks, that makes a lot of sense. I agree that grouped component/story results are a good first step without changing the existing search and filtering semantics. The accessibility points you mentioned are especially helpful. I’d be happy to continue working on the prototype and make sure keyboard navigation, focus handling, and screen reader announcements behave correctly with grouped and collapsed results.

[Sidnioulz]

AFAIU 3 and 4 are already implemented. We have a button that opens a filter panel to filter based on content type, presence of recent changes or user-defined tags. We also show a "Recently opened" view when clicking on search though we're aware it has issues of discoverability and keyboard navigation.

@a-likhodievski could you please share your Figma prototype for search? I think it addresses many of @StefanG1102's proposals.

[StefanG1102]

I’ve already experimented with this idea a bit and implemented a small working prototype in my PR Feature: Improve search bar with grouped results, filters and recently viewed stories #36241. It currently covers some of the discussed improvements, including grouping related stories in search results and managing story tags directly from the sidebar.

I’d be very happy to continue working on it and adjust or extend the implementation based on feedback. I’d also love to work with the Figma prototype once it’s available, so I can align the implementation more closely with the intended design and UX.

Any feedback on the current approach or what would be most useful to tackle next would be greatly appreciated.

[Sidnioulz]

Can't put my hands on Aleksey's prototype but he did make a demo video which I can't share.

Please note that anything to do with "Recently viewed", right now, is still pending discussion. I don't think we've reached consensus to change that part yet.

So the idea of showing results as a tree is one where we're aligned. We've got an idea on how to treat component matches vs story matches:

• If only the component name matches, show component node collapsed
• If a story name matches, show the component node expanded, with the matching story/stories, and a button to open all other stories

Please note that we're in the process of making very big changes to the sidebar / tree code, and this part of the code is very complex and hard to work with. I don't think this volume of work is compatible with the timeline where you want to make a contribution as it will require significant back and forth.

[a-likhodievski]

Can't wait for the search that preserves groups @StefanG1102 I don't have a prototype and was just experimenting in a temporary branch. I took a closer look at #36241, and it already feels like an improvement compared to the current interaction.
On top of what @Sidnioulz said, I would suggest not using bold text for components in search results. Just treat them like stories, highlighting the matched part in blue. Also, each search result item should include a contextual menu.