Before you Start
Who can use this feature
Anyone with edit access to the Figma design file can create, manage, and use component props
Component properties are the changeable aspects of a component. You can define which parts of a component others can change by tying them to specific design properties. This allows you to control things like:
- Layers you can hide or show
- Whether an instance can be swapped
- Which text strings can be changed
These definitions are consolidated into a single set of controls in the right sidebar. Anyone editing the instance can use these controls to understand what is changeable and to make edits.
This removes the need to select and override individual layers, reduces time needed to refer to documentation, and improves accurate usage of components and design systems.
Component properties also helps reduce the size of your design system or library file through the use of boolean properties. Learn more ↓
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.
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:
Boolean property
Note: Boolean properties are currently only available for layer visibility.
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.
Warning: Before applying boolean properties to components, it’s important to consider any need for interactive components or prototyping connections. Prototyping noodles must connect between two objects. If you connect two components and consolidate them using boolean properties, the prototyping connections will be lost.
For example, you have a boolean property applied to an icon in a button component to represent two states: a button with an icon and one without. It’s not possible to set up an interaction between the two because you’re using a single component. Prototype interactions must be between two individual objects.
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.
Note: Text component properties currently don't support rich text — such as lists styles, superscript, and other type settings. You can still apply these settings to the text layer, but their formats won't be reflected in the component properties panel of the right sidebar.
If the text layer contains a bulleted or numbered list style, changing the text string from the right sidebar will remove the list style. To preserve it, update the string from the canvas instead.
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.
Note: 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.
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.
Note: If you have an exposed nested instance with visibility set to hidden on a boolean property, any component properties attached to the instance will be hidden as well.
Choose nested instances to expose
With a main component or component set selected, click in the Properties section of right sidebar and choose Nested instances under Expose properties from.
Note: The option to expose nested instances is available only if a main component:
- already has an exposed nested instance, or
- contains nested instances with component properties applied to it
If you don’t see the Nested instances option, try applying a component property to a nested component first.
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 .
Preferred values
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.
Note: If you don’t want to use a preferred value, click the dropdown or use the search bar above the list to find other components from available.
Add and remove
- To add preferred values for an instance, start by editing its existing instance swap property or creating a new one. 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.
- Remove a preferred value anytime by clicking next to the value in the Preferred values section of the modal.
Simplified 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.
Note: Simplified instances will hide certain layer names, but anyone with can edit permissions to the file can still edit the layers.
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.
