Figma Component Properties and Variants Explained with Examples
· 3 min read · by the ProFigma team
Component properties and variants make one Figma component behave like many. A single button can switch size, show or hide an icon, change its label and swap the icon, all from the right panel. This guide explains the four kinds of properties, when to use each one, and how they work together in a real example.
The four types of component properties
| Property | What it controls | Example |
|---|---|---|
| Variant | Which version of the component you see | Size: small, medium, large |
| Boolean | Whether a layer is visible | Show icon: on or off |
| Text | The text on a text layer | Label: "Save changes" |
| Instance swap | Which nested component sits in a spot | Icon: plus, arrow, check |
Variants
A variant is a different version of the same component, grouped in a component set. Each variant is defined by one or more properties and values. For a button you might have Type (primary, secondary, ghost), Size (small, medium, large) and State (default, hover, disabled). Figma lists every combination, and each instance gets a dropdown for every property.
Use variants when the versions look or are built differently, such as a different color, a different layout or a different state. Variant properties can only be created on the parent component set. Select the main component, click the plus next to Variants, and add a property.
Boolean properties
A boolean property shows or hides a layer. It is the right tool for optional parts: an icon, a badge, a helper text. Without it, you would need one variant with the icon and one without, for every combination. With it, you add one toggle. Select the layer inside the main component, click the property icon next to Visibility, and name the property, for example "Show icon".
Text properties
A text property exposes the text of a layer in the right panel, so people can edit the label without double clicking into the layer. Select the text layer, click the property icon next to the Text content, and name it, for example "Label". It keeps the layout clean for people who only change words.
Instance swap properties
An instance swap lets people replace a nested component, such as an icon, with another one from a list of options. Select the nested instance, click the property icon next to the component name, and set a default. You can also set preferred instances, so the right icons are easy to find. This is better than detaching, because the swap keeps the link to your library.
Example: one button, many uses
- Build the button with auto layout: an icon, a label and padding.
- Create the component with Ctrl + Alt + K.
- Add variants for Type and Size.
- Add a boolean property for the icon and a text property for the label.
- Add an instance swap for the icon, with a few preferred icons.
Now a designer can place a button, type a label, turn the icon off or swap it, and choose primary or secondary, without opening the main component. One component replaces dozens of separate buttons.
When to choose a variant and when to choose a property
- Use variants when the structure or style changes, for example a hover state or a large size.
- Use boolean, text and swap properties when only the content changes, for example the label or an optional icon.
- If you have more than about 30 variants, check whether some of them should be boolean properties instead.
Tips
- Name properties for what they do ("Show icon", "Size"), not how they look.
- Keep values short and in lowercase or title case consistently.
- Set sensible defaults, so a new instance looks right without changes.
- Test the component by placing it and trying every property before you share it.
Quick answers
What is the difference between a variant and a component property?
Variants switch between whole versions of a component. Properties change one detail, such as a text, a layer's visibility or a nested icon.
Where do I add properties?
Select the main component, then use the plus icon in the Properties section of the Design panel.
See how it looks in practice: our free Figma components use variants and auto layout, so you can open them and inspect the setup. New to components? Start with how to create a component in Figma.
