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"
  }
  ...
}

To apply it to all stories, add it to the Import defaults configuration.

: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"
  }
  ...
}

:excludeSelector

This selector drops matching elements from the capture, keeping everything else.

It is useful when you point :selector at a container in order to capture several elements together, but that container also holds something you don’t want. A modal is the typical case: the overlay and the dialog are rendered outside the Storybook root, so capturing them together means capturing their common ancestor, which also contains the button that opened the modal.

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

Example

Capture a modal with its overlay, without the button that opens it:

{
  "initArgs": {
    ":selector": "body",
    ":actionSelector": "#storybook-root button",
    ":tap": true,
    ":excludeSelector": "#storybook-root",
    ":width": "1280px",
    ":height": "720px"
  }
  ...
}

A body capture sizes itself relative to its parent, which no longer exists once it is a component, so give it an explicit :width and :height - otherwise the imported frame collapses around whatever in-flow content is left while the modal and its overlay, being positioned, spill outside it.

: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">'}
      ]
    }

To apply it to all stories, add it to the Import defaults configuration.

:story

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

:width and :height

Those two arguments respectively affect the width and height of your components. Their default value, Try to hug (auto in the Advanced Mode), implies that story.to.design will try to make your component hug if that’s possible.

That default value is usually good enough to get the expected results. In some cases, you will want to explicitly set the width and/or height of your component, in which case you can used the Fixed value and specify the values you want.