Before you start

Who can use this feature

Variants are supported on any team or plan. Publishing component sets to a library is only supported Professional and Education teams, or Figma Organizations.

Anyone with Can edit access to a file can create variants and component sets in that file.

Anyone with Can view access to a file can use components or components sets from that library.

As you create components and build out your design system, you'll find the need for components that are similar to each other, with only slight differences.

For example: you might have multiple components for buttons, with separate components for various states and sizes, as well as light and dark modes.

Variants allow you to group and organize similar components into a single container. This simplifies your component library and makes it easier for everyone to find what they need.

Customize the properties and values of your variants, to take the guesswork out of your design system and bring your components closer to front-end code.

Variant properties and values

Variant properties and their values allow you to define the attributes of your variants. Variant properties are a type of component property specific to variants and component sets.

You can add as many properties and values as you need, and customize them to suit your design system. You can even map your properties and values to code components in your design system.

• Variable properties are the variable aspects of our component. For example: the properties of a button component could be the size, state, or color.
• Values are the different options available for each property. For example: the state property could have default, hover, pressed, and disabled values.

All variants within the component set should use the same properties and values, but each variant needs to be a unique combination of them. You don’t need to have a component for every possible combination of properties and values.

Rename your components

Figma uses the slash naming system to organize components in the Assets panel and Instance menu. Each / in a component's name will create another level of hierarchy.

This makes it easier to navigate your library, or find and swap related components. Learn how to name and organize components →

You can also use this naming system to convert your existing components to variants. To be accurately converted, component names need to follow this structure:

componentName/property1value/property2value/property3value

• The text before the first / will become the name of the component set.
• Figma will create a new property for every other / in the component's name, then add the attribute as a value.
• If you have used suffixes in your naming system, you will need to add these to the component's name, separated by a /.

A button component with the name Button/Primary/Large/Default/False will have the following properties and values:

Component set name: Button
Variant: Primary
Property 2: Large
Property 3: Default
Property 4: False

In the image below, we can see how the rest of our component names (on the left) are converted to variant values (on the right).

Organize components on the canvas

If you have a lot of variants for a particular component, you may want to organize your components in rows, columns, or grids.

This will help to communicate their multi-dimensional nature to anyone who's using your design system. You can also add text layers beside your component set to annotate the relevant properties and values.

In our example below, we've arranged our button variants in a grid. We've also added text layers to the canvas that correspond to a property's values.

Combine as variants

1. Select the components you want to combine. Learn how to select layers and objects →
2. In the right sidebar, click the Combine as Variants button.
3. Figma will add all components to a single component set.

Give properties descriptive names

As part of the conversion process, Figma will create generic properties and add any attributes you added to the component's name as values.

As Figma doesn't know the names of the properties, it will name the first property Variant, then number them sequentially: Property 2, then Property 3, and so on.

You'll need to rename those properties to something more descriptive.

1. Select the component set.
2. View the current properties in the Variants section in the right sidebar.
3. Hover over the property so a grey box appears around it.
4. Click to edit the property and give it a more descriptive name.
5. Click outside the property to apply.
6. Repeat for the remaining properties.

Create new variants

There are a few ways to create a new variant. Select a main component and:

• Click from the toolbar, or
• Right-click the main component > Main component > Add variant, or
• Click in the Properties section of the right sidebar > Variant. This creates a new variant property and turns the main component into a component set.
  From there, click below the component set to add a variant.

Figma will do a few things:

• Make an identical component with the same properties
• Add both components as variants to a component set
• If you used the slash naming convention, the text before the / will become the name of the component set, and the attributes after will be used as values.

You can also create new variants by combining multiple components ↑. 

If you have an existing component set, add more variants ↓ to it at any time. 

Add properties and values

Create and apply properties and values to your variants when you first create them, or as your design system evolves. Learn how to create and apply properties and values →

Add more variants to a component set

Continue to add variants to your component set using any of the following methods:

• Select a component set and click in the toolbar.
• Select a component set and click on just below the component set. You'll only see this option once you have at least two variants.
• Duplicate existing variant using the keyboard shortcut:
  • Mac: ⌘ CommandD
  • Windows: CtrlD
• Drag other components into the component set to add them as variants.

Manage variants

Organize variants

When you add new variants to a component, Figma's default behavior is to add variants in a single column, with equal spacing between them.

If you have your components in another layout before converting them, Figma will keep the same layout for the component set.

You can override Figma's default behavior and arrange variants in any way you choose.

• Select a variant and move it to new co-ordinates within the component set. Figma will allow you to place variants anywhere within the component set, including over the top of other variants.
• Adjust the dimensions of the component set in the right sidebar, or resize it in the canvas like you would a regular frame.
• With all variants selected: Use the fields in the right sidebar to adjust the horizontal and vertical space between variants.

Manage properties and values

You can rename and reorder properties and values anytime after creation. Remove properties you no longer need. Learn how to rename properties and values →

• If you reorder properties, Figma will adjust the name and syntax of your variants to match.
• If you've converted your existing components to variants, you'll need to rename your properties to make them more descriptive.

 

Publish component sets to a library

If you're a member of a Professional or Education team, or a Figma Organization, you can share your variants with collaborators.

Publish component sets alongside your styles and regular components to allow members of your team or organization to use them.

Component sets appear in the Assets panel alongside your other components. Figma will use the variant in the top-left corner of the component set as the default variant.

Collaborators can then drag the component set into their files to create an instance. They can then access all the other variants in the component set by configuring the property values in the right sidebar.

Learn how to publish libraries →

Use variants

Component sets appear in the Assets panel alongside any regular components. So instead of looking for a specific variant in the Assets panel, you only need to select the component set.

Once you have an instance of that component set on the canvas, you can configure the instance's property values to select a variant.

Select component sets

1. Click on the Assets tab in the left sidebar, or use the keyboard shortcut:
   • Mac: ⌥ Option 2
   • Windows: Alt + 2
2. Click on a component set and drag it on to the canvas. Figma will create an instance of the default variant of that component set.
3. View the component set's name and properties in the right sidebar.
4. Use the next to the property to select your preferred combination of values.
5. Turn specific properties off and on using the and toggle switches.

Configure variants

Select other variants in a component set by configuring the properties and values in the right sidebar.

1. Select the instance.
2. View the name of the component in the right sidebar. If the component has variants, you'll see fields underneath the component name to configure the properties and values of that component set.
   • Use the next to the property to select your preferred combination of values.
   • Turn specific properties off and on using the and toggle switches

Override preservation

Figma will attempt to preserve your overrides when you select a different variant, or swap between instances in the Instance menu.

Figma uses the following criteria to determine whether to preserve an override:

• Layer names need to match between the current instance and the variant or instance you're selecting. This applies both when swapping instances and selecting variants
• When selecting variants, Figma will also check if the layer properties you’ve overridden originally match between variants. If so, Figma will preserve your overrides.

In our example below, Figma preserves the fill override on Step 3, but not on Step 4. This is because the default primary button and hover primary button both started with the same fill of #1BC47D. Our override was to change the hex code from #1BC47D to #F531B3.

Figma doesn't preserve our override in Step 4 as the hover secondary variant has a fill of #ffffff, which is different to the fill we applied our original override to (#1BC47D).