Before you Start
Who can use this feature
Anyone with edit access to the Figma file can create, manage, and use component props in Figma design files
Component properties remove the guesswork out of your design system.
Define which parts of the component people can change by tying them to specific design properties. This allows you to control things like whether layers are visible, if you can swap an icon or change the text, or if effects are applied. 
Like regular components, you can attach descriptions and links to further documentation. This makes sure the people using your components have the right information and context to apply them.
You configure all component properties at an instance level. So there's no need to select and override individual layers.
Warning: It's important to note that component properties don't support prototype interactions. If you want to create prototypes with your components, you'll still need to use variants.
We recommend reviewing your existing design system before you adopt component properties. That way, you can decide which aspects you can reflect as component properties and which need to be variants. Learn more about interactive components →
Property types
Component properties are tied to different design properties. You can create component properties for any main component or component set, and apply them to nested layers of the component or variant.
Component properties come in different types:
Variant property
A variant is an individual component within a component set.
A variant property allows you to define attributes of your variants, such as state, color, or size.
A component set contains multiple variants, and the variants carry attributes that can be defined by variant properties. Variant properties are specific to variants and component sets, and can’t be created or applied to main components. Learn how to create variants and component sets →
In the example below, we have a button component set with four variants. It has two variant properties, size and color. The size values include small and large, while color values include green and red.

Instance swap property
An instance swap property indicates which instances in a main component or variant can be swapped. When creating an instance swap property, you can define the default instance value from any local and enabled libraries.
For anyone using this property, they’ll be provided with an instance swap menu to swap the nested asset out for one within the same component subset, or one from any available library.
Nested instances with this component property can only be swapped at the top-level layer of its parent component. You won’t be able to swap it for another instance if you select the nested instance.
Text property
Use text properties to indicate which text layers should be edited.
Whether you’re managing a text property’s default value or using an instance containing it, the string of text can be edited either from the right sidebar or on the canvas. The value updates in both directions.
Layers without this property can still be updated.
Boolean property
Use boolean properties to set true/false values, allowing users to toggle a regular property on or off.
For example, if a design system contains buttons with and without an icon, instead of creating variants for each state, apply a boolean property to the icon’s layer visibility.
Note: Boolean properties are currently only available for layer visibility.
Create
You can create component properties at two levels: the parent layer or the child layer of a component. Parent, child, and sibling relationships →
Any component property can be created from the parent layer of a component. You can’t create variant properties from a child layer.
From the child layers
Create a component property from a child layer of a variant or main component. This creates the property and applies it to any selected layers at the same time.
This method supports creating instance swap, text, and boolean properties. You can’t create variant properties from a child layer.
Instance swap property
-
Select an instance nested in a main component or variant.
- (Optional) Variant only: Click to select similar layers in the component set. These layers are recognized by having the same hierarchy and name.
-
Next to the swap instance dropdown in the right sidebar, click to create a property. This opens the create component property modal.

-
Give your property a name in the text field
-
Set the default value by using dropdown to select an instance from local components in the file or any enabled libraries.
-
Click create property. When applied, you’ll see a purple pill with the property name
where the instance dropdown was in the right sidebar.
Text property
- Select a text layer nested in a main component or variant.
- (Optional) Variant only: Click to select similar layers in the component set. These layers are recognized by having the same hierarchy and name.
- Click in the content section of the right sidebar to create a property. This opens the create component property modal.
- Use the text field to type in a name for the property.
- Use the value text field to set a default string of text. If you set the default value to something other than the current string, Figma will update the text string to match this value. This also works the other way around: if you update the text string on the component, Figma will update the default value too.
- Click create property. When applied, you’ll see a purple pill with the
property name
in the content section of the right sidebar.
Boolean property
- Select a layer nested in a main component or variant.
- (Optional) Variant only: Click to select similar layers in the component set. These layers are recognized by having the same hierarchy and name.
- Click in the layers section of the right sidebar to create a property. This opens the create component properties modal.
- Use the Name text field to give the property a name.
- Set the default value to true or false.
- Click create property. When applied, you’ll see a purple pill with the
property name
next to the relevant property in the right sidebar.
Tip! Want to apply or create a different property? Click the purple pill from the relevant property in the right sidebar.
From the parent layer
Create a component property with the component set or main component selected. This method supports creating all property types, including variant properties.
This approach only creates the property, you’ll need to apply properties to any child layers as a separate step.
To create a component property from the parent layer:
- Select a main component or component set, and click in the Properties section of the right sidebar. A dropdown with component property options will appear.

