Storybook tags, filter UI, and badges

[shilman]

In Storybook 8.4 we released Storybook tags with interactive filter UI, plus an addon for badges in the sidebar. (docs, addon).

Curious if you're finding tags useful, whether you have requests, and if you have use cases that you can share with the community!

[smlimasu]

Thank you for your work.

I would like to have a regex exclude filter option for tags in the sidenav Tag dropdown menu, because we have internal tags that we don't want to show.

Also, it would be great to have a tag like "test-only" or "internal" that displays stories in the sidenav only when they are checked (so that testers can toggle them on, but normal users don't in default.

Other use cases: I have made a docs component that shows various tags above the docs title as chips, also some tag-chips above each story-title in the docs. It reads from the story/meta. Would be great if there was a storybook block or option in stories-block, maybe with the tags addon (great work, frog!).

For the Controls/Argtypes tables, I enhance my Argtypes descriptions with various jsdoc tags and their info (filling the missing gap from compodoc.json) like deprecated, since (version XY), param. I display them in different colors and styles as chips to give my users more info about the argtype. Would be great if a) you could specify in preview which tags to include (like exclude internal, ignore (I know, this can be done via compodoc build options), include deprecated or version, and we would have these jsdoc info generated the same for all frameworks and b) set global styles to these tags like in the tags addon, maybe the same like create theme options.

Wish you happy holidays!

[smlimasu]

@shilman not sure if we mean the same with the jsdocs tags. I understand that it's difficult to tie jsdoc tags to e.g. the tags-filter-menu, but thats not what i thought of.

My goal is another. Since jsdoc tags are an essential part of code documentation, written extensively in the components source code, it's important that storybook shows that info where it could. Since we're talking about tags, for me they are different kind, but we should talk about their current state and their roadmap too, i think.

This comment only relates to the enhancement of the static text display of various jsdoc / argtype info in the argtype-block/controls-table. I hope I understand correctly that this is no problem with the indexer?

Here is an example what I mean, left my custom implementation, right the (angular SB) default behaviour:

There are different feature requests and open (or closed, but not working properly atm) bugs around displaying docgen jsdoc information or jsdoc tags in the argstable. See f.ex. #9721, #28830 , #26154 , #21794 . Looking at the source code, I see the various frameworks do not extract a standardized amount of info (if available trough their docgen api ofc). Example: In Angular and Svelte, deprecated is currently not displayed at all, but in react it is. There are other differences with see, param, since, too.

It would be so great if there was a consensus/goal or public guidance by the maintainers for contributors on what needs to be extracted from the jsdoc, if it should be joined to the description or if it should go into that array of tags, and how to display it (what order, what style/color, which column, striketrough the argtype.name), etc. in the table? So that contributors can all aim to implement the desired outcome step by step.

I'd really like to contribute to this, and fix the problems especially for angular, or implement features like in my screenshot, but for example I'm not sure if it would be okay to add colors or styleclasses to the tags or not. Should I only fix "deprecated" or go on and show more relevant jsdoc tags? Who or where to ask? What do other users think?

Just some food for thought for further discussions, thank you for reading ( :

[shilman]

Hi @smlimasu, thanks for clarifying.

Indeed, I thought you were referring to Storybook's notion of tags, which have the hard requirement of static analysis in the indexer. It's technically possible to do add Jsdoc parsing to the static analysis, but it's a heavy lift.

The information in the ArgsTable is a different code path. I would be open to a technical discussion on how we might go about improving that. Perhaps we could work on a plan together?

[Sidnioulz]

Honestly I can see the appeal to having tags for argTypes. It is so common for library maintainers to want to highlight when a prop was introduced or deprecated; having built-in tags support (e.g. a tags property on the argTypes item and then addons can display those if there's the right ArgsTable hook?) would be amazing.

Regarding the earlier discussion on default filters / profiles / etc, I think the easiest resolution for a v1 would be to provide API endpoints to set the tag filter, reachable by addons. Then anyone is free to build default filters with an API call in their manager, or an addon for profile switching. WDYT @shilman?

[shilman]

@Sidnioulz there's already a sidebar filtering API in the manager. I believe it's intentionally undocumented and prefixed with experimental_ but it's there. That API is a filter function so it's quite flexible. The tag filter UI uses that API under the hood.

If you want manager API's to set the tag filter specifically, that should also be possible. I'm open to it, but I'd only want to increase the surface area in that way if the use cases were better articulated.

[Sidnioulz]

I think it would provide a better experience to end users if there was an API that lets addon authors configure tag filters, so that what they do is reflected in the UI rather than hidden, but that's just an opinion and I thoroughly agree with you that we need more fleshed out use cases and more requests before adding maintenance surface.

[Sidnioulz]

Making a dedicated thread to discuss tags in argTypes.

Use cases

Brought up by @smlimasu but also something I've experienced as a library maintainer.

• Deprecated props
• Prop versioning

Opportunities

Having built-in tags support would allow showing badges in the ArgsTable next to props, and possibly also in the controls description, though likely with extra development effort or additional work in stories files.

Challenges

Since argTypes are not statically loaded, the tag filter UI cannot support such tags.

[Grubsniff]

Thank you for this valuable contribution! The tagging system is particularly useful for organizing stories.

However, I'd like to expand on @smlimasu feedback regarding story visibility control.

Current Challenge:
We're running a production Storybook instance where test stories are visible alongside production components. With hundreds of test stories, this creates unnecessary noise for our end users.

Feature Request:
Could we implement a default visibility filter based on tags?

• Ability to automatically hide stories marked with a 'x' tag
• Option to toggle visibility of filtered stories when needed
• Default hide/show preferences that persist across sessions

This would significantly improve the user experience for teams using Storybook in production environments while maintaining the ability to access test stories when needed.

Has there been any consideration for implementing this kind of filtering system? Happy to provide more context about our use case if helpful.

Thanks again for maintaining this project!

[shilman]

I think this is the logical next step for tags! I scoped things down to keep the first version small, but def have this in mind.

For tests specifically we have a slightly different idea for differentiating stories from tests, but I think this request still holds for any kind of story that clutters the sidebar.

[Grubsniff]

Thanks for the reply.

This is great to hear that it is in scope as an enhancement.

Thanks for sharing the tests approach, that actually seems really valuable for one of our other storybook teams!

Has this idea been implemented as of yet? or would we expect that in a future version?