Skip Navigation

Documentation

Variants

Updated

Variants let you keep every version of a component together as one component. For example, you can make a single button component with variants organized by properties like State (Default, Hover, Pressed), Theme (Dark, Light), and Size (Regular, Large).

Without variants, you’d need a separate component for each combination — and as your libraries and design systems grow, that number grows quickly. With variants, you need far fewer components to cover every state, theme, and size in your designs.

Useful shortcuts

Create component, add variant, or combine as variants ⌘Y
Select matching layers ⇧⌘M

Creating variants

To create a variant, select an existing component source and press ⌘Y, or choose Add Variant add.variant in the toolbar, the inspector menu, or the command bar.

⌘Y adapts to what you have selected. With a single component source selected, it’s Add Variant add.variant. With several component sources selected, it’s Combine as Variants. With anything else selected, it’s Create Component, which turns your selection into a new component.

Once a component has variants, you’ll see an Add Variant button add.variant on the canvas when you select its component source or one of its variants. Click it to duplicate your selection as a new variant. Component instances don’t show this button.

If you select the variant set itself, the Add Variant button add.variant appears to the right of it. Click it to duplicate the component’s default variant.

When you add the first variant to a component, Sketch sets up a placeholder property called Property 1, with Value 1 for the original and Value 2 for the new variant. Rename them in the inspector to describe what changes between your variants.

If a component has a single property, each variant you add gets its own new value. A copy of a placeholder value takes the next free number, such as Value 3, and a copy of a named value gets “Copy” added to its name, such as Large Copy. If a component has several properties, or a single toggle property, the new variant keeps the same values as the one you duplicated.

Combining components as variants

If you already have separate components for each version of something, select their sources and choose Combine as Variants. Any instances of those components stay attached to the new component, so you don’t need to replace them.

We use the names/groupings of the components to pre-fill the new component’s properties. For example, components named Button/Dark/Hover and Button/Light/Pressed give you a property for theme and another for state. If the names don’t suggest any properties, Sketch adds a placeholder Property 1 with a different value for each variant.

Where variants live

A component source and its variants live together in a variant set variant.set. In practice, a variant set is a section that holds the component source and all of its variants, wherever your component source lives — on a components page or anywhere else in your document.

A variant set can only contain component sources and nested sections. Everything else on the Sections page applies to variant sets too.

You name the component, not each variant. You can’t rename variants individually, because their property values describe them. If you double-click a variant’s name in the layer list, Sketch reminds you to change its property values in the inspector instead.

Properties and values

Properties describe the ways your variants differ, and values are the options for each property. A button might have a State property with Default, Hover, and Pressed values.

To add a property, select the variant set and use the Variants section of the inspector:

  1. Click Add Variant Property circle.plus. In the Variant Property panel that opens, enter a name for the property.
  2. To add more values, click Add Value circle.plus, or press ⌘⏎ while you’re editing a value to add another below it.

If it’s the component’s first property, Sketch gives each variant its own placeholder value (Value 1, Value 2, and so on). Any property you add after that starts with a single Value 1, shared by every variant. Placeholder values always take the lowest free number.

To edit a single variant’s properties, select that variant. In the inspector, click a property’s name to rename it, or click its value to change it or add a new value. The value picker lets you search for an existing value, or type a new one to add it. To add a new property from here, click the circle.plus button next to the Properties heading.

Changing values on the canvas

Each variant shows its property values as pills on the canvas. To change a value without going to the inspector, select the variant, then click one of its pills. In the menu that opens, choose another value, or type to add a new one. This only changes the variant you clicked. If you rename a value from this menu, the new name applies to every variant that uses it.

Variants that don’t have a value for a property show a No Values pill with a dashed outline.

When you’ve selected a variant, you’ll also see a dots.3.horizontal button next to each property. Use it to select every variant with the same value, or to remove the property.

Toggle properties

For properties that switch something on or off, like whether a button shows an icon, give the property exactly two values from one of these pairs:

  • True and False
  • On and Off
  • Yes and No (or their Chinese and Spanish equivalents)

When a property uses one of these pairs, the inspector shows it as a simple toggle instead of a list of values.

Fixing issues with variants

When something doesn’t add up in a set of variants, we show the number of issues in the inspector. Click it to see the details. Issues fall into four groups:

  • Incomplete: some variants are missing values for a property.
  • Conflicts: two or more variants share exactly the same combination of values, so we can’t tell them apart.
  • Unused Properties: a property that none of the variants use.
  • Unused Values: a value that no variant uses.

To clean up, click the remove button in the Unused Properties or Unused Values group to delete everything listed there. You can do this on the canvas or in the assets view.

If a component with variants has no properties at all, you’ll see a No Properties warning. Click Add Property in the Issues panel to add one.

Component and variant settings

Some settings apply to the whole component and others apply to a single variant:

  • Component Settings, such as where the component is available, apply to every variant.
  • Variant Settings, such as which overrides are available and export options, apply only to the variant you’ve selected.

Using variants in your designs

When you browse components to insert, we show a single component for each set of variants, marked with the variants icon variant.set, rather than every variant. This keeps long lists of components easier to work with.

After you insert an instance, use the properties in the inspector to swap it to a different variant. Instances use the component’s name, not the name of the variant they show.

In the assets view, you can preview different variants of a component using its properties. Click the Reset to default variant button arrow.counterclockwise in the Variants section of the inspector to go back to the default.

Selecting matching layers

To change the same layer in every variant at once, such as a button’s label or icon, select it in one variant and press ⇧⌘M (Edit > Select > Select Matching Layers). Sketch selects the matching layer in every other variant of the component, so you can edit them all together. Find out more about how matching works in Selecting layers.

Did you find this useful?