# Variants

**URL:** https://www.sketch.com/docs/components-and-styles/variants/ | **Last updated:** 2026-11-17

---
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

| Action | Shortcut |
|--------|----------|
| Create component, add variant, or combine as variants | <kbd>⌘</kbd><kbd>Y</kbd> |
| Select matching layers | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>M</kbd> |

## Creating variants

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

> **Note:** <kbd>⌘</kbd><kbd>Y</kbd> adapts to what you have selected. With a single component source selected, it’s **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](/docs/components-and-styles/components/).

Once a component has variants, you’ll see an **Add Variant** button 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](#where-variants-live) itself, the **Add Variant** button 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](#toggle-properties), 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 . In practice, a variant set is a [section](/docs/designing/sections/) 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](/docs/designing/sections/) 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** . In the Variant Property panel that opens, enter a name for the property.
2. To add more values, click **Add Value** , or press <kbd>⌘</kbd><kbd>⏎</kbd> 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 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 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](/docs/components-and-styles/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 , 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](/docs/interface-and-settings/the-mac-app-interface/the-assets-view/), you can preview different variants of a component using its properties. Click the **Reset to default variant** button 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 <kbd>⇧</kbd><kbd>⌘</kbd><kbd>M</kbd> (**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](/docs/designing/layer-basics/selecting-layers/#selecting-matching-layers).