@ergosign/storybook-addon-pseudo-states-react

Storybook Addon Pseudo States

Storybook Addon Pseudo States allows you to automatically display pseudo states (and attribute states) of a component in Storybook's preview area.

• Live-Demo
• Example Repo (CRA)

Framework Support

Framework	Display States	Tool-Button to show/hide
Angular	+	+
React	+	+
Lit	+	+
HTML	+	+
Vue	+	+

Getting started

First of all, you need to install Pseudo States into your project as a dev dependency.

npm install @ergosign/storybook-addon-pseudo-states-react --save-dev

When using create-react-app and the related preset, configure it as an addon for your Storybook environment (located in the Storybook config directory).

For version < 5.3.x

Import the addon in your addons.js file:

import "@ergosign/storybook-addon-pseudo-states-react/preset-postcss";

For version >= 5.3.x

Add it to the addons section in your main.js file.

module.exports = {
  "addons": [
    '@ergosign/storybook-addon-pseudo-states-react/preset-postcss'
  ]
}

In case you have an other project configuration, check out the Advanced setup section, to see how to get it working with different settings.

To see what's needed to use the pseudo addon, have a look at the Usage section.

Advanced setup

With PostCSS Preset

This project comes with a dependency to the postcss-pseudo-classes package. Unfortunately, the latest version is only tagged and not released.

We provide a preset-postcss preset that adds postcss-loader to Storybook's custom webpack config. Add this preset to your configuration (located in the Storybook config directory)

For version < 5.3.x

Import the addon in your addons.js file:

import "@ergosign/storybook-addon-pseudo-states-react/preset-postcss";

For version >= 5.3.x

Add it to the addons section in your main.js file.

module.exports = {
  "addons": [
    '@ergosign/storybook-addon-pseudo-states-react/preset-postcss'
  ]
}

This creates for each css pseudo class an equivalent as normal css class (for instance :hover to \:hover), so that you can use it in element's class attribute (<div class=":hover">Element in hover state</div>).

You can modify post css loader options (see type definition of PseudoStatesPresetOptions):

module.exports = {
   presets: [
       {
            name:"@ergosign/storybook-addon-pseudo-states-react/preset-postcss",
            options: {
                rules: [/\.scss$|\.sass$/, ".sass", ...],
                cssLoaderOptions: CssLoaderOptions,
                postCssLoaderPseudoClassesPluginOptions: {
                    prefix: 'pseudo-states--', // default for angular
                    blacklist: [':nth-child', ':nth-of-type']
                }
            }
        }     
    ] 
}

If you set another prefix you have to set the same for the addon, too. Therefore, add the following to your .storybook/preview.js:

addParameters({
    withPseudo: {
        prefix: "still-pseudo-states--",
    },
});

Own Webpack config (but automatically generated with PostCss)

When you have configured your own webpack config but still want to use this addon with PostCSS, add postcss-loader to you webpack config.

ATTENTION: When using CSS-Modules, you have to take care that no [hash] is used as localIdentName in your css-loader options.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(scss|css)$/,
        use: [
          {
            loader: 'style-loader',
          },
          {
            loader: 'css-loader',
            options: {
              // ATTENTION when using css modules
              modules: {
                // !!! must not use [hash]'
                localIdentName: '[path][name]__[local]',
              },
            },
          },
          // Add loader here
          {
            loader: 'postcss-loader',
          },
          {
            loader: 'sass-loader',
          },
        ],
      },
    ],
  },
};

Aditionally, you have to enable the postcss-peudo-classes module it your postcss.config.js

module.exports = {
  plugins: {
    'postcss-pseudo-classes': {
      // prefix: 'pseudoclass--',
    },
  },
};

When using a custom `prefix` parameter, use the same for postcss-pseudo-classes

module.exports = {
  plugins: {
    'postcss-pseudo-classes': {
      prefix: 'pseudoclass-example-prefix',
    },
  },
};

Manually

When you do not want that the pseudo classes are generated for you, you can provide your own rule on which the plugin looks for your css classes.

Per default, the prefix used in the addon to look for css classes is \:. To add the needed styles you have to add fakle classes consisting of prefix + pseudostate by yourself.

For example: When you want the hover and focus states to be shown by the plugin, you have to add \:hover and \:focus classes to your styles by yourself.

For the default prefix this may look like this:

.element {
  //element styling

  &:hover,
  &\:hover {
    // hover styling
  }
}

With a custom prefix

If you want to specify your own prefix, set it as prefix value in the addons parameters object.

To change the prefix to .pseudoclass-- you have to adjust the parameter like this:

// in your story
parameters: {
    withPseudo: {
        selector: "element",
        prefix: "pseudoclass--"
    }
}

And use the specified prefix in your styling definition:

.element {
  //element styling

  &:hover,
  &.pseudoclass--hover {
    // hover styling
  }
}

With babel plugin for Emotion.js

If you use emotion.js to style your components might want to consider using babel-plugin-storybook-addon-pseudo-states-emotion. It will create pseudo-classes for your components.

With a babel-plugin-storybook-addon-pseudo-states-emotion

This babel-plugin was made for this exact use-case. If you have questions or issues please look at the documentation or contact the repository owners.

Configure:

Please look at the options for babel or webpack configurations in storybook:

1. https://storybook.js.org/docs/react/configure/babel
2. https://storybook.js.org/docs/react/configure/webpack#extending-storybooks-webpack-config

Here's an example of the plugin configuration. (please refer to the original documentation)

Basic integration

{
  "plugins": ["babel-plugin-storybook-addon-pseudo-states-emotion"]
}

Adding a custom prefix as supported by the addon

{
  "plugins": [
    [
      "babel-plugin-storybook-addon-pseudo-states-emotion",
      {"prefix": "pseudoclass--" }
    ]
  ]
}

Show/Hide Toolbar-Button

You can enable a toolbar button that toggles the Pseudo States in the Preview area.

See Framework Support which Frameworks support this feature.

Enable the button by adding it to your addon configuration file (located in the Storybook config directory)

For version < 5.3.x

Import the addon in your addons.js file:

import "@ergosign/storybook-addon-pseudo-states-react/register";

For version >= 5.3.x

Add it to the addons section in your main.js file.

module.exports = {
  "addons": [
    '@ergosign/storybook-addon-pseudo-states-react/register'
  ]
}

Usage

WARNING: withPseudo should always the first element in your decorators array because it alters the template of the story.

General

Component Story Format (CSF, recommended)

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-react';

const section = {
  title: 'Button',
  decorators: [withPseudo],
  parameters: {
    withPseudo: { selector: 'button' },
  },
};
export default section;

export const Story = () => {
  return {
    component: ButtonComponent,
  };
};

storyOf Format

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-react';

storiesOf('Button', module)
  .addDecorator(withPseudo)
  .addParameters({
    withPseudo: {
      selector: 'button', // css selector of pseudo state's host element
      pseudos: ['focus', 'hover', 'hover & focus', 'active'],
      attributes: ['disabled', 'readonly', 'error'],
    },
  })
  .add('Icon Button', () => <Button />);

There is a default configuration for selector, pseudos and attributes. Thus, you can leave withPseudo options empty.

Parameters & Types

See Types