Component Properties are configurable controls that define which parts of a Figma component can be changed when the component is used as an instance. They make components flexible, reusable, understandable, and easier to maintain inside a design system.
With component properties, designers can expose specific controls such as showing or hiding an icon, changing text, swapping a nested component, selecting a variant, or adding flexible content without requiring users to edit the internal layers of the component.
Learn professional Figma design concepts through JustAcademy Figma Training and explore the available learning options through the Register for Figma Course Demo.
Component Properties are configurable aspects of a main component or component set that tell users which parts of the component are intended to be customized. Instead of manually searching through layers and overriding individual elements, users can access consolidated controls in the Properties section of the right sidebar.
For example, a button component may contain an icon, label, and different states. A Boolean property can control whether the icon is visible, a Text property can control the label, and a Variant property can control the button state or size.
Component Properties = Controlled customization options for reusable components.
They allow a designer to create a component once and expose only the controls that other designers need when using its instances.
| Property Type | Main Purpose | Example |
|---|---|---|
| Boolean | Show or hide a layer | Show/hide button icon |
| Instance Swap | Replace a nested instance | Change an icon |
| Text | Change text content | Change button label |
| Variant | Define component variations | Size, state, color |
| Slot | Add and arrange flexible content | Modal content or list items |
Figma provides five component property types: Boolean, Instance Swap, Text, Variant, and Slot.
Main Component
|
|-- Define Property
|
|-- Set Default Value
|
|-- Apply Property to Layer
|
v
Component Instance
|
|-- Boolean
|-- Text
|-- Instance Swap
|-- Variant
|-- Slot
|
v
Controlled Customization
The main component defines the available controls. When a designer creates an instance, those controls appear in the Properties section of the right sidebar.
Component properties are normally created on a main component or component set. The component creator decides which parts of the component should be configurable.
This creates a clear separation between the component's fixed design rules and the parts that users are allowed or expected to customize.
When an instance containing component properties is selected, Figma displays the available property controls in the right sidebar. Users can change those controls without manually navigating through the internal structure of the component.
This creates a cleaner and more predictable editing experience.
A Boolean property uses a true/false value to control whether a layer is visible or hidden inside an instance.
For example, a button can contain an icon. Instead of creating separate components for a button with an icon and a button without an icon, a Boolean property can control the icon's visibility.
Button
├── Icon → Boolean Property: Show Icon
└── Label → Text Property
A true value shows the controlled layer and a false value hides it.
Suppose a button has the following structure:
Button
├── Icon
└── Text: "Continue"
Create a Boolean property named Show Icon.
Show Icon = True
→ Icon visible
Show Icon = False
→ Icon hidden
The same button component can now support both versions without creating unnecessary duplicate components.
Use names that clearly describe the purpose of the property.
Avoid unclear names such as Boolean 1, Option, or Toggle.
An Instance Swap property allows a nested component instance to be replaced with another component instance while keeping the overall component structure intact.
This is especially useful for icons, avatars, logos, trailing actions, badges, and other nested components.
List Item
├── Leading Icon
├── Label
└── Trailing Component
↓
Instance Swap Property
↓
Checkbox / Arrow / Menu / More
Instance Swap properties can define the nested instances that can be swapped and can also provide preferred instances to guide designers toward suitable choices.
Consider a navigation item containing an icon.
Navigation Item
├── Icon
└── Dashboard
Instead of creating separate components for Home, Dashboard, Settings, Profile, and Search, use an Instance Swap property for the icon.
Icon Property
→ Home
→ Dashboard
→ Settings
→ Profile
→ Search
Preferred instances are curated component choices that help users select appropriate alternatives when using an Instance Swap property.
For example, an icon button might have access to hundreds of icons, but the design system may recommend only eight icons for that particular component. Preferred instances can communicate those recommended choices.
This reduces guesswork and improves consistency.
A Text property defines which text content inside a component can be changed by users.
It is useful for buttons, headings, labels, card titles, descriptions, notifications, menu items, form labels, and other content-driven components.
Button
└── Text Layer
↓
Text Property: Label
↓
"Submit"
"Continue"
"Save"
"Download"
Text properties allow users to update text directly from the right sidebar or on the canvas.
Create a button with the default text Submit.
Create a Text property named Label.
Default:
Label = "Submit"
Instance 1:
Label = "Login"
Instance 2:
Label = "Register"
Instance 3:
Label = "Continue"
The same main component can therefore support multiple content variations.
Use names based on the content's purpose.
Always test text properties with short and long content.
Short:
"Save"
Medium:
"Save Changes"
Long:
"Save Changes and Continue"
When designing reusable components, combine Text properties with Auto Layout so the component can respond appropriately to changing content.
A Variant property is used to define and organize variations of components within a component set.
Variants are especially useful when the component has visually or structurally different states, sizes, colors, or interaction states.
Button Component Set
├── Size: Small
├── Size: Medium
├── Size: Large
├── State: Default
├── State: Hover
├── State: Pressed
└── State: Disabled
Variant properties are used to define attributes such as state, color, or size.
A button component set might contain:
| Property | Values |
|---|---|
| Size | Small, Medium, Large |
| State | Default, Hover, Pressed, Disabled |
| Style | Primary, Secondary, Destructive |
These properties define the visual and behavioral variations of the button.
Variants are generally better for visually or structurally distinct states and types, while Boolean, Text, Instance Swap, and Slot properties can expose content-level customization without multiplying the number of variants.
| Use Case | Recommended Approach |
|---|---|
| Show/hide icon | Boolean |
| Change label | Text |
| Replace icon | Instance Swap |
| Different button state | Variant |
| Different component size | Variant |
| Flexible content area | Slot |
A Slot property creates a flexible area inside a component where users can add, edit, and rearrange content while keeping the instance connected to the main component.
Slots are particularly useful for components that need flexible content such as cards, modals, lists, forms, and repeating content areas.
Card
├── Header
├── Slot
│ ├── Custom Content
│ ├── Image
│ └── Additional Information
└── Footer
Slots provide more freedom than an Instance Swap because users can add and arrange content within the defined flexible area.
Imagine a modal component with a fixed header and footer but flexible body content.
Modal
├── Header
├── Slot: Body Content
└── Footer
Different instances can use different content inside the slot while preserving the modal's overall design-system structure.
| Feature | Instance Swap | Slot |
|---|---|---|
| Purpose | Replace one nested instance | Add and arrange flexible content |
| Flexibility | More controlled | More flexible |
| Example | Swap one icon | Add multiple card elements |
| Design Guardrails | Strong | Flexible |
Instance swapping is useful when a component needs controlled alternatives, while slots are useful when users need more freeform content inside a defined area.
A professional button component can combine multiple property types.
Button
├── Leading Icon → Boolean: Show Leading Icon
├── Icon → Instance Swap: Leading Icon
├── Label → Text: Label
└── Component Set → Variant: Size / State / Style
This creates a powerful reusable button system without requiring separate components for every combination.
| Property | Type | Example Value |
|---|---|---|
| Show Icon | Boolean | True |
| Icon | Instance Swap | Arrow |
| Label | Text | Continue |
| Size | Variant | Medium |
| State | Variant | Default |
A card can also use multiple properties.
Product Card
├── Product Image
├── Title → Text Property
├── Description → Text Property
├── Favorite Icon → Boolean Property
├── Action Icon → Instance Swap Property
└── Card Type → Variant Property
A list item is an excellent example of combining Boolean, Instance Swap, and Text properties.
List Item
├── Avatar → Boolean
├── Label → Text
├── Metadata → Text
├── Leading Component → Instance Swap
└── Trailing Component → Instance Swap
This structure allows optional elements, replaceable nested components, and editable text to be managed through component properties.
| Question | Property |
|---|---|
| Should an element appear or disappear? | Boolean |
| Should text change? | Text |
| Should a nested component be replaced? | Instance Swap |
| Should the component have different states or types? | Variant |
| Should users add and rearrange flexible content? | Slot |
| Bad Name | Better Name |
|---|---|
| Boolean 1 | Show Icon |
| Text 1 | Label |
| Swap 1 | Leading Icon |
| Option | Show Badge |
| Type | Button Style |
Component properties can have default values. Default values define how the component behaves when it is first created or when no override has been applied.
For example:
Show Icon = True
Label = "Submit"
Icon = Arrow
Size = Medium
State = Default
Choosing sensible defaults makes the component easier to use and helps maintain predictable behavior.
Component properties provide intentional, named controls for customization. Traditional instance overrides can still exist for other supported instance customizations.
Using component properties gives users a more organized and discoverable way to customize reusable components.
| Component Properties | Manual Overrides |
|---|---|
| Explicitly designed as controls | Individual instance changes |
| Easy to discover | May require layer navigation |
| Good for design systems | Useful for individual customization |
| Consistent interface | Can become difficult to manage |
Component properties work especially well with Auto Layout. When text changes, icons appear or disappear, or content is swapped, Auto Layout can help the component adjust its dimensions and spacing.
Button
┌──────────────────────────┐
│ [Icon] Continue │
└──────────────────────────┘
↓
Show Icon = False
↓
┌───────────────────┐
│ Continue │
└───────────────────┘
Combine component properties with Auto Layout and responsive sizing rules to create components that adapt to different content and screen sizes.
For example, a button with a Text property can automatically grow when the label changes from Save to Save Changes and Continue.
Component properties can be applied to nested layers inside a main component or variant. This allows a complex component to expose selected controls without exposing every internal design decision.
Main Component
├── Header
│ └── Icon → Instance Swap
├── Content
│ └── Text → Text Property
└── Footer
└── Button → Nested Component
A good component does not expose every possible customization. It exposes the controls that users actually need.
For example, a button may expose:
It may intentionally keep internal padding, border radius, typography rules, and layout structure controlled by the design system.
Without component properties, designers may create a large number of variants to represent every possible combination.
Without Properties:
Button with Icon + Small + Primary
Button with Icon + Medium + Primary
Button without Icon + Small + Primary
Button without Icon + Medium + Primary
...
Using a Boolean property for icon visibility can eliminate many unnecessary combinations.
Button
├── Size: Small / Medium / Large
├── State: Default / Hover / Disabled
├── Show Icon: True / False
├── Icon: Arrow / Plus / Check
└── Label: Editable Text
This provides controlled flexibility without requiring every combination to become a separate variant.
Component properties are an important part of scalable design systems because they define how reusable assets can be customized.
A design system can use properties to establish clear rules for components while still allowing designers to adapt them to specific content and contexts.
Design System
│
├── Buttons
│ ├── Size
│ ├── State
│ ├── Label
│ └── Icon
│
├── Cards
│ ├── Title
│ ├── Description
│ ├── Image
│ └── Action
│
└── List Items
├── Avatar
├── Label
├── Metadata
└── Trailing Action
Component properties become particularly useful when components are distributed through shared libraries. Designers can insert component instances and use the available properties without modifying the main component.
When updated components need to be used across files, the updated assets should be published to the team library according to the applicable library workflow.
Good component documentation should explain what each property does and when it should be used.
Button
Label:
Text shown inside the button.
Show Icon:
Controls whether the leading icon is visible.
Icon:
Selects the preferred icon.
Size:
Controls the button size.
State:
Controls the interaction state.
Clear documentation helps designers understand how and when to customize each property.
Create a professional button component with the following properties:
Test the button using multiple instances with different property combinations.
Create a profile card with:
Create an e-commerce product card.
Product Card
├── Image
├── Product Name → Text
├── Price → Text
├── Favorite → Boolean
├── Action Icon → Instance Swap
└── Card Type → Variant
Create a notification component using:
Possible types can include Success, Warning, Error, and Information.
Create a modal component with a Slot for flexible content.
Modal
├── Title → Text Property
├── Close Icon → Boolean / Instance Swap
├── Content → Slot
└── Footer Actions → Slot or Nested Components
Create a reusable list item with optional and replaceable elements.
List Item
├── Avatar → Boolean
├── Leading Icon → Instance Swap
├── Label → Text
├── Metadata → Text
└── Trailing Action → Instance Swap
One of the most common mistakes is creating a separate variant for every content difference.
For example, creating separate variants for Button Label = Save, Delete, Continue, and Submit is usually unnecessary. A Text property is more appropriate when only the text changes.
Boolean properties are useful for optional elements, but excessive Boolean properties can make a component confusing.
Use Boolean properties when the visibility change represents a meaningful and intentional configuration option.
Unclear property names make components difficult to use.
Bad:
Option 1
Setting
Toggle
Better:
Show Avatar
Show Badge
Show Description
Text properties should be tested with realistic content. A component that works with a five-character label may break when used with a long sentence.
Use Auto Layout, appropriate constraints, and responsive sizing to handle content changes.
Creating separate components for every small difference makes the design system difficult to maintain.
Before creating a new component, determine whether the difference can be represented using a Boolean, Text, Instance Swap, Variant, or Slot property.
Component properties should guide users, not expose every internal layer. Too many controls can make a component overwhelming and reduce consistency.
If users need to replace one controlled nested component, Instance Swap may be appropriate. If they need to add and rearrange flexible content, a Slot is generally more suitable.
Instance Swap provides stronger guardrails, while Slot provides greater flexibility for content.
After creating component properties, test every property through real component instances.
Test:
Show Icon = True
→ Icon visible
Show Icon = False
→ Icon hidden
Expected Result:
Component layout remains correct in both states.
Test Values:
"Save"
"Save Changes"
"Continue"
"Continue to Checkout"
Expected Result:
Text changes correctly and component resizes appropriately.
Test:
Icon = Search
Swap → Home
Swap → Settings
Swap → User
Expected Result:
Only the intended nested component changes.
Test:
Size = Small
Size = Medium
Size = Large
State = Default
State = Hover
State = Disabled
Expected Result:
Correct variant appears without breaking the component.
Component properties should support accessible design rather than make it harder. Text properties should allow meaningful content, while Boolean properties should not accidentally hide important information or actions.
Designers should test components with realistic labels, sufficient contrast, meaningful states, and appropriate content hierarchy.
Be careful when consolidating visually different states using Boolean properties if separate interactive objects are required for prototyping. Changes to component structure can affect prototype connections, so interactive components should be tested after property changes.
Component properties and variables can work together in advanced design systems. For example, variables can be associated with variant properties so component variants can change based on variable values or modes.
This combination can help create scalable systems for themes, responsive designs, states, and other design-system requirements.
Design System
│
├── Variables
│ ├── Colors
│ ├── Spacing
│ ├── Typography
│ └── Modes
│
├── Components
│ ├── Boolean Properties
│ ├── Text Properties
│ ├── Instance Swap Properties
│ ├── Variant Properties
│ └── Slot Properties
│
└── Instances
└── Controlled Customization
A well-designed component property system reduces repeated manual editing and makes the design system easier to maintain. When the main component changes, instances can continue to follow the component's structure while users retain the intended configurable controls.
Component properties provide controlled freedom. Designers can customize content while important design rules remain centralized in the main component.
Central Design Rules
↓
Main Component
↓
Component Properties
↓
Controlled Instances
↓
Consistent Product UI
| Requirement | Better Approach |
|---|---|
| Only text changes | Text Property |
| Optional icon | Boolean Property |
| One nested component changes | Instance Swap |
| Visual state changes | Variant |
| Flexible content changes | Slot |
| Completely different structure | Separate Component |
Add to Cart Button
│
├── Label → Text Property
│
├── Cart Icon → Boolean Property
│
├── Icon → Instance Swap Property
│
├── Size → Variant Property
│
└── State → Variant Property
This single component can support many product pages without requiring dozens of manually designed buttons.
Dashboard Card
│
├── Title → Text
├── Value → Text
├── Supporting Text → Text
├── Icon → Instance Swap
├── Trend Indicator → Boolean
└── Card Type → Variant
Navigation Item
│
├── Icon → Instance Swap
├── Label → Text
├── Badge → Boolean
└── State → Variant
Notification
│
├── Type → Variant
├── Icon → Instance Swap
├── Title → Text
├── Message → Text
└── Close Button → Boolean
Use component properties to define intentional customization points. Use variants for meaningful visual or structural differences. Use Auto Layout for responsive behavior, nested components for composition, and slots when flexible content needs to remain inside the component.
| Property | Controls | Best Use |
|---|---|---|
| Boolean | Visibility | Optional elements |
| Text | Content | Labels and messages |
| Instance Swap | Nested component | Icons and replaceable components |
| Variant | Component variation | States, sizes, styles |
| Slot | Flexible content | Lists, cards, modals |
Component Properties are configurable controls that define which aspects of a component can be customized when using its instances.
The five current types are Boolean, Instance Swap, Text, Variant, and Slot properties.
A Boolean property uses true/false values to control layer visibility.
It allows a nested component instance to be replaced with another component instance.
It allows specific text content inside a component to be changed from the component's controls.
It defines attributes and variations within a component set, such as state, size, or color.
A Slot creates a flexible area where content can be added, edited, and rearranged while keeping the component connected.
Component properties can handle content-level customization without multiplying variants for every possible content combination.
Instance Swap provides controlled replacement of a nested instance, while Slot provides a more flexible area for adding and arranging content.
Yes. They are especially useful for creating reusable, scalable, and controlled design-system components.
Create a button with Label, Show Icon, Icon, Size, and State properties. Create at least five instances and customize each one.
Create a product card with editable title and price, optional favorite icon, replaceable action icon, and multiple card styles.
Create a modal with a Text property for the title and a Slot for flexible body content. Add reusable action buttons inside the footer.
Create a list item containing an optional avatar, editable label, editable metadata, swappable leading icon, and swappable trailing action.
Component Properties
│
├── Boolean
│ └── Show / Hide
│
├── Text
│ └── Change Content
│
├── Instance Swap
│ └── Replace Nested Component
│
├── Variant
│ └── State / Size / Style
│
└── Slot
└── Flexible Content
Identify Component Requirements
↓
Create Main Component
↓
Build Structure with Auto Layout
↓
Identify Customizable Areas
↓
Choose Property Type
↓
Create Property
↓
Apply Property
↓
Set Default Value
↓
Create Component Instance
↓
Test Property Controls
↓
Test Responsive Behavior
↓
Document Component
↓
Publish / Share Through Library
↓
Use Across Designs
Component Properties are one of the most important features for building flexible and scalable components in Figma. They allow designers to define exactly which parts of a component can change while keeping the underlying design system consistent.
Boolean properties are ideal for visibility controls, Text properties are useful for editable content, Instance Swap properties provide controlled replacement of nested components, Variant properties manage meaningful component variations, and Slot properties provide flexible content areas.
When combined with Auto Layout, variants, variables, nested components, documentation, and libraries, Component Properties help create professional design systems that are easier to reuse, maintain, and scale.
For structured Figma learning, visit JustAcademy Figma Training and explore the Register for Figma Course Demo.
