Before you Start

Who can use this feature

Users on any plan

Anyone with edit access to the Figma Design file can create, manage, and use component props

This article covers how to create and configure component properties. Learn how to edit instances with component properties.

Component properties are the changeable aspects of a component. They allow you to communicate which parts of a component can be changed, such as:

• Which layers in a component have the option to be hidden or shown
• Whether an instance can be swapped and set preferred instances to swap to
• Which text strings can be changed

Anyone using a component with component properties can view a single set of consolidated controls in the right sidebar, so they can understand at a glance what is changeable and make edits in one place.

This removes reduces time needed to refer to documentation, improves accurate usage of components and design systems, and decreases the need to select and override individual layers.

Component properties also helps reduce the size of your design system or library file through the use of boolean properties.

Types of component properties

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:

• Boolean properties
• Instance swap properties
• Text properties
• Variant properties

Boolean property

Use boolean properties to set true/false values. This allows users to toggle an attribute 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.

This is also a great way to reduce the size of design systems and file libraries.

If a boolean property is created for layer visibility and value is set to false, any associated component property will be hidden. Once you toggle it to true, the associated property will appear.

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.

Set preferred instances so others know which instances to swap to ↓

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 applied can still be updated.

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.

Create and apply a component property

Component properties are created and applied to main components and component sets to define parts of a design system and to make design systems easier to use.

Component properties can be created from two levels: the parent layer or the child layer of a main component or component set. Learn about the relationship between parent and child layers.

You can create instance swap, text, and boolean properties from the child layer, and they’ll be applied to the child layer(s) without extra steps.

You can create any component property from the parent layer, however you’ll need to take the extra step to apply it to child layers. Variant properties can only be created from the parent layer.

Property	Child layer	Parent layer
Boolean	✓	✓
Text	✓	✓
Instance Swap	✓	✓
Variant	✕	✓

Create from a child layer

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.

1. Select a layer nested in a main component or variant.
2. (Optional, variants only) Click to enable multi-edit to edit matching objects and speed up your workflow. Learn how to multi-edit variants.
3. In the right sidebar, find the section corresponding to the component property you wish to create and click .
   • Instance swap property: Next to the swap instance dropdown in the right sidebar.
   • Text property: In the Content section in the right sidebar.
   • Boolean property: In the Layer section in the right sidebar.
4. If a dropdown menu appears, click Create property.
5. From the Create component property modal, use the fields and dropdown menus to configure the property.
   • Instance swap:
     • Give your property a name using the text field
     • Set the default value by using dropdown to select an instance from local components in the file or any enabled libraries.
     • If any, set up any preferred instances so others know which instances they can swap to when using the component.
   • Text:
     • Give your property a name using the text field
     • Set the default string of text by using the value text field. 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 main component, Figma will update the default value too.
   • Boolean property:
     • Give your property a name in the text field
     • Set the default value to true or false.
6. Click create property. When applied, you’ll see a purple pill with the property name in the property’s corresponding section in the right sidebar.

Create from a parent layer

This method supports creating all property types, including variant properties.

Adding component properties from the parent layer is a two step process:

1. Create the component property from the parent layer.
2. Manually apply it to the desired layers.

To create a component property from the parent layer:

1. 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.
2. Select a property from the component.
   • Variant property
   • Boolean property
   • Instance swap property
   • Text property
3. Use the fields and dropdowns from in the create component property modal to give your property name and default value.
4. Click Create property.
5. Lastly, apply the property to any nested layer.

Apply an existing property

To apply an existing component property to a nested layer:

1. Select one or more nested layers in a main component, component set, or variant.
2. (Optional, variants only) Click to enable multi-edit to edit matching objects and speed up your workflow. Learn how to multi-edit variants.

3. From the right sidebar, find the section for the property you want to apply.

4. Click to open a dropdown. The dropdown contains existing properties for the type in that corresponding section.

   • Instance swap: Instance swap section
   • Text: Content section
   • Boolean: Layers section

   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.

5. 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.

Customize a component property

Change the default value

Change the default value of a text, boolean, or instance swap property.

