84,437
Back to integrations

Tag Badges

Display Storybook tags as badges in the sidebar and toolbar.

View on Github

📔 Table of Contents

🤔 Which badge addon should I use?

A few other projects have been written to display badges in Storybook. This addon is a rewrite of storybook-addon-badges from Jim Drury, focused on exploiting Storybook tags. We use tags as a data source to display badges, rather than dedicated story parameters, as tags are becoming more prevalent in Storybook and have a strong role overlap with badges.

This architectural choice opens up new possibilities, but also prevents some features from the original addon from working. The table below summarises the differences between both addons.

storybook-addon-tag-badges storybook-addon-badges
Show badges in toolbar ✅ ✅
Show badges in sidebar ✅ ⚠️ only for current story
Define badges based on tags ✅ ❌
Per-story customisation ❌ ✅
Tooltip support ⚠️ only in toolbar ✅
Storybook >= 8.4 ✅ ✅
Storybook < 8.3 ❌ ✅

📦 Installation

yarn add -D storybook-addon-tag-badges

npm install -D storybook-addon-tag-badges

pnpm install -D storybook-addon-tag-badges

In your .storybook/main.ts file, add the following:

export default {
  addons: ['storybook-addon-tag-badges'],
}

🏁 Default Config

This addon comes with a default config, allowing you to get started immediately by adding tags to your content.

Preconfigured Badges

Preview Tag patterns Suggested use
new Recently added components or props/features
alpha, beta, rc, experimental Warn that a component or prop is not stable yet
deprecated Components or props that should be avoided in new code
outdated Components with design changes that weren't yet implemented, which can incur extra development costs to your users
danger Components that require particular attention when configuring them (e.g. for with security concerns)
code-only Components that only exist in code, and not in design
version:* Per-component versioning

Display Logic

By default, all tags are always displayed on the toolbar, but they're only displayed for component entries in the sidebar.

Besides, the addon is limited to one badge per entry in the sidebar. Badges placed first in the configuration will be displayed in priority. For example, the new badge will be displayed before the code-only badge.

👀 Usage

To display preconfigured badges, add the relevant tags to your components, stories, or docs entries.

Component Badges

To set badges for a component (and its child stories), define tags in the component's meta:

// src/components/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Example/Button',
  component: Button,
  tags: ['autodocs', 'version:1.0.0', 'new'],
}

Story Badges

To add badges to a specific story, add tags to the story object itself:

// src/components/Button.stories.ts
export const Tertiary: StoryObj<typeof Button> = {
  args: {
    variant: 'tertiary',
    size: 'md',
  },
  tags: ['experimental'],
}

Docs Badges

To set badges for a docs entry, pass a tags array to the docs parameter:

// src/components/Button.stories.ts
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Example/Button',
  component: Button,
  parameters: {
    docs: {
      tags: ['outdated'],
    },
  },
}

🛠️ Customise Badge Config

In your manager file, you may redefine the config object used to map tags to badges. Each tag is only rendered once, with the first badge configuration it matches; therefore, make sure to place your overrides to the config first if you also want to keep the default config in place.

// .storybook/manager.ts
import { addons } from '@storybook/manager-api'
import {
  defaultConfig,
  type TagBadgeParameters,
} from 'storybook-addon-tag-badges'

addons.setConfig({
  tagBadges: [
    // Add an entry that matches 'frog' and displays a cool badge in the sidebar only
    {
      tags: 'frog',
      badge: {
        text: 'Frog 🐸',
        bgColor: '#001c13',
        fgColor: '#e0eb0b',
        tooltip: 'This component can catch flies!',
      },
      display: {
        sidebar: ['component'],
        toolbar: false,
      },
    },
    // Place the default config after your custom matchers.
    ...defaultConfig,
  ] satisfies TagBadgeParameters,
})

Let's now walk through the different properties of tagBadges. Each object in tagBadges represents a list of tags to match, and where a match is found, a badge configuration to use and places where the badge should be displayed.

Tags

The tags property defines the tag patterns for which a badge will be displayed. It can be a single pattern or an array of patterns.

A tag pattern can be:

Pattern type Description Example pattern Match outcome
string Exact match 'new' 'new'
RegExp Regular Expression /v\d+\d+\d+/ 'v1.0.0'
{ prefix: string | RegExp } Match part of a tag before a : separator { prefix: 'status' } 'status:done'
{ prefix: string | RegExp } Match part of a tag after a : separator { suffix: 'a11y' } 'compliant:a11y'

Display

