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.

[smlimasu]

To add to the list of use cases:

• param tag for methods with param description

• returns tag with description

• proper formatting for see, link and example

• make sure to have option to hide "internal" or "ignore" or "private/protected" props (like in the compodoc options for angular), maybe as an option in the preview.controls object

• should all tags and their description/comment part go into an array "jsdoc tags" of the argtype object to allow users implement custom things? I would say yes, this way users could also add additional tags and descriptions in the argtypes of the story manually e.g. when the argtype is not pulled from the prop jsdoc.

styling decisions:

• style deprecated in an "orange" color (should this be configurable by the user? Then add tags styling to the theme options array or at least add a style class to each tags span)
• should deprecated args be sorted last in the argstable, with strike trough and lighter text color? See mock from 2021.
• style since/version in a badge color style (maybe primary color?)
• order of tags, I would suggest deprecated first, then the overall arg description, then "versioning", then param/returns and the default value.

@shilman yes I am open to help to discuss or mock a plan/draft for this, thank you.

[Sidnioulz]

As tags would be simple word lists, they couldn't substitute the way function arg descriptions are done in the ArgsTable.

I'm curious if addon hooks can be provided in the ArgsTable, @shilman? Is there a way we can avoid increasing the code footprint and allow addon authors to do more? Going back on the idea of custom controls (there's a PR for that somewhere in the repo) and my unexplored idea of JSX controls, providing an entry point into the table for addons could have extra benefits.

[smlimasu]

@Sidnioulz yes, but they have a tagname and description, like there already is the jsdoctags type in the argtype in the codebase, see this story

storybook/code/lib/blocks/src/components/ArgsTable/ArgRow.stories.tsx

Line 291 in 2759c5b

jsDocTags: {

storybook/code/renderers/react/template/stories/docgen-components/jsdoc/argTypes.snapshot

Line 10 in 1664776

"jsDocTags": undefined,

when i set the jsdoc tags in the argTypes of my story like this (if needed, for simpler use cases, not as a substitution, e.g. when you need to define argTypes for documentation purposes yourself in some cases)

const meta = {
  argTypes: {
      backgroundColor: {
        description: 'sets color of the background',
        control: 'color',
        table: {
          defaultValue: {
            summary: '#F5F5F5',
          },
          jsDocTags: {
            deprecated: 'this arg is deprecated',
          },
        },
      },
    },
} satisfies Meta<typeof Button>;

it currently shows the deprecated "tag" and the deprecated string message in SB react stackblitz. So why don't we add this behaviour to the argType type's documentation/typespec officially.

Maybe we mean something different here, i am talking about concatenating all tags, their descriptions and the prop description, param, returns etc in the end to one "description text"-cell in the argstable, like I did it in my screenshot, you are talking about adding the jsdoc tags in an extra column or something? Could you clarify?

yes, addon hooks would be great.

[Sidnioulz]

Maybe we mean something different here, i am talking about concatenating all tags, their descriptions and the prop description, param, returns etc in the end to one "description text"-cell in the argstable, like I did it in my screenshot, you are talking about adding the jsdoc tags in an extra column or something? Could you clarify?

We do :)

• JSDoc tags refer to https://jsdoc.app/; in Storybook there are some JSDoc tags in argTypes[...].table.jsDocTags
• Storybook tags are a Storybook-only list of words applied to stories, components meta, docs entries (and by extrapolation, to all Storybook Hash entries)

I refer to the latter, not the former. Having tags on argTypes could extend beyond the table: I could possibly also want to print a summary of new props or deprecated props in a MDX block that I add to my autodocs template, for instance. I could also exploit that information in a future Figma CodeConnect integration.

[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?

[shilman]

@Grubsniff that's great! The .test proposal is still just at concept stage but will very likely be ready late this spring for 9.0.

The tags improvements are not on the roadmap yet but are on my radar. Will try to squeeze them in as they are a smaller lift. Will post back here when there's progress!

[akibmayadav]

Thank you for the amazing work!
Would be great to have this URL parameters for tag filters so that you can share a filtered view of your Storybook. Is there any way to use url parameters to share specific views at this point of time ? Or is it possible to set some default selections of the filter ?

[ptbrowne]

It would be great to be able to have a link to a pre-filtered view. This could help sharing a link to components needing a visual review, or that are new.

[shilman]

Good one. Any thoughts on how that might look? A CLI option like storybook build --includeTags new --excludeTags experimental?

[enemyXXX]

That really nice, but what about filtering by tags using search input? I guess it will be really helpful for huge projects with thousand stories, where each story has kind of shortcut with often tries to search it

[shilman]

We don't have a search-based UI yet. However, if you filter by tag using the UI, it will also filter down the search results AFAIK.

[oriooctopus]

Could this be used to SEO stories? For example, if I have a component called FinalStep, I'd like it to come up if somebody searches DoneStep. It would be nice if tagging allowed for this

[breakone]

Is there a possibility to show tags, e.g. the deprecated, in the components tree? Something like this?

[Sidnioulz]

Yes, use the tag badges addon: Https://github.com/sidnioulz/storybook-addon-tag-badges

[breakone]

🙏 thanks for the quick reply