1. Select component set or main component.
2. Click next to the variant property to open the edit property modal.
3. 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.

Choose preferred values (instance swap property only)

Preferred values allow you to create a curated set of components to choose from when swapping instances (via the instance swap property). They reduce guesswork by communicating which specific components can replace an existing one.

For example, you create an icon button with an instance swap property to indicate that the icon can be swapped. However, your icon library contains over 100 icons, but only 8 of them should be used for this button.

To make it easy find these 8 icons and to know which one can be used, you add them as preferred values. Now, whenever designers go to swap the icon, they have a curated list of assets they know they can use.

When using a component with a preferred value, a list of preferred values appear by default when opening the instance swap property menu.

To add preferred values for an instance:

1. Start by editing its existing instance swap property or creating a new one.
2. From the respective modals, click in the Preferred values section and check the checkboxes next to the instances you want to include as a preferred values.

To remove a preferred value, click next to the value in the Preferred values section of the modal.

Expose nested instances

Expose specific nested instances to reveal their component properties alongside those of the top-level instance. This helps design system users discover nested instances and their component properties without deep-selecting layers to find them.

For example, you create a social media card component with multiple components nested inside — an avatar, name, buttons, and so on. You want to change the icon of the default button to a “send” icon, and change its text. You also want to change the cancel button state to a disabled state.

Instead of deep-selecting into each layer to find their component property controls, exposing nested instances allows you to click just the top-level component — in this case, the social media card — and edit your instance from a single place.

When you select a top-level instance with exposed nested instances, a list of component properties for the top-level and nested instances will appear in the right sidebar.

When hovering over a property row, a light purple highlight appears around the corresponding object on canvas so you know what you’re editing.

With a main component or component set selected, click in the Properties section of right sidebar and choose Nested instances under Expose properties from.

From the Expose nested instances modal, check the boxes for instances you want to reveal at the top-level.

A list of chosen nested instances will appear in the right sidebar.

To remove nested instances from being exposed, hover over the instance name on this list and click .

Simplify instances

Simplifying an instance helps reduce clutter in the layers and properties panel by hiding layers without component properties applied. Figma assumes that a layer with no component property is a layer that should not be edited, and therefore can be hidden.

To simplify an instance, select a main component or component set, and click in the right sidebar. From the pop-up, check the simplify all instances checkbox.

When using an instance of a simplified component, excess layers will be collapsed under See all layers. Click See all layers to expand and see the layers. You can collapse it again by clicking outside the layers panel or selecting a different layer.

Manage properties

After creating component properties and their values, you can manage them at any time. Rename, reorder, delete, change default values, and more.

Detach a property

Detach text, instance swap, or boolean properties from a layer.

1. Select a nested layer with a component property applied.
2. 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.

Rename, reorder, or delete

Properties

To rename, reorder, or delete an existing component property:

1. Select the main component or component set.
2. From the Properties section in the right sidebar:

   • Rename: Double-click a property name. Type in a new name, then press return / enter or click outside the field to apply.

   • Reorder: Hover over a property to reveal handles. Click and drag to reorder, then release to apply.

     Variant properties always sit above other property types in the right sidebar. They can be reordered with other variant properties, but not with other property types.

   • Delete: Right-click a property and click Delete property. Or, select a property and press delete.

     If your component set or main component only contains one variant property, deleting the property will delete the entire component set or main component.

Values

To change or reorder values of a variant property:

1. Select component set or main component.
2. Click next to the variant property to open the edit property modal.
   • Change: In the Values section, use the text fields to change or update the values.
   • Reorder: Hover over a value to reveal handles. Click and drag to reorder.

Component playground in Dev Mode

When selecting a component or instance in Dev Mode, you’ll see a component preview, a link to the main component, as well as any links to relevant documentation and dev resources.

The component playground appears in the inspect panel when a component instance is selected. Use the playground to experiment with the component’s different properties without changing the actual design. To open the component playground in Dev Mode:

1. Select a component instance on the canvas.
2. Click Open in playground in the Inspect panel.

Learn more about using Dev Mode to inspect designs →