Documentation

  • Getting Started
  • Using Visly from code
  • Version Control
  • Tokens
  • Layers
  • Primitives
  • Interaction States
  • Variants
  • Props & Slots
  • Composition & Inner Components
  • Built-ins
  • Responsive Design

Tutorials

  • Using Visly with Create React App
  • Using Visly with Next.js
  • Using Visly with Gatsby
  • Creating stateful components
  • Routing with Visly
  • Using variants for responsive design
  • Create dynamic UI with inner components
  • Reuse existing components with Slots

Documentation

Variants

Variants are a way to express different versions of a single component. This is useful for many reasons. They can be used as a way to share styles between very similar components, but also to express states additional to those built into Interaction States (hover, pressed, focus and disabled). Variants are commonly used to express things like the size of a component (small, medium, large), type (primary, secondary), or to express properties of a component (withIcon, noImage).

Variants can be either enums or booleans. Boolean variants map to a single variation of the component, while enum variants can be set to one of multiple values. To add a variant to a component, click the [+] icon in the bottom left panel.

Variants can be selected in this panel by clicking on them or by selecting the corresponding frame on the canvas. Styles you configure will be applied to the selected variant as an override from the base component, just like how Interaction States work. All variants of a component will map to Props & Slots that can be used to enable that variant dynamically. A component can have any number of variants, and each individual variant can be enabled independently of one another.

import { Button } from '../visly'

<Button size="small" selected />

In the above example size is an enum variant which can have values such as small, medium, and large, while selected is a boolean variant and can simply be turned on or off.

Boolean variants

Boolean variants are the simplest example of variants in Visly. Create them by pressing the + button in the props panel next to the variants heading in the bottom left of the editor and select the boolean options. Once created, you can double click the variant in this list to give it a descriptive name.

After you've created a boolean enum it will show up on the canvas as a frame (or multiple frames if you are building an Interaction States). Select the layer you want to edit within the appropriate frame on the canvas to make changes to this layer within the selected variant / state combination.

When selecting a layer for a variant that you haven't configured yet you'll notice that all the style sections are collapsed, this just means that the variant currently doesn't override any styles. Just click the + button to add an override that'll be used when the component is in this variant.

When importing a component with a boolean variant from code, this variant will be exposed as a boolean prop on that component. In the example below, we have created a selected variant on a Button component. Boolean variants always default to false if not specified.

import { Button } from '../visly'

<Button selected />

Enum variants

Enum variants are created in the same way that boolean variants are created, the only difference being that you choose the enum option instead of the boolean option after pressing the + button next to the variants heading in the bottom left of the editor. However, you'll immediately notice that the result is a bit different.

Instead of creating a single row in the variants panel, the option for creating an enum variant adds a top level row as well as a nested row below. The top level row created (default to customProp as seen above) is the name of the enum prop, and all the rows nested beneath this enum are the enum's options. Next to the row that represents the enum prop, you'll see a + button - this button adds another option to the enum. Just like with boolean enums, you are able to double click on the rows to rename both the enum prop itself as well as its options. Adding a few options and renaming them may result in something that looks like this:

In the above example an enum variant representing size variation for this component has been created and includes three different size options (small, medium, and large). From this point on, enum variants work exactly like boolean variants. They will show up on the canvas as a frame (or multiple frames if you are building an Interaction States). Select the layer you want to edit within the appropriate frame on the canvas to make changes to this layer within the selected variant / state combination.

When importing a component with an enum variant from code, this variant will be exposed as a prop on that component, which accepts a string mapping to one of the options of your enum. In the example below, we have created a size variant on a Button component. By default, enum variants have no value, so none of the size options will be used and the default component size is used instead.

import { Button } from '../visly'

<Button size="small" />

Inheritence and multiple variants

Variants of a component inherit styles from the base component, and are applied in a top-down order based on canvas position when multiple variants are applied to single component.

Consider a button component with both a small and an error variant. Both the small and error variants inherit their styles from the base component, but because the error variant is listed further down on the canvas, it will apply its styles after the small variant.

This doesn't matter in this case because these two variants changed different styles of the component, but if we were to add a green variant that changed the color of the button to green, then order would matter when declaring a green+error button. To change the order in which variants are applied, you can press the button that looks like a down arrow next to the relevant variant.