Before you start
Who can use this feature
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.
Note: We don't recommend using variants to group different icons.If you have different sizes of the same icon, then you could combine these as variants instead.
Properties and values
Properties and their values allow you to define attributes of your variants.
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.
- Properties are the variable aspects of our component. For example: the properties of a button component could be the
type, size, state, or whether it has an icon.
- 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 will 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.
Properties and values in action
Let's take a look at an example! We have a button component that has 24 unique variants. The image below shows all of the variants for this component inside a single component set.
There are four properties in our button component set, each with its own set of values.
- Type property with Primary and Secondary values.
- Size property with Large and Small values.
- State property with Default, Pressed, and Inactive values.
- Icon property has True and False values.
Figma uses these properties and values to determine which variant we need from the component set. In the image below, we've created an instance of our component set and configured the following values:
- Type: Primary
- Size: Large
- State: Default
- Icon: False (or off)
Layer names and syntax
Layer naming is an important aspect of creating and managing variants. Unlike other layer names in Figma, which can be mostly arbitrary, the names of variants in a component set have a very specific syntax.
This includes information about the properties and values of that variant. You can only see this syntax when you try to rename a variant in the layers panel.
Variant names follow this structure: Property1=value, Property2=value, Property3=value
Combine components as variants
Caution: When you add an instance with variants to a file, Figma will import every variant in that component set. Importing large component sets will impact Figma's speed and performance.
If you already have component libraries in Figma, you can combine your components as variants. The general process looks like this:
- Rename your components so they use the slash naming convention
- Organize your components on the canvas
- Combine components as variants
- Give your properties descriptive names
Note: Figma only looks at layer names when combining components as variants, not page and frame names. If you were using pages or frames to organize components, these will become redundant on conversion.
You’ll still be able to use pages and top-level frames to create extra levels of hierarchy. This makes for better component organization in the Assets panel and Instance menu.
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
/.
Caution: To make sure your values match up with the same property, every component you are combining needs to have the same number of slashes.
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
Note: Component sets can only contain components, so it's not possible to add text or annotations, nest frames, or group a subset of variants inside a component set.
When combining components as variants, Figma will apply your existing layout and spacing to variants inside the component set. We recommend organizing your components before converting them, to save you having to rearrange them after.
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.
Tip! By default, component sets have a dashed-purple stroke and no fill. You can adjust the fill and stroke properties of the component set to better suit your brand or design system.
Combine as variants
- Select the components you want to combine. Learn how to select layers and objects →
- In the right sidebar, click the Combine as Variants button.
- 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.
- Select the component set.
- View the current properties in the Variants section in the right sidebar.
- Hover over the property so a grey box appears around it.
- Click to edit the property and give it a more descriptive name.
- Click outside the property to apply.
- Repeat for the remaining properties.
Note: Figma handles component sets the same way as regular components. You can add descriptions and links to documentation to them. You can also drag them into the canvas from the Assets panel, and swap between instances of them.
Create new variants
Note: Figma places variants in a single container called a component set. Component sets can only contain components. Click Create component in the toolbar, or use the keyboard shortcut to turn your selection into a component:
- Mac: ⌥ Option ⌘ Command K
- Windows: Ctrl + Alt + K
Learn how to create components →
- Select a component
- Rename the component so it uses the slash naming convention (recommended).
- In the right sidebar, click the under the Variants section to add your first 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.
- Make any visual changes to the variant as required.
Tip! By default, component sets have a dashed-purple stroke and no fill. You can adjust the fill and stroke properties of the component set to better suit your brand or style guide.
Add properties and values
Add properties and values to your variants when you first create them, or as your design system evolves.
Add properties to the component set:
- Select the component set.
- Click the in the Variant section of the right sidebar.
- Select Add New Property.
You can only add values when you have a variant selected. There are a few ways to do this:
- Click the next to the current value and select Add new from the options.
- Click into the value field and enter in a new value.
- Double-click on the variant in the layers panel and update the value for the desired property.
Tip! If you have a property that has only two possible options, Figma considers this a binary choice or a boolean value and can represent that property as a toggle switch. Figma recognizes both true/false and on/off as boolean values.
Fix conflicted value errors All variants within the component set will use the same properties and values, but each variant needs to be a unique combination of them.
If any variants have the exact same combination of values, Figma will let you know that there is a conflict. You'll see this error even if the variants themselves are visually different.
To resolve this issue, you'll need to add or update the values of the affected variants, so they have a unique combination of values.
Add more variants to a component set
Continue to add variants to your component set using any of the following methods:
- Click on the canvas, inside the component set. You'll only see this option once you have at least two variants.
- Click in the Variants section of the right sidebar and select Add New Variant.
- Duplicate existing variant using the keyboard shortcut:
- Mac: ⌘ Command D
- Windows: Ctrl + D
- Drag other components into the component set to add them as variants.
Caution: When you add an instance with variants to a file, Figma will import every variant in that component set. Importing large component sets will impact Figma's speed and performance.
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.
Note: Figma will use the variant in the top-left corner as the default variant. This variant will represent the entire component set in the Assets panel.
Rename properties and values
To rename a property or value, you'll need to select the component set and update the property or value in the Variants section of the right sidebar.
To rename a property:
- Click on the property and enter a more descriptive name.
- Press the
Enter / Return key to apply or click outside the property to apply.
- Repeat for the remaining properties.
To rename a value:
- Double-click on the value and enter a new name.
- Press the
Enter / Return key to apply.
Note: If you've converted your existing components to variants, you'll need to rename your properties to make them more descriptive.
Fix corrupted variant errors You will get a corrupted variant error if any of your variants do not follow this syntax. This can happen if you mistype a property or value, or use an invalid naming structure when converting existing components.
To fix this issue, you'll need to rename the properties and values of the variant. While it's possible to rename them using this syntax in the layer name, we recommend renaming properties and values in the right sidebar instead.
Reorder properties and values
You can change the order that properties and values appear in the right sidebar. If you reorder properties, Figma will adjust the name and syntax of your variants to match.
To reorder properties:
- Select the component set.
- In the Variants section, hover over the left edge of the property field until the appears.
- Click and drag the property up or down to change its order.
To reorder values:
- Click and hold on the value.
- Drag to value so its in the new order.
- Release to apply.
Remove properties
To remove a property:
- Select the component set.
- Hover over the property in the Variant section of the sidebar.
- Click to remove.
Note: Figma will only keep values that are currently applied to a variant. You can remove a value by making sure no variant uses it.
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
- Click on the Assets tab in the left sidebar, or use the keyboard shortcut:
- Mac: ⌥ Option 2
- Windows: Alt + 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.
- View the component set's name and properties in the right sidebar.
- Use the next to the property to select your preferred combination of values.
- 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.
- Select the instance.
- 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
Swap between instances
You can still swap between instances when using variants, like you would with regular components.
The most efficient way to do this is using the Instance menu. The Instance menu allows you to find component replacements from the current file, or any of your enabled team libraries.
Access the Instance menu from the properties panel in the right sidebar, when you have a component selected.
- Select the instance you want to change.
- Click on the component name in the right sidebar.
- Use the instance menu to search for and select another component.
Learn how to swap using the instance menu →
Override properties
Component libraries define and outline the ideal implementation of our design system.
These components often contain generic information which you'll need to change, like a button label. Under some circumstances, you may need to change other aspects of that specific instance.
Overrides allow you to make superficial changes to instances. Figma supports overrides to text, fill, stroke, and effect properties. Learn more about supported overrides →
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).
Tip! If you're not sure what variants are available in a component set, or their original styling, you can view the component set in the original file. With the instance selected, click the next to the component name in the right sidebar.
