Explore component properties

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

Already familiar with component properties? Learn how to create and add them to components or how to edit instances with component properties.

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 ↓

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

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.

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.

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.

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.

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.

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