src="./static/addon-example.png"
alt="Example of the addon in use, showing badges next to component entries in the sidebar."
loading="lazy"
decoding="async"
height="247"
/>

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
- Installation
- Default Config
- Usage
- Customise Badge Config
- Sidebar Config
- Workflow Examples
- Limitations
- Contributing
- Support
- Contact
- Acknowledgments

📦 Installation

``sh
yarn add -D storybook-addon-tag-badges
`

`sh
npm install -D storybook-addon-tag-badges
`

`sh
pnpm install -D storybook-addon-tag-badges
`

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

`ts
// .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.

$3

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

$3

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.

$3

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

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

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

$3

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

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

$3

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

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

const meta: Meta = {
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.

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

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: [{
type: 'component',
skipInherited: true,
}],
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.

$3

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' |

---

When prefix or suffix are used, the tag is split in two on the first : separator character. The left-hand side of the tag is compared to prefix and the right-hand side (including any additional :) to the suffix. If you've used a string as prefix or suffix, the addon will search for an exact match. If you used a RegExp, you must add ^ and $ regular expression delimiters yourself to avoid accidentally matching other tags.

`ts
// As an example, consider the following tags on a story:
const tags = ['v:1.0.0', 'private']

// ✅ The string prefix will only match 'v:1.0.0'
{
tags: { prefix: 'v' },
badge: { / ... / },
}

// ❌ The RegExp prefix without delimiters will also match 'private'
{
tags: { prefix: /v/i },
badge: { / ... / },
}

// ✅ The RegExp prefix with delimiters will only match 'v:1.0.0'
{
tags: { prefix: /^v$/i },
badge: { / ... / },
}
`

$3

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 |
| --------------------------------- | --------- | -------------------------------------------------------------------------- |
| ![](./static/entry-story.svg) | story | One of the component stories written in your CSF files. |
| ![](./static/entry-docs.svg) | docs | A documentation page generated through MDX files or autodocs. |
| ![](./static/entry-component.svg) | component | The grouping of a component's stories and autodocs page. |
| ![](./static/entry-group.svg) | 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 | boolean | true |

Using the default config for display is heavily recommended. It is defined as follows:
`ts
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'],
}
`

$3

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:

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

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:

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

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

$3

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.

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

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 {item.name} [doc]
}

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

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

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.

$3

This component works like @storybook/addon-docs/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:

`mdx
import { Canvas, Heading, Meta, Title } from '@storybook/addon-docs/blocks'
import { MDXBadges } from 'storybook-addon-tag-badges/manager-helpers'

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