Variants has arrived! 🎉 For detailed instructions on how to use variants, check out our Create and use variants article.
Variants introduce a new way to group and organize variants of the same component. This makes components easier to maintain and more intuitive to use.
Combine variants into a single component with custom properties and values. These can mirror front-end code, simplify asset libraries, and make picking the right variant easier.
You can have as many properties and values as you need. You can define properties and values during the creation process, as well as add, remove, and reorder them as your design system evolves.
In our example, we have a button component which has 24 variants. You can see these variants in this image of our design system:
There are four properties in our example, each containing a 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 with True and False values.
Figma uses this set of properties and values to identify each unique variant. The screenshot below shows this variant in the Instance section of the right sidebar.
Use the next to the property to select your preferred combination of values. Or toggle specific properties off and on using the and switches.
Note: You can only convert components into variants. If your selection includes other layers or objects, you won’t have the option to combine them as variants.
Prepare for variants
There are a couple of things that you can do to make converting your existing design system components as easy as possible.
- Use a consistent naming convention
- Checks for override preservation
- Organize components on the canvas
- Group related components
Note: These suggestions affect how users can select components from libraries in Figma. If this will cause problems for your team, hold off on making these changes until you have access to variants.
Use a consistent naming system
Figma already supports slash
/ naming system to organize components. You can use this naming system to help convert your existing components to Variants.
We recommend using the following structure for any components you want to convert:
- Any text before the first
/will become the component name. Every extra
/level will create a new property.
- By default, Figma will name the first property
Variant, the next
Property 2, then
Property 3, and so on.
- Every variant will need a value for each property. Make sure that each component uses the same number of slashes.
- If you have suffixes in your naming system, you should convert these to
/levels before combining the components as variants. For example: if you have component states for
- pressed, create another
/level for the state.
- When you combine variants into one component, Figma will create toggles for any Yes/No or True/False values.
For example: our button component has the following name:
Once converted, the resulting variant will look like:
Component name: Button Variant: Primary Property 2: Large Property 3: Default Property 4: True
You’ll be able to change the name and order of any properties once you convert them to variants. Reorder properties in the Variants section of the right sidebar. This will also change the order of the values in each variant’s name.
Tip! You can also rename layers in bulk using the rename layers modal. Learn more about renaming layers in bulk →
Checks for override preservation
With this launch, Figma is also changing the way overrides are preserved. Figma will now preserve all supported overrides, including overrides to fill and stroke properties, and blur or shadow effects. This will apply when swapping between instances, as well as selecting different variants.
Figma will use the following criteria to determine whether to preserve an override:
- Layer names need to match between the current instance and the variant 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 the 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 have a matching fill of
#1BC47D. Our override changes the hex code from
Figma doesn't preserve our override when we select the
hover secondary variant, as this variant has a fill of
#ffffff, not the
#1BC47D we applied our override to.
Organize components on the canvas
It can be easier to keep track of all your variants if you lay them out in a grid. The top-level container of a component can’t hold anything other than variants. This means you can't group a set of variants together, or insert text or other annotations into the container.
To annotate your variants, we recommend adding text labels for relevant properties and values beside the variant container.
You don’t need to have a component for every possible combination of properties and values, just the ones that you and your team use. This can include any variants you’ll need for interactive components.
Figma groups variants in a single container. By default, Figma will represent this container with a dashed, purple border. Like regular frames, you can adjust the properties, like fill or stroke, to suit your design system.
Group related components
Figma only looks at layer names when combining components, not page and frame names. If you were using pages or frames to organize variants, these may 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.
You could use an approach similar to Shopify’s Polaris design system. It groups sets of components, that are functionally similar. For example Button and Button Groups under Actions, or Text field and Date picker under Forms.
Create instances of variants: Figma will make sure your instances point to the correct component. When you convert components to variants, any instances will reference the new variant.
Anyone accessing design systems in the Assets panel or Instance menu will see a single result for that component. Once they place an instance on the canvas, they can select the desired variant in the right sidebar.