The display property controls where and for what type of content the badges are rendered. It has two sub-properties: sidebar and toolbar. In the sidebar, tags may be displayed for component, docs or story entries. In the toolbar, they may be set for docs or story entries (as other entry types aren't displayable outside the sidebar).

Each of these sub-properties can be set to:

Type Description Example Sidebar outcome Toolbar outcome
ø (not set) Use default behaviour ['component'] ['docs', 'story']
false Never display tag false [] []
true Always display tag true ['component', 'docs', 'story'] ['docs', 'story']
string Display only for one type of entry 'docs' ['docs'] ['docs']
string[] Display for a list of entry types ['docs'] ['docs'] ['docs']

Badge

The badge property defines the appearance and content of the badge to display. It can be either a static object or a function that dynamically generates the badge based on the matched content and tag.

Static Badge Object

The object has the following properties:

Name Type Description Example
text string The text displayed in the badge (required). 'New'
bgColor string? The CSS property passed to background-color. '#aea'
fgColor string? The CSS property passed to color. '#2f2'
borderColor string? A border colour, rendered as a CSS box-shadow. '#2f2'
tooltip string? A tooltip text shown when clicking the badge in the toolbar only. 'This component is new!'

Dynamic Badge Functions

Dynamic badge functions allow you to customize the badge based on the current entry and matched tag. They must return a valid badge object as documented above. They receive an object parameter with the following properties:

  • entry: The current HashEntry (component, story, etc.), with an id and/or name, a type, and tags
  • getTagParts, getTagPrefix, getTagSuffix: Utility functions to extract parts of the tag
  • tag: The matched tag string

Example of a dynamic badge function:

// .storybook/manager.ts
import { addons } from '@storybook/manager-api'
import {
  defaultConfig,
  type TagBadgeParameters,
} from 'storybook-addon-tag-badges'

addons.setConfig({
  tagBadges: [
    {
      tags: { prefix: 'version' },
      badge: ({ entry, getTagSuffix, tag }) => {
        const version = getTagSuffix(tag)
        const isUnstable = version.startsWith('0')
        return {
          text: `v${version}`,
          bgColor: version.startsWith('0') ? '#f0ccff' : '#cce0ff',
          tooltip: `Version ${version}${isUnstable ? ' (unstable)' : ''}`,
        }
      },
    },
    ...defaultConfig,
  ] satisfies TagBadgeParameters,
})

📝 Workflow Examples

This repository contains examples on how to support various workflows with Storybook badges:

  • Market segmentation
  • Separating functional from branded components
  • Compliance state for checks like a11y, brand, QA
  • Component composition patterns
  • Use of external dependencies
  • Smart components

To see these in action, check out the repository and run the local Storybook instance:

git clone https://github.com/Sidnioulz/storybook-addon-tag-badges.git
cd storybook-addon-tag-badges
pnpm i
pnpm start

🐌 Limitations

Per-Story Config

This addon does not support changing the badge config for a specific story, and never will. This is because parts of the Storybook UI, like the sidebar, are rendered in a context where story data is not loaded. Storybook has stopped preloading all story data in v7, to improve performance.

As a result, we need to create sidebar tags without access to story-specific data. This addon uses the core addon API to read your configuration, and so the way to customise the rendering of a specific badge is to use dynamic badge functions. Those functions can exploit a story's ID, title, or tag content to customise the rendered badge, as examples below will show.

Component tags

In Storybook, your MDX and CSF files are converted to docs, component, group and story entries to render the sidebar, each with their own semantics. docs and story entries directly inherit the tags defined in parameters.docs.tags and in the CSF meta, respectively.

For component entries, tags are computed indirectly: they are the intersection of tags present on all of the component's stories. For example, for a component that defines the tag version:1.2.0 in its meta, and has one story that defines an additional tag deprecated, the component entry will only have the version:1.2.0 tag defined.

In particular, if a component meta defines two tags outdated and version:1.1.0, but one story explicitly removes the tag outdated (by adding !outdated), then the component entry will only have tag version:1.1.0.

👩🏽‍💻 Contributing

Code of Conduct

Please read the Code of Conduct first.

Developer Certificate of Origin

To ensure that contributors are legally allowed to share the content they contribute under the license terms of this project, contributors must adhere to the Developer Certificate of Origin (DCO). All contributions made must be signed to satisfy the DCO. This is handled by a Pull Request check.

By signing your commits, you attest to the following:

  1. The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file; or
  2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, under the same open source license (unless you are permitted to submit under a different license), as indicated in the file; or
  3. The contribution was provided directly to you by some other person who certified 1., 2. or 3. and you have not modified it.
  4. You understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information you submit with it, including your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Getting Started

This project uses PNPM as a package manager, and Turbo as a monorepo provider.

Useful commands

  • pnpm start starts the local Storybook
  • pnpm build builds and packages the addon code
  • pnpm pack:local makes a local tarball to be used as a NPM dependency elsewhere
  • pnpm test runs unit tests

Migrating to a later Storybook version

If you want to migrate the addon to support the latest version of Storyboook, you can check out the addon migration guide.

Release System

This package auto-releases on pushes to main with semantic-release. No changelog is maintained and the version number in package.json is not synchronised.

🆘 Support

Please open an issue for bug reports or code suggestions. Make sure to include a working Minimal Working Example for bug reports. You may use storybook.new to bootstrap a reproduction environment.

✉️ Contact

Steve Dodier-Lazaro · @Frog on the Storybook Discord - LinkedIn

Project Link: https://github.com/Sidnioulz/storybook-addon-tag-badges

💛 Acknowledgments

Thanks

Built With

Dependabot ESLint GitHub Prettier Semantic-Release Storybook tsup TypeScript Vitest

Made by
  • sdlazaro
    sdlazaro
Tags
How to install addons Create an addon