Learn about Storybook Test and the new Storybook 9
86,794
Back to integrations

Tag Badges

Display Storybook tags as badges in the sidebar and toolbar.

View on Github

📔 Table of Contents

📦 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:*, v:* 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.

[!WARNING] This means that when you customise this addon's configuration, you should include your customisations before spreading the default config object, so that they have a higher priority.

👀 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 🐸',
        style: {
          backgroundColor: '#001c13',
          color: '#e0eb0b',
        },
        tooltip: 'This component can catch flies!',
      },
      display: {
        sidebar: ['component'],
        toolbar: false,
        mdx: true,
      },
    },
    // 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 (advanced usage)

The display property controls where and for what type of content the badges are rendered. It has three sub-properties: sidebar, toolbar and mdx. 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 mdx property controls the badges displayed by MDXBadges in a MDX file; in MDX, tags may be displayed for component or story entries (when importing CSF stories and using the of prop).

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, toolbar and mdx keys. You can either specify a single condition, or an array of conditions (in which case matching any condition for a given tag causes it to be used).

For mdx and toolbar display properties, the conditions can either be a boolean (to always or never display the badge) or a string (matching an entry type):

  • false: the badge should never be displayed
  • true: the badge should always be displayed
  • string: the badge should be displayed
Type Description Example MDX outcome Toolbar outcome
ø (not set) Use default behaviour ['component', 'story'] ['docs', 'story']
false Never display badge false [] []
true Always display badge true ['component', 'story'] ['docs', 'story']
string Display only for that type of entry 'docs' [] ['docs']

For the sidebar property, things are more complicated. You must choose for which entries to display badges and whether a badge should be displayed for an entry when its parent entry already displays the same badge.

For instance, of a component entry has a new badge, you must decide if you also want its individual stories to show the new badge. Tags inherited from parents are skipped in the default configuration.

A condition for the sidebar takes two properties:

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

Using the default config for display is heavily recommended. It is defined as follows:

const DISPLAY_DEFAULTS = {
  mdx: ['story', 'component'],
  sidebar: [
    { type: 'story', skipInherited: true },
    { type: 'docs', skipInherited: true },
    { type: 'component', skipInherited: false },
    { type: 'group', skipInherited: false },
  ],
  toolbar: ['docs', 'story'],
}

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'
style string | object Preset color, or a CSS properties object. 'turquoise' | { color: 'red', fontSize: '1rem' }
tooltip string | TooltipMessageProps? A tooltip shown on click in the toolbar only. { title: 'New Component', desc: 'Recently added to the library' }

Style presets

The following preset colors are defined:

  • grey
  • green
  • turquoise
  • blue
  • purple
  • pink
  • red
  • orange
  • yellow

Custom Style

To customise the look of your badges, you may pass an object of CSS properties to the style prop. The object is consumed by @storybook/theming and ultimately by emotion.

[!NOTE] The borderColor property, if set, will be passed to an inner box-shadow and then deleted.

[!NOTE] The margin on the side of the badge cannot be removed. It is reserved for the Vitest addon and other future Storybook UI features.

Example of a custom style:

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

addons.setConfig({
  tagBadges: [
    {
      tags: 'stylish',
      badge: {
        text: 'Stylish!',
        style: {
          background:
            'linear-gradient(to right in lch, rgb(255, 41, 91) 0%, rgb(177, 75, 255) 100%)',
          borderColor: 'transparent',
          borderRadius: 0,
          color: '#111',
          fontWeight: 'bold',
          fontFamily: 'monospace',
          letterSpacing: '0.05em',
          fontVariant: 'small-caps',
          padding: '0.5em',
        },
        tooltip: `This component can help create strong brand moments.`,
      },
    },
    ...defaultConfig,
  ] satisfies TagBadgeParameters,
})

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:

  • context: Whether the badge is being rendered in mdx or in the Storybook sidebar or toolbar
  • entry: The current HashEntry (component, story, etc.), with an id and/or name, a type, and tags (except if using badges in mdx with MdxBadges, as the entry is not loadable in that context)
  • 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}`,
          style: version.startsWith('0') ? 'pink' : 'blue',
          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,
  }
})

Using Badges in MDX

This addon provides two ways for you to include badges in your MDX files. A MDXBadges component takes a CSF meta or CSF story as a parameter and renders badges based on this parameter's tags. A CustomBadge component lets you create your own badge independently from tags.

Prerequisites

Before you can use badges in MDX, it's necessary to adjust how you handle your tagBadges configuration object.

Because we cannot load addon config in the preview part of Storybook (where MDX is rendered), we have to separate the tagBadges config in its own file, and load that file both in .storybook/manager.ts and .storybook/preview.ts.

First, create the .storybook/tagBadges.ts file to centralise your customisations to the default config:

// .storybook/tagBadges.ts
import { defaultConfig, type TagBadgeParameters } from 'storybook-addon-tag-badges'

export default [
  ...defaultConfig,
  {
    tags: 'frog',
    badge: {
      text: 'Frog 🐸',
      style: {
        backgroundColor: '#001c13',
        color: '#e0eb0b',
      },
      tooltip: 'This component can catch flies!',
    },
  },
] satisfies TagBadgeParameters

Next, adjust the manager to load config from that file:

// .storybook/manager.ts
import { addons } from 'storybook/manager-api'
import tagBadges from './tagBadges'

addons.setConfig({ tagBadges })

Finally, inject the tagBadges config into the window of the preview context. Note that parameters and globals cannot be used because their content is not loadable from MDX files:

// .storybook/preview.ts
import tagBadges from './tagBadges'

declare global {
  interface Window {
    tagBadges: typeof tagBadges
  }
}

window.tagBadges = tagBadges

MDXBadges

This component works like @storybook/blocks components Title, Subtitle, etc. It takes an of prop, which may receive either a CSF meta (the default export of a CSF file) or an individual story. Say you have a Button component implemented, the below example shows how to create your custom MDX page with automatic badges:

import { Canvas, Heading, Meta, Title } from '@storybook/blocks'
import { MDXBadges } from 'storybook-addon-tag-badges'

import ButtonStoriesMeta, * as CSF from './Button.stories'

<Meta of={ButtonStoriesMeta} />
<Title of={ButtonStoriesMeta} /> <MDXBadges of={ButtonStoriesMeta} />

{CSF.__namedExportsOrder.map((storyName) => <section key={storyName}>
  <Heading>{storyName} <MDXBadges of={CSF[storyName]} /></Heading>
  <Canvas of={CSF[storyName]} />
</section>)}

You can control which tags generate a badge in MDXBadges with the mdx sub-property of the display property in your addon configuration.

CustomBadge

If you want to create your own custom badges on the fly, you may import and use the CustomBadge component.

import { CustomBadge } from 'storybook-addon-tag-badges'

<CustomBadge text="My text" style="turquoise" />

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

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