- Select a property from the component.
- Variant property
- Instance swap property
- Text property
- Boolean property
- Use the fields and dropdowns from in the create component property modal to give your property name and default value.
Creating a component property using the top-down method does not apply them to any nested layers. Learn how to apply a component property ↓
Apply
Apply an existing component property to a nested layer at any time.
- Select a nested layer in a main component or variant.
- (Optional, variants only) Click to select similar layers in the component set.
- From the right sidebar, find the section for the property you want to apply. Click to open a dropdown. The dropdown contains relevant, existing properties.
If the create component property modal appears instead of the dropdown, then a property of that type doesn’t exist in that component. Learn how to create a component property ↑
- From the dropdown, click a property to apply it to the selected layer(s). A purple pill with an icon and property name will appear in the right sidebar.
Tip! To switch a nested layer’s component property, click the purple pill in the right sidebar to open a dropdown with other existing properties of the same type. Select a property to apply.
Attach documentation
Like regular components, you can attach descriptions and links to further documentation. This makes sure the people using your components have the right information and context to apply them.
- Select component set or main component.
- Click to open component details.

- Fill in one or both fields,
- How to use this component
- Link to documentation
- Click or anywhere outside the modal to apply changes.
Publish updates
Publish to the team library when you create or update component sets, main components, properties, or values. This allows you to share them with others or to use them in other files or projects. Learn how to publish to team library →
Manage
After creating component properties and their values, you can manage them at any time. Rename, reorder, delete, change default values, and more.
Manage properties
Rename
To rename a component property,
- Select component set or main component.
- From the Properties section in the right sidebar, double-click a property name.
- Type in a new name, then press return or click outside the field to apply.
Tip! Use the edit property modal to rename a component property by clicking in the right sidebar and typing a new name in the Name text field.
Reorder
To change the order of component properties:
- Select component set or main component.
- Hover over a property to reveal handles.
- Click and drag to reorder, then release to apply.
The order of component properties will also be reflected in the right sidebar when someone is using an instance of the component.
Note: Variant properties always sit above other property types in the right sidebar. They can be reordered amongst other variant properties, but cannot be reordered with other types.
Delete
To delete an existing component property,
- Select component set or main component.
- Right-click property and click Delete property, or select property and press delete.
Note: If your component set or main component only contains one variant property, deleting the property will delete the entire component set or main component.
Detach a property
Detach text, instance swap, or boolean properties from a layer.
- Select a nested layer with a component property applied.
- Click in right sidebar panel next to the property you wish to unlink.
This removes the component property from the layer, but the component property won’t be deleted.
Note: It’s not possible to detach a variant property from a nested layer.
Manage values
Change default value
Change the default value of a text, boolean, or instance swap property.
- Select component set or main component.
- Click next to the variant property to open the edit property modal.
- Use the text field or dropdown in the Value section to update the default value.
Updating the default value will reflect on canvas if the associated instance layer has no property overrides applied.
Rename
To rename a value of a variant property:
- Select component set or main component.
- Click next to the variant property to open the edit property modal.
- In the Values section, use the text fields to rename the values.
Reorder
To reorder values of a variant property:
- Select component set or main component.
- Click next to the variant property to open the edit property modal.
- Hover over a value to reveal handles.
- Click and drag to reorder.
Delete
To delete a value of a variant property
- Select component set or main component.
- Click next to the variant property to open the edit property modal.
- Click the handle of a value, and press delete / backspace.
Use
When using an instance containing component properties, you can use the controls in the Properties section of the right sidebar to configure the instance.
You can also check any descriptions or documentation to make sure you’re using the asset correctly.
Read documentation
Documentation is essential to ensure accurate and consistent use of a design system. Component documentation can include a description, a link to external documentation, or both.
If a description was included with a component, they appear in two places:
- In a tooltip when hovering over the component from the assets panel
- In the right sidebar when selecting the instance
If a link to external documentation with a component, it’ll appear as a button in the Inspect panel.
Configure properties
When you select an instance containing component properties, the Properties section in the right sidebar will populate with different property controls. Use the accompanying dropdowns, toggles, or text fields to make changes, and they will be reflected in the instance.
- Dropdowns with denote instances that you can swap.
- Update the text in text fields to directly change the string of text that appears on the canvas.
- Use the toggles to turn a setting on and off.
Reset changes to an instance at any time by clicking in the right sidebar and selecting Reset all changes.
Note: If you select a nested instance with an instance swap property applied, you won’t be able to swap the instance at this level. You will need to select the top-level component and use the property controls in the right sidebar. You can still, however, detach nested the instance.
Overrides
You can still make overrides to non-component properties of a single instance. Figma records the changes you make to an instance and preserves them, even when you swap between instances or select different variants.
Learn about overrides and override preservation →