Autobadges

Autobadges are a feature that allows for adding badges that don't need to be defined in advance for a story.

info

If you frequently run multiple Storybooks locally, please see Running Multiple Storybooks below.

Options

The autobadges configuration option accepts either an array of built-in autobadges, or a function that returns an array of strings which should be badges to add to a story.

warning

If defining your configuration as a parameter in the preview file, this option cannot accept a function value due to how Storybook serializes parameters.

Array Config

To use the built-in autobadges, pass an array of the built-in autobadge names below to the autobadges config option:

.storybook/manager.ts

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

addons.setConfig({
  // ...rest of config
  badgesConfig: {
    autobadges: ['new', 'a11y-fail']
  };
})

There are several autobadges that can be defined by default:

• new - Assigned when a new story has been added since the last time you loaded the Storybook.
• updated - Assigned when a story has had args/parameter changes since the last time you loaded the Storybook.
• a11y-fail - When using storybook-addon-a11y, this will be added for stories that have a11y violations.
• a11y-pass - When using storybook-addon-a11y, this will be added for stories that pass a11y checks with no violations.
• a11y-check - When using storybook-addon-a11y, this will be added for stories that have 'incomplete' checks from the a11y addon, allowing you to review.

note

storybook-addon-a11y is currently having some changes made to incorporate with the experimental testing addon. At the moment, the autobadges relating to a11y checks can only be generated when you select a story (they will then persist until the next time that story is selected).

Function Config

A function can also be used to configure your own custom autobadges.

This function receives an object with the following properties:

• a11yStatus: Can be one of 'pass', 'fail' or 'incomplete', or null if no data exists for the story.
• entry: The Storybook data for the story. An object containing:
  • id: The unique ID of the entry.
  • depth: The depth of the entry in the sidebar tree (how many folders deep - including the root).
  • name: The name of the entry, usually displayed in the sidebar.
  • refId: An internal Storybook reference.
  • renderLabel: A function for rendering the label in the sidebar. See the Storybook docs for more details.
  • type: The type of the entry.
  • startCollapsed: Whether a root entry is collapsed on initial load. (Only available on type: 'root').
  • children: The contents of a root, group, or component entry. Lists the direct child entry ID's.
  • parent: The parent of a group, component, docs or story entry. The ID of the entry's direct parent entry.
  • tags: The tags of a component, docs or story entry.
  • title: The title of a docs or story entry. Can be inferred, or manually entered in the component's meta.
  • prepared: A boolean indicating whether the docs/story has been prepared. If false, the args,argTypes,initialArgs and parameters are unlikely to be populated.
  • importPath: The file path for docs/story entries. Relates to their story file (*.stories.tsx?).
  • parameters: The parameters of a docs/story entry. Only available if the entry is prepared.
  • args: The current args of a story entry, will differ to initialArgs if the values have been updated in Storybook but not saved. Only available if the entry is prepared.
  • argTypes: The argTypes of a story entry. Only available if the entry is prepared.
  • initialArgs: The initialArgs of a story entry. Only available if the entry is prepared.
• isNew: Whether the `new` badge would be applied when using the array option.
• isUpdated: Whether the `updated` badge would be applied when using the array option.

isNew, isUpdated and a11yStatus allow you to include logic to apply those built-in badges in your custom logic (as a custom function replaces that array).

The autobadges function can return an array of any badge IDs (not just the built-in ones), so you can define custom badges and use the function to assign any of them based on information about the story.

Example

autobadges: (params: AutobadgesFnParameters) => {
  const badges: string[] = [];

  // Incorporate logic for built-in autobadges (optional)
  if (params.isNew) badges.push(BADGE.NEW);
  if (params.isUpdated) badges.push(BADGE.UPDATED);
  if (params.a11yStatus === 'pass') badges.push(BADGE.A11Y_PASS);
  if (params.a11yStatus === 'fail') badges.push(BADGE.A11Y_FAIL);
  if (params.a11yStatus === 'incomplete') badges.push(BADGE.A11Y_CHECK);

  // Add custom logic based on information about the story.
  if (params.entry.id.includes('input')) badges.push('form-input');

  return badges;
};

Disabing Autobadges

If you don't want to use autobadges, you can pass false to the autobadges config item. This will disable autobadges entirely.

Additional Options

Autobadges offer some additional configuration options to tweak settings to your liking.

• markAllAsReadOnDocsView: (default true) Clicking on a component with a docs page will usually select the docs page. As this usually loads all stories on the docs page (at least if using autodocs), all stories will be loaded and any new/updated badges will be removed (as those stories have now been 'read'). To disable this behavior, and require manually selecting a story to clear the badge, you can pass false to this option.

Running Multiple Storybooks

Due to how this addon works with autobadges, running multiple storybooks on the same URL (e.g: localhost in development) may mean that the new/updated badges display when switching between them.

You can get around this by providing an storybookId in your manager config:

.storybook/manager.ts

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

addons.setConfig({
  storybookId: 'my-storybook',
});

This will ensure that the data is saved against a unique key (otherwise all storybooks will be saved against the default key, and can then conflict with each other).