Storybook Addon - Tag Badges

This addon displays badges in the sidebar and toolbar of the Storybook UI, next to component, docs or story entries, based on the tags defined in your content. Badges can be customised to support your team's workflows.

---

📔 Table of Contents

• Table of Contents
• Which badge addon should I use?
• Installation
• Default Config
• Usage
• Customise Badge Config
• Sidebar Config
• Workflow Examples
• Limitations
• Contributing
• Support
• Contact
• Acknowledgments

🤔 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:

// .storybook/main.ts
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 in the sidebar for component entries, and for docs or story entries that appear at the top-level. They are not displayed in docs or story entries inside a component or group entry.

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, group, 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).

The following entry types are rendered by Storybook:

Icon	Name	Description
	story	One of the component stories written in your CSF files.
	docs	A documentation page generated through MDX files or autodocs.
	component	The grouping of a component's stories and autodocs page.
	group	A generic group containing unattached MDX docs, stories and/or components.

To control where badges are shown, you pass conditions to the sidebar and toolbar keys. You can either specify a single condition, or an array of conditions (in which case matching any condition causes the badge to display).

Conditions can either specify the type of entry you want to display badges for, or, whether to allow badges for any tag that isn't already displayed by a parent entry (e.g. in the top-level component in the sidebar). Tags inherited from parents are skipped in the default configuration; otherwise, every single story would have a tag when you add tags to a CSF meta export, which would be verbose.

A condition takes two properties in its full form:

Property	Description	Type	Example value
type	The type of entry to match	string	'docs'
skipInherited	Whether to skip showing the badge if a parent entry in the UI already shows a badge for the same tag	string	true

Syntax shortcuts are supported, and summarised in the table below:

Type	Description	Example	Sidebar outcome	Toolbar outcome
ø (not set)	Use default behaviour		[{ skipInherited: true }, { type: 'component', skipInherited: false }, { type: 'group', skipInherited: false }]	[{ type: 'docs' }, { type: 'story' }]
false	Never display badge	false	[]	[]
true	Display badge everywhere	true	[{ skipInherited: false }]	[{ type: 'docs' }, { type: 'story' }]
string	Display only for one type of entry, and skip inherited tag badges	'docs'	[{ type: 'docs', skipInherited: true }]	[{ type: '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 | TooltipMessageProps?	A tooltip shown on click in the toolbar only.	'This component is new!' or { title: 'New Component', desc: 'Recently added to the library' }

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,
})

Tooltip

Badges may have a tooltip when displayed in the toolbar. The tooltip is disabled in the sidebar to avoid conflicting with the sidebar's function, though feedback is welcome on this.

You may pass a string to tooltips for a simple tooltip. You may also pass the same objects used by Storybook's TooltipMessage:

• title: The title of the tooltip [string]
• desc: Secondary text for the tooltip [string]
• links: An optional array of link objects displayed as buttons [object[]]
  • title: The title of the link
  • href: The URL to which the link points (navigates in-place)
  • onClick: A callback when the link is clicked (can be used to navigate in a new browser tab)

Sidebar Config

This addon uses the sidebar renderLabel feature to display badges in the sidebar. If you define it for other purposes in your Storybook instance, it will conflict with this addon and sidebar badges won't show.

To show badges for items that aren't customised by your own renderLabel logic, you may import the addon's own renderLabel function and call it at the end of your function.

// .storybook/manager.ts
import { addons } from '@storybook/manager-api'
import type { API_HashEntry } from '@storybook/types'
import { renderLabel, Sidebar } from 'storybook-addon-tag-badges'

addons.setConfig({
  sidebar: {
    renderLabel: (item: API_HashEntry) => {
      // Customise your own items, with no badge support.
      if (item.name === 'Support') {
        return '🛟 Get Support'
      }

      // Customise items with badge support by wrapping in Sidebar.
      if (item.type === 'docs') {
        return <Sidebar item={item}>{item.name} [doc]</Sidebar>
      }

      // Badges for every item not customised by you.
      return renderLabel(item)
    },
  }
})

Likewise, if you define configuration for the sidebar option without including renderLabel, the render function defined by this addon will be overwritten, and badges won't show in the sidebar. Import and add the renderLabel function like so:

// .storybook/manager.ts
import { addons } from '@storybook/manager-api'
import { renderLabel } from 'storybook-addon-tag-badges'

addons.setConfig({
  sidebar: {
    /* your own changes here... */
    renderLabel,
  }
})

📝 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.

• See the installation instructions for PNPM
• Run pnpm i

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

• Jim Drury for his groundbreaking working on the original Badges Addon; I am a mere copy-cat
• Michael Shilman for his help with addon internals and his feedback
• All the contributors to the Storybook addon kit

Built With