Addon

While storybook-addon-badges can be used out of the box, some of the most powerful features are opt-in, to ensure that they don't conflict with how you use Storybook.

You can configure using the manager file (recommended), or the preview file in your .storybook/ configuration folder.

Manager Config

Configuring via the manager configuration file is the recommended method as it ensures that all options are available, and allows you to pass functions to certain configuration items.

To set the addon configuration, pass in your config options under the badgeConfig key of the object passed to addons.setConfig:

.storybook/manager.ts

import { addons } from '@storybook/addons';

addons.setConfig({
  // ...rest of config
  badges: ['version:1.0.0'], // 👈 You can also pass in global badges here if not using tags.
  badgesConfig: {
    // ...addon config here
  };
})

Preview Config

As Storybook serializes the parameters, any non-serializable values (such as functions/dates) are lost. Due to this, configuring in the preview config file isn't recommended for most users, but is available for backwards compatability.

To set the addon configuration, pass in your config options under the badgesConfig key of the preview parameters:

.storybook/preview.ts

// Replace `[your-framework]` with the name of your framework
import type { Preview } from '@storybook/[your-framework]';

const preview: Preview = {
  //...other preview config
  parameters: {
    //...other parameters
    badges: ['version:1.0.0'],
    badgesConfig: {
      // ...addon config here
    }
  }
}

export default preview;

Options

Below are the various configuration options available and what they do. For more information on a particular option, click the option's name in the table below.

Option	Description	Default
autobadges	Allows you to automatically add badges to a story based on triggers.	['new', 'updated']
badgeMap	Define the badges available to display.	See pre-defined badges
baseStyle	The style that badges use by default. Any values not defined will fall back to this.	See base style
delimiter	The string used to separate a badge's ID from its content.	':'
displayContentOnly	Whether to display just the content part of a badge. Can be overridden for each badge.	false
excludeTags	List of tags to prevent from generating badges.	['autodocs', 'dev', 'test', 'attached-mdx', 'unattached-mdx']
locations	Default locations for badges to display.	['toolbar']
matchers	Allows for complex logic and badge mapping.	[]
markAllAsReadOnDocsView	When using autobadges for new and updated, whether to remove the badge from all stories for a component when its docs page is viewed.	true
replaceDefaultBadgeMap	Allows a custom badge map to completely override the built-in badges, rather than extend.	false
separators	How to display separators in the different locations.
sidebarDisplayBadges	The number of badges to display on the sidebar to prevent it getting cluttered.	all
useMatcherBadgeFallback	When using matchers, whether to fallback to default badge mapping if no matchers match.	false
useTags	Whether to generate badges from tags.	false
warnOnLegacyConfig	Whether to display the warning when using 'legacy' configuration.	true

Warn On Legacy Config

info

As using parameters to configure storybook-addon-badges is considered legacy, you may see a warning pop up the first time you load a Storybook. This will only be shown once (per user, as it uses localStorage), and serves a reminder to migrate to the more powerful manager-based configuration if you've just upgraded.

If, however, you have a reason to keep using parameters, and want to remove this warning from ever showing on published Storybooks, you can pass in warnOnLegacyConfig: false to the badgesConfig and this will prevent the warning from showing.