Special Args

Special Args are specific to story.to.design. They allow you to customize how variants are imported. They can be used in the variantProperties API pretty much anywhere an Arg can be defined.

:selector

By default, story.to.design looks for elements to be imported as components under the element with id="root" or id="storybook-root" (for Storybook 7+). However, in some cases, you will want to target a different element. For example:

• A modal that will be rendered with a portal out of the root div.
• If your stories’ elements are decorated with other elements, such as divs with a specific background color, in which case you would not want to import those divs.

The :selector value is a CSS query selector.

Example

{
  "initArgs": {
    ":selector": ".my-provider-class :first-child"
  }
  ...
}

:actionSelector

This special Arg is specific to simulated states. It indicates which element to simulate the state on. For example, you may want to use it for a button group, where you would want to be able to choose which button story.to.design should simulate interactions on.

Like :selector, its value is also a CSS query selector.

Example:

{
  "initArgs": {
    ":actionSelector": ".button-group-class :nth-child(3)"
  }
  ...
}

:portalSelector

This selector is meant to indicate story.to.design if there is a DOM hierarchy to consider outside of the Storybook root. This can typically happen with React Portals or Vue Teleport when rendering modals, tooltips or dropdowns.

Like :selector, its value is also a CSS query selector.

Example

{
  "initArgs": {
    ":portalSelector": ".MyPortalRootClass"
  }
  ...
}

:css

This special Arg allows you to create variants based on CSS themes. Here are a couple simple examples to illustrate it:

Inline CSS theming example

Create 2 themes red and blue that force CSS color:

    {
      "fromArg": ":css",
      "name": "css-theme",
      "values": [
        {"name": "red", "argValue": "<style>* { color: red }</style>"},
        {"name": "blue", "argValue": "<style>* { color: blue }</style>"}
      ]
    }

Stylesheet-based theming example

If you have different stylesheets for different themes, you can easily create variants out of them:

    {
      "fromArg": ":css",
      "name": "theme",
      "values": [
        {"name": "dark", "argValue": '<link rel="stylesheet" href="/css/dark.css">'},
        {"name": "light", "argValue": '<link rel="stylesheet" href="/css/light.css">'}
      ]
    }

:story

In some very specific cases, you may want to import variants for a same component from different stories.