@paul-parton/variants

Story Variants

Storybook addon for displaying component variants all together in one story.

Table of Contents

• Getting started
• How to use
  • Parameters
• Compatibility

Getting started

1. Install the addon:

yarn add @storybook-extras/variants -D

1. Add the addon

// .storybook/main.ts
import { StorybookConfig } from '@storybook/angular';
import { ExtrasConfig } from '@storybook-extras/preset';

const config: StorybookConfig & ExtrasConfig = {
    ...
    "addons": [
        "@storybook-extras/variants",
        // it will be included automatically if you are using
        // "@storybook-extras/preset",
        ...
    ],
    ...
}

export default config;

How to use

• Simply enable the variants through the toolbar or using the parameters like so:

// .storybook/preview.ts 
// button.stories.ts
parameters: {
    variants: {
        enable: true
    },
};

• You can also manually pass and display the variant params in a template, this can be useful for passing transcluded content

// button.stories.ts
render: (args) => ({
    prop: args
    template: `
        <app-button [type]="type" [colour]="colour">This is a {{type}} {{colour}} button.</app-button>
    `,
})
parameters: {
    variants: {
        enable: true,
        include: ['type', 'colour']
    },
};

Parameters

Name	Type	Default	Description
enable	boolean	false	Enable the variants addon
include	string[]	[]	Include variants from the list
exclude	string[]	[]	Exclude variants from the list
groupBy	string[]	[]	Group the variants by these keys
autoCalculate	boolean	false	Automatically calculate the variants

NOTES

• If you set autoCalculate to false, you can use the include parameters to include the variants.
• If you set autoCalculate to true, you can use the exclude parameters to filter the variants.
• Toolbar button will not show if autoCalculate is set to true or include is not empty.

Compatibility

This addon was initially developed for Angular 15 & Storybook v7 in mind. However, you can still use it in older versions, but you will need to use the decorator directly in preview.js instead of adding the addon in your main.js.

// .storybook/preview.ts
import { withVariants } from '@storybook-extras/variants';

export const decorators = [withVariants()];

This approach will also work for React, Vue, and other frameworks. Please open an issue if you find any compatibility issues, pull requests are always welcome.