npm package: @paul-parton/variants
Description: Storybook addon for displaying component variants all together in one story.
Author: Mostafa Sherif
Latest version: 0.0.68-clone-0.4

<div align="center">

<img src="https://raw.githubusercontent.com/sheriffMoose/storybook-extras/master/logos/variants.svg" alt="logo" width="200" />

<h1>Story Variants</h1>

<p>Storybook addon for displaying component variants all together in one story.</p>

![][img.node]
![][img.npm]
[![][img.storybook]][link.npm]

[![][img.banner]][link.npm]

</div>

<h2>Table of Contents</h2>

- [Getting started](#getting-started)
- [How to use](#how-to-use)
  - [Parameters](#parameters)
- [Compatibility](#compatibility)

## Getting started

1. Install the addon:

```shell
yarn add @storybook-extras/variants -D
```

1. Add the addon

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

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

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

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



[img.node]:
https://img.shields.io/node/v/@storybook-extras/variants?logo=node.js&logoColor=white&labelColor=339933&color=grey&label=
[img.npm]:
https://img.shields.io/npm/v/@storybook-extras/variants?logo=npm&logoColor=white&labelColor=CB3837&color=grey&label=

[img.storybook]:
https://img.shields.io/npm/dependency-version/@storybook-extras/variants/dev/storybook?logo=storybook&logoColor=white&labelColor=FF4785&color=grey&label=

[img.banner]:
https://nodei.co/npm/@storybook-extras/variants.png

[link.npm]:
https://npmjs.org/package/@storybook-extras/variants