Variants

Variants are a concept that is usually only needed for more advanced design.

A page or component can have multiple variants that let the page or component appear differently in different circumstances.

The most common use is for responsive design of pages—see responsive design using screen variants. These are what are called global variants.

As another example, a Button component might have Small, Medium, and Large variants, and also Primary, Secondary, and Danger variants. This section will just focus on such component-specific variants.

Variants overview

All variants are either:

• Toggle variants: these are either on or off. These are the most common.
• Organized into single-choice groups. For example, you might have a variant group called “Size” containing variants Small, Medium, and Large, as well as a variant group called “Type” containing variants Primary, Secondary, and Danger.
• Organized into multiple-choice groups. Any of the variants in these groups can be independently toggled on and off—it’s basically just a way to group together a bunch of toggle variants.

All components also have a base variant that defines its default appearance. You can see the organization in the floating Component Panel, which is where you can create and delete variant groups and variants.

Variants in any group are optional—your instances of Button can leave “Type” unset, so is neither Primary/Secondary; in that case, the Button will simply be displaying its “base” state.

The non-base variants hold style settings that override styles in the base variant. By default a variant inherits all the styles of the base variant. For instance, your Button’s Large variant might inherit all the same styles from of the Button’s base variant, but override only the font size of the button text. If you later make the Button rounded (in the base variant), your Large Button also becomes rounded.

This is also what lets you see a Button in a combination of variants. For instance, you can view a Button whose Size is Large and Type is Primary. Again, each variant only overrides specific styles, so Large overrides the font size, and Primary overrides the background color and text color.

We recommend that you put most of the Component styles in the base variant, and only put necessary override styles in the other variants; this allows you to share as much style as possible between the different variants of your component.

How to edit variants

To record some edits that are specific to a variant, first activate recording to that variant.

If you are in normal editing mode, you can select the variant from the toolbar. If you are in design mode, you usually will see a dedicated artboard for each variant, so you can make your edits there. Lastly, you can aso select the variant from the Page Data or Component Data tab.

The selected variant will light up in red, indicating that you are now recording changes for that variant. As you make changes in the right panel, a red dot next to a style setting will indicate that it’s defined in the current variant, overriding the base variant. You can clear the override by right-clicking it and choosing Remove Style. To stop making style changes to a variant and go back to the base variant, simply select the base variant again in the Component Panel.

To add/remove/manage the variants and variant groups, switch to the Page Data or Component Data tab, and find the variants toward the bottom.

What variants can override

Variants can override a few things:

• Design styles: Most styles in the Design tab in the right sidebar can be overridden.

  

• Visibility — whether the node is rendered at all or omitted in a variant. For instance, a sidebar in a screen design might be visible only on the desktop variant and not a mobile variant. Visibility can be toggled with the eye icon in the Tree in the left sidebar.

• HTML attributes, such as the placeholder for an input textbox, or the src for an image.

• Component props and variants. If your component contains other component instances, then what variant(s) you want active onyou can override props you set and what those other components. For example, a ProfileCard component might contain a Button instance for following/unfollowing a user, which we want to enable or disable depending on whether the current user is following the person in the ProfileCard. The ProfileCard then might have two variants — a “following” variant, where the Button instance has the “Type = Disabled” variant activated, and a “not-following” variant, where the Button instance has the “Type = Primary” variant activated.

Interaction variants

You may want to define variants that correspond to common interactions, such as the hovered and pressed states of a Button. You can create special interaction variants for some fundamental interaction types, including Hovered, Pressed, Disabled, and Focused. They’re special because when you switch into Preview mode (by pressing the Play button in the top toolbar), you can immediately see these variants in action by interacting with your design.

You can also define these to be any combination of the above. For instance, you may want an interaction variant for when the button is “Hovered and Not Disabled.”

Interaction variants are always defined as nested under some other (normal) variant.

Targeting combinations of variants

So far, we’ve said how you can record edits to your design that are specific to some variant.

However, you can also record edits that are specific to a combination of variants—apply these differences when multiple variants are active.

For instance, let’s say you have a Button that is blue text on white background normally.

It also has:

• A Hovered interaction variant that is brighter blue text on white background.
• A Primary variant that is white text on blue background.

But what happens when you are hovering over a primary button? Say this is what we want:

• When Hovered and Primary, have white text on a bright blue background.

You can record to specific combinations of variants like this. Typically, from the canvas you can add a combination artboard to your component, and from there specify targeting the combination you want.

Global variants and screen variants

See global variants and responsive design.

Have feedback on this page? Let us know on our forum.