Related Videos

• Edit instances with component properties

  🚧 A few new component property features have landed in open beta. Learn what they are and how to try them out →

  Before you Start

  Who can use this feature

  Users on any plan

  Anyone with edit access to the Figma design file can create and manage component properties

  New to component properties? Learn how component properties works by exploring the different types, preferred values, exposed nested instances, and more.

  Component properties are the changeable aspects of a component, so you know which parts of a component — like icons or text — can change.

  When editing an instance containing component properties, the their component properties controls appear in a single section of controls in the right sidebar. This makes it easy to know what is changeable and to make those changes in one place.

  

  This also removes the need to select and override individual layers, reduces time needed to refer to documentation, and removes the guesswork out of design systems!

  When editing an instance, you can check any available descriptions or documentation to ensure accurate use of the asset. Component documentation can include a description, a link to external documentation, or both. Learn how to view documentation →

  Configure properties

  When you select an instance containing component properties, the Properties section of the right sidebar will populate with different component property controls. Use the accompanying dropdowns, toggles, or text fields to make changes, and they will be reflected in the instance.

  • Boolean property: Allows you to set true/false values to turn a specific property on or off. Currently only available for layer visibility. Use the toggles to turn a setting on and off.
  • Instance swap property: Indicates which instances can be swapped. Dropdowns with a  denote instances that you can swap.
  • Text property: Indicates which text strings can be edited. Update the text in text fields to directly change the string of text that appears on the canvas.
  • Variant property: Allows you to define specific values and attributes to your variants, such as state, color, or size. Dropdowns with no icon denote variant states that you can change.

  Learn more about the different component property types →

  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 →

  Tip! Component properties are supported in Figma's plugin API. Learn more from Figma's plugin developer docs →

• Create and manage component properties

  🚧 A few new component property features have landed in open beta. Learn what they are and how to try them out →

  Before you Start

  Who can use this feature

  Users on any plan

  Anyone with edit access to the Figma design file can create and manage component properties

  New to component properties? Learn how component properties works by exploring the different types, preferred values, exposed nested instances, and more.

  Create

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

  Tip! Add descriptions and links to documentation to components to better communicate a component’s intended use. Documentation provides the right information to those using or implementing your design system to guide proper application, variant and state usage, and accessibility and contrast requirements. Learn how to add documentation to components and styles →

  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.

  1. Select an instance nested in a main component or variant.
  2. (Optional, variants only) Click to select similar layers in the component set. These layers are recognized by having the same hierarchy and name.
  3. Click in the section corresponding to the component property you wish to create. If a dropdown menu appears, click Create property…
     • Instance swap: Next to the swap instance dropdown in the right sidebar.
     • Text: In the Content section in the right sidebar
     • Boolean: In the Layer section in the right sidebar
  4. 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 your preferred values so others know which values they should choose from when using the component. Learn more →
     • 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.
  5. 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.

  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

  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. Apply the property to nested layers. Creating a component property using this method does not apply them to any nested layers. Learn how ↓

  Manage

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

  Note: To use new or updated components across different files, be sure to publish them to the team library. This allows you to share them with others or to use them in other files or projects. Learn how to publish to team library →

  Apply an existing property

  Apply an existing component property to a nested layer at any time.

  1. Select a nested layer in a main component or variant.
  2. (Optional, variants only) Click to select similar layers in the component set.

  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.

  Tip! To change a nested layer’s component property to an existing one of the same type, click the purple pill in the right sidebar. From the dropdown, click a property to apply.

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

  Note: The default value of a variant property is determined by the variant in the top left corner of a component set. Learn how to change a component set’s default variant →

  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.

  Note: It’s not possible to detach a variant property from a nested layer.

  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.
• Explore component properties

  🚧 A few new component property features have landed in open beta. Learn what they are and how to try them out →

  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.

  
  Explore the component properties playground file in the Figma Community →

   

  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 properties ↓
  • Instance swap properties ↓
  • Text properties ↓
  • Variant properties ↓

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

  🚧 Exposed nested instances is currently in beta. Learn how to access this feature →

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

  🚧 Preferred values is currently in beta. Learn how to access this feature →

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

  🚧 Simplified instances is currently in beta. Learn how to access this feature →

  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.

  Alt: Simplify instances to reduce clutter in the layer (and properties?) panel by hiding names of layers without component properties applied.

  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.

• Guide to components in Figma

  Before you start

  Who can use this feature

  Users on any plan

  Users with can edit access to a file can create and edit components.

  Users with can view access to the original file can use components from that Library.

  Video tutorials

  Check out these video tutorials about components:

  Overview

  Components are elements you can reuse across your designs. They help to create and manage consistent designs across projects.

  You can create components from any layers or objects you've designed. These could be a whole range of things like buttons, icons, layouts, and more.

  There are two aspects to a component:

  1. A main component defines the properties of the component.
  2. An instance is a copy of the component you can reuse in your designs. Instances are linked to the main component and receive any updates made to the component.

  You can create components to use within a single file. Or, you can use team library to share components and styles across files and projects.

  Related articles

  Read these articles to learn more detailed and specific information about components.

  1. Create a component
  2. Create and use variants
  3. Create and use component properties
  4. Name and organize components
  5. Create an instance of a component
  6. Swap between component instances in a file
  7. Override properties of an instance
  8. Reset instances to remove overrides
  9. Detach instances from components
  10. Make changes to components and instances
• Name and organize components

  Before you start

  Who can use this feature

  Users on any plan

  Users with Edit access to a file can rename layers, including Components.

  New to Components? Check out our Getting Started with Components and Getting Started with Team Library articles.

  We recommend defining and documenting a component structure within your team or company.

  This will make it easier to find components in the Assets panel. As well as swapping related component instances.

  There are many different ways to structure your components. We'll show you how we structure components for the Assets panel and related components.

  Tip! Not sure where to start with building a Component Library? Our Best practices: components, styles, and shared libraries article has some great tips.

  Assets Panel

  The fastest way to access components in a file is via the Assets panel.

  To open the Assets panel:

  • Click on the Assets tab in the left sidebar.
  • Or, use the Keyboard Shortcuts:
    • Mac: ⌥ Option - 2
    • Windows:: Alt + 2

  Structure

  In the Assets panel, you will have access to the following components:

  • Local Components: Components you created in this file.
    • Private to this file: Components you created in this file, but didn't publish to the Team Library.
  • Used in this file: Components from other Libraries that you have already used in this file.
  • Enabled Libraries: Any default Libraries that anyone has enabled in a Team or Organization.

  There will be a heading for each of these sections in the Assets panel. We will list all enabled libraries, with their file name as the heading. You can collapse the headings to reduce the space they take up. Or expand them to explore the components within those files.

  

  Explore library file

  We display components in a path that mirrors the file's structure. The file path will follow this general structure: file > page > frame

  Each step in the path will represent a heading in the Assets panel. You can use the arrows to expand the file path and explore the components within each frame.

  We display pages in alphabetical order, not the order they are in the original file.

  

  Tip! If you use a slash-separated naming convention, we will group those components together in the Instance menu. e.g. file / page / frame /**name**/

  Related components

  You can view the selected Component in Instance section in the Design tab.

  You can use this to switch between related components, without leaving the file.

  We determine related components by:

  • How you have named the Component. e.g. We will display UI/Button/Active, UI/Button/Hover and UI/Button/Inactive together.
  • How you have arranged the Component in the origin file. e.g. We treat all Components within the same frame as Related Components.

  

  Examples

  Name Components

  If you want to add another layer of Organization, you can name your components in a particular way. We recommend you use the slash separated convention e.g. Component/State.

  Let's say you have named the components in a frame like this:

  • Login/Active
  • Login/Hover
  • Login/Inactive
  • Create/Active
  • Create/Hover
  • Create/Inactive

  Learn how to rename layers in bulk →

  Organize components

  In this example, we've structured our components based on their location. We've used pages and frames to organize our components into groups.

  • In our Figma UI file, we have the components that make up the Figma UI.
  • We have created a page for the Left Sidebar. The page will house all our components related to that sidebar.
  • The left sidebar consists of two main panels: the Layers panel and the Assets panel. We've created a frame for each of these panels.
  • We support two sizes for each icon: 16px and 32px. We add both sets of icons to each respective frame.
  • To make it easier to differentiate between the icon sizes, we name the components. In the Layers panel we use the slash convention to name each Component e.g. 16 / Team Library or 32 / Team Library.

  

  We've created a dialog window - in another file - that needs a close icon. We've already created one of these for the Assets panel, so we can use that one again.

  We need the 32px version of that Component. To find it in the Assets Panel we go to: Figma UI / Left Sidebar / Assets Panel / 32

  We can then drag that Component from the Assets Panel into the file.

  

  Note: For this approach, you will need to have the library enabled in the Assets panel. Learn more about enabling default libraries.

• Create components to reuse in designs

  Before you start

  Who can use this feature

  Users on any plan can create Components. Users on a Starter team can't publish Components to a Library.

  Users with can edit access to a file can create and edit components.

  Users with can view access to a file can use components from a library, if they have access to it.

  You can create a component out of any collection of objects or layers. components can be as simple as shapes, buttons or fields, or more complex design like cards and menus.

  Tip! As you create components and build out your design system, you'll find the need for components that are similar to each other, with only slight differences.

  Variants allow you to group and organize similar components into a single container. This simplifies your component library and makes it easier for everyone to find what they need.

  Learn how to create and use variants →

  Create a component

  You can create a single component out of selection of layers. Or, create individual components in bulk from a selection of objects.

  Create a single component

  There are a few ways to create a component. First, you'll need to select the layers you'd like to include in the component. 

  1. Select the layers you’d like to be included in the component.
  2. You then have a few different methods for create a component:
     • Click Create component in the toolbar.
     • Right-click on your selection and choose Create component.
     • Use the keyboard shortcuts:
       • Mac: ⌥ Option - ⌘ Command - K
       • Windows: Ctrl + Alt + K
  3. Figma will nest the layers within a special component frame. Identify components in the Layers panel using the purple icon.
  4. In the right sidebar, add a Description and Documentation link for collaborators. Collaborators and developers can view this information in the Inspect panel.

  Tip! Figma will create a custom button if you add a link from any of the following domains:

  • Github
  • Notion
  • Storybook
  • Zeroheight
  • Confluence
  • Dropbox Paper

  Create components in bulk

  By default, the Create component action will create a single component from your selection.

  You can also create components in bulk. This allows you to select multiple groups or frames and create components out of them. Create multiple components from:

  • Objects and layers in frames
  • Objects and layers in groups
  • Single layers, like a path or vector network
  • Layers in a boolean operation

  Note: If you select more than one layer that isn't on one of the above configurations, Figma will create a component for each individual layer.

  1. Select the layers you want to create components from,
  2. Click the next to Create component in the toolbar.
  3. Select Create Multiple components from the options.
  4. Figma will create a component for each frame, group, boolean operation, or path.

  

  Delete a component

  You can delete a component at any time.

  Deleting a main component does not remove instances of that component from your files.

  1. Select the component you want to delete.
  2. Press delete.

  Restore a component

  If you have an existing instance of a deleted component, you can use that instance to restore the component.

  Learn more about instances →

  There are a few ways to restore a component from an instance:

  From the right sidebar

  1. Select an existing instance of the deleted component.
  2. Do one of the following to restore the component:
     • If you are in the library file that contained the main component, click the Restore Component button from the properties panel in the right sidebar.
     • If you are in a file that did not contain the main component, click the Go to main component in library icon. Then click the Restore button in the dialog window.

  From the right-click menu

  1. Right-click on the instance in the canvas.
  2. Do one of the following to restore the component:
     • If you are in the library file that contained the main component, hover over the Main component option and click Restore main component.
     • If you are in a file that did not contain the main component, click Go to main component. Then click the Restore button in the dialog window.
• Create and insert component instances

  Who can use this feature

  Supported on any team or plan.

  Anyone with can view access to the file can use components from that library.

  New to components? Guide to style and component libraries →

  Components are UI elements that you can reuse across your designs.

  • The main component defines the properties of the element.
  • The instance is a copy of the component you can reuse in your designs.

  

  Create instances

  There are a few ways to create instances. Which method you can use depends on whether the components are published or local to the file.

  Method	Local components	Published components
  Assets panel	✓	✓
  Quick insert	✓	✓
  Copy/paste or duplicate	✓	✕

  Assets panel

  The Assets panel in the left sidebar allows you to search for components to add to your file. You can choose which libraries are available in the Assets panel.

  • Manage libraries for your drafts
  • Manage libraries in design files
  • Manage libraries in teams
  • Manage default organization libraries

  To open the Assets panel:

  1. Select the Assets tab in the left sidebar, or use the shortcut:
     • Mac: ⌥ Option 2
     • Windows: Alt + 2
  2. Find the component you want to use:
     • View Local components created in the current file.
     • Explore components from enabled libraries. Open the Library modal to manage available libraries.
     • View private local components and any components Used in the file.
     • Use the and to switch between grid and list view.
     • Use the search field to find components from any library you have access to. This includes team or organization libraries and files you have at least can view access to
  3. Click and drag the component into the canvas to create an instance of that component.

  

  Quick insert

  Insert instances of components from your keyboard using quick insert. Quick insert opens the Resources modal where you can find and view components from enabled libraries.

  The components found in the Resources modal mirror what you see in the Assets panel. Explore components from libraries you have access to, including:

  • Recently used components across all of your files
  • Local components in the current file, organized by page
  • All components in an enabled library

  

  1. Use the shortcut Shift I to open quick insert. 
  2. To locate a component, do one of the following: 
     • Use the search bar to find a specific component or use the arrow keys to navigate to the relevant component.
     • Use the and icons to switch between grid and list view.
     • Select from recent components used across your files, or select from an enabled library. If a library is not displaying, you may need to enable the library first. Manage libraries in design files →
  3. To swap: Select or hover over the instance, then hold down ⌥ Option (Mac) or Ctrl (Windows). Swap components and instances →

  Copy or duplicate

  If you're working in the same file, you can copy a component to create an instance. There are a few ways to copy objects in Figma.

  • A

    Duplicate using the keyboard shortcut

    • Mac: ⌘ Command D
    • Windows: Ctrl + D
  • B

    Drag to copy

    Hold down ⌥ Option (Mac) or Alt (Windows) and drag to create an instance.

    Release the click before you release the modifier key. Otherwise, Figma will move the original component instead of duplicate it.

  • C

    Copy and paste

    Copy the component and paste it as an Instance using the keyboard shortcuts:

    • Mac: ⌘ Command - C and ⌘ Command - V
    • Windows: Ctrl + C and Ctrl + V
• Create and use variants

  Before you start

  Who can use this feature

  Variants are supported on any team or plan. Publishing component sets to a library is only supported Professional and Education teams, or Figma Organizations.

  Anyone with Can edit access to a file can create variants and component sets in that file.

  Anyone with Can view access to a file can use components or components sets from that library.

  As you create components and build out your design system, you'll find the need for components that are similar to each other, with only slight differences.

  For example: you might have multiple components for buttons, with separate components for various states and sizes, as well as light and dark modes.

  Variants allow you to group and organize similar components into a single container. This simplifies your component library and makes it easier for everyone to find what they need.

  Customize the properties and values of your variants, to take the guesswork out of your design system and bring your components closer to front-end code.

  Note: We don't recommend using variants to group different icons.If you have different sizes of the same icon, then you could combine these as variants instead.

  Variant properties and values

  Variant properties and their values allow you to define the attributes of your variants. Variant properties are a type of component property specific to variants and component sets.

  You can add as many properties and values as you need, and customize them to suit your design system. You can even map your properties and values to code components in your design system.

  • Variable properties are the variable aspects of our component. For example: the properties of a button component could be the size, state, or color.
  • Values are the different options available for each property. For example: the state property could have default, hover, pressed, and disabled values.

  All variants within the component set should use the same properties and values, but each variant needs to be a unique combination of them. You don’t need to have a component for every possible combination of properties and values.

  Rename your components

  Figma uses the slash naming system to organize components in the Assets panel and Instance menu. Each / in a component's name will create another level of hierarchy.

  This makes it easier to navigate your library, or find and swap related components. Learn how to name and organize components →

  Tip! You can rename layers in bulk using the rename layers modal. Learn more about renaming layers in bulk →

  You can also use this naming system to convert your existing components to variants. To be accurately converted, component names need to follow this structure:

  componentName/property1value/property2value/property3value

  • The text before the first / will become the name of the component set.
  • Figma will create a new property for every other / in the component's name, then add the attribute as a value.
  • If you have used suffixes in your naming system, you will need to add these to the component's name, separated by a /.

  Caution: To make sure your values match up with the same property, every component you are combining needs to have the same number of slashes.

  A button component with the name Button/Primary/Large/Default/False will have the following properties and values:

  Component set name: Button
  Variant: Primary
  Property 2: Large
  Property 3: Default
  Property 4: False

  In the image below, we can see how the rest of our component names (on the left) are converted to variant values (on the right).

  Organize components on the canvas

  Note: Component sets can only contain components, so it's not possible to add text or annotations, nest frames, or group a subset of variants inside a component set.

  When combining components as variants, Figma will apply your existing layout and spacing to variants inside the component set. We recommend organizing your components before converting them, to save you from having to rearrange them after.

  If you have a lot of variants for a particular component, you may want to organize your components in rows, columns, or grids.

  This will help to communicate their multi-dimensional nature to anyone who's using your design system. You can also add text layers beside your component set to annotate the relevant properties and values.

  In our example below, we've arranged our button variants in a grid. We've also added text layers to the canvas that correspond to a property's values.

  Tip! By default, component sets have a dashed-purple stroke and no fill. You can adjust the fill and stroke properties of the component set to better suit your brand or design system.

  Combine as variants

  1. Select the components you want to combine. Learn how to select layers and objects →
  2. In the right sidebar, click the Combine as Variants button.
  3. Figma will add all components to a single component set.

  

  Give properties descriptive names

  As part of the conversion process, Figma will create generic properties and add any attributes you added to the component's name as values.

  As Figma doesn't know the names of the properties, it will name the first property Variant, then number them sequentially: Property 2, then Property 3, and so on.

  You'll need to rename those properties to something more descriptive.

  1. Select the component set.
  2. View the current properties in the Variants section in the right sidebar.
  3. Hover over the property so a grey box appears around it.
  4. Click to edit the property and give it a more descriptive name.
  5. Click outside the property to apply.
  6. Repeat for the remaining properties.

  

  Note: Figma handles component sets the same way as regular components. You can add descriptions and links to documentation to them. You can also drag them into the canvas from the Assets panel, and swap between instances of them.

  Create new variants

  Note: Figma places variants in a single container called a component set. Component sets can only contain components. Click Create component in the toolbar, or use the keyboard shortcut to turn your selection into a component:

  • Mac: ⌥ Option ⌘ Command K
  • Windows: Ctrl + Alt + K

  Learn how to create components →

  There are a few ways to create a new variant. Select a main component and:

  • Click from the toolbar, or
  • Right-click the main component > Main component > Add variant, or
  • Click in the Properties section of the right sidebar > Variant. This creates a new variant property and turns the main component into a component set.
    From there, click below the component set to add a variant.

  Figma will do a few things:

  • Make an identical component with the same properties
  • Add both components as variants to a component set
  • If you used the slash naming convention, the text before the / will become the name of the component set, and the attributes after will be used as values.

  You can also create new variants by combining multiple components ↑. 

  If you have an existing component set, add more variants ↓ to it at any time. 

  Tip! By default, component sets have a dashed-purple stroke and no fill. You can adjust the fill and stroke properties of the component set to better suit your brand or style guide.

  Add properties and values

  Create and apply properties and values to your variants when you first create them, or as your design system evolves. Learn how to create and apply properties and values →

  Fix conflicted value errors All variants within the component set will use the same properties and values, but each variant needs to be a unique combination of them.

  If any variants have the exact same combination of values, Figma will let you know that there is a conflict. You'll see this error even if the variants themselves are visually different.

  To resolve this issue, you'll need to add or update the values of the affected variants, so they have a unique combination of values.

  Add more variants to a component set

  Continue to add variants to your component set using any of the following methods:

  • Select a component set and click in the toolbar.
  • Select a component set and click on just below the component set. You'll only see this option once you have at least two variants.
  • Duplicate existing variant using the keyboard shortcut:
    • Mac: ⌘ CommandD
    • Windows: CtrlD
  • Drag other components into the component set to add them as variants.

  Tip! Dragging in other components won't reflow existing variants. You can use Smart Selection to adjust the layout of your variants. Learn more about smart selection →

  Caution: When you add an instance with variants to a file, Figma will import every variant in that component set. Importing large component sets will impact Figma's speed and performance.

  Manage variants

  Organize variants

  When you add new variants to a component, Figma's default behavior is to add variants in a single column, with equal spacing between them.

  If you have your components in another layout before converting them, Figma will keep the same layout for the component set.

  You can override Figma's default behavior and arrange variants in any way you choose.

  • Select a variant and move it to new co-ordinates within the component set. Figma will allow you to place variants anywhere within the component set, including over the top of other variants.
  • Adjust the dimensions of the component set in the right sidebar, or resize it in the canvas like you would a regular frame.
  • With all variants selected: Use the fields in the right sidebar to adjust the horizontal and vertical space between variants.

  Note: Figma will use the variant in the top-left corner as the default variant. This variant will represent the entire component set in the Assets panel.

  Manage properties and values

  You can rename and reorder properties and values anytime after creation. Remove properties you no longer need. Learn how to rename properties and values →

  • If you reorder properties, Figma will adjust the name and syntax of your variants to match.
  • If you've converted your existing components to variants, you'll need to rename your properties to make them more descriptive.

   

  Fix corrupted variant errors You will get a corrupted variant error if any of your variants do not follow this syntax. This can happen if you mistype a property or value, or use an invalid naming structure when converting existing components.

  To fix this issue, you'll need to rename the properties and values of the variant. While it's possible to rename them using this syntax in the layer name, we recommend renaming properties and values in the right sidebar instead.

  Publish component sets to a library

  If you're a member of a Professional or Education team, or a Figma Organization, you can share your variants with collaborators.

  Publish component sets alongside your styles and regular components to allow members of your team or organization to use them.

  Component sets appear in the Assets panel alongside your other components. Figma will use the variant in the top-left corner of the component set as the default variant.

  Collaborators can then drag the component set into their files to create an instance. They can then access all the other variants in the component set by configuring the property values in the right sidebar.

  Learn how to publish libraries →

  Are you a member of a Figma Organization? Design system analytics allow you to see how members of your organization are using components and variants. Learn how to track component and variant usage →

  Use variants

  Component sets appear in the Assets panel alongside any regular components. So instead of looking for a specific variant in the Assets panel, you only need to select the component set.

  Once you have an instance of that component set on the canvas, you can configure the instance's property values to select a variant.

  Select component sets

  1. Click on the Assets tab in the left sidebar, or use the keyboard shortcut:
     • Mac: ⌥ Option 2
     • Windows: Alt + 2
  2. Click on a component set and drag it on to the canvas. Figma will create an instance of the default variant of that component set.
  3. View the component set's name and properties in the right sidebar.
  4. Use the next to the property to select your preferred combination of values.
  5. Turn specific properties off and on using the and toggle switches.

  Configure variants

  Select other variants in a component set by configuring the properties and values in the right sidebar.

  1. Select the instance.
  2. View the name of the component in the right sidebar. If the component has variants, you'll see fields underneath the component name to configure the properties and values of that component set.
     • Use the next to the property to select your preferred combination of values.
     • Turn specific properties off and on using the and toggle switches

  Override preservation

  Figma will attempt to preserve your overrides when you select a different variant, or swap between instances in the Instance menu.

  Figma uses the following criteria to determine whether to preserve an override:

  • Layer names need to match between the current instance and the variant or instance you're selecting. This applies both when swapping instances and selecting variants
  • When selecting variants, Figma will also check if the layer properties you’ve overridden originally match between variants. If so, Figma will preserve your overrides.

  In our example below, Figma preserves the fill override on Step 3, but not on Step 4. This is because the default primary button and hover primary button both started with the same fill of #1BC47D. Our override was to change the hex code from #1BC47D to #F531B3.

  Figma doesn't preserve our override in Step 4 as the hover secondary variant has a fill of #ffffff, which is different to the fill we applied our original override to (#1BC47D).

  

  Tip! If you're not sure what variants are available in a component set, or their original styling, you can view the component set in the original file. With the instance selected, click the next to the component name in the right sidebar.

• Create interactive components with variants

  Who can use this feature

  Supported on any team or plan.

  Anyone with can edit access can create interactive components.

  Anyone with can edit access to the file can publish components to a library.

  New to Prototyping? Check out our Guide to prototyping in Figma →

  Interactive components allow you to create prototype interactions between variants in a component set. Any time you add an instance to your designs, those interactions are set up and ready to go. This saves you time when creating prototypes and prevents unnecessary noodle soup.

  • Create interactive elements that automatically switch between variants, like buttons that change from hover to pressed states.
  • Set default interactions at a component level and remove the guesswork when it comes to building prototypes.
  • Reduce the amount of frames and connections needed to prototype input fields, like a set of checkboxes or toggles.

  Note: Interactive components are an extension of variants. If you don't have a component set to work with, you'll need to create one first. Learn how to create and use variants →

  Before variant interactions

  In the example below we've added all the possible connections to prototype a frame with five checkboxes. Without interactive components, we would need to duplicate the same frame 32 times and create 160 connections between them to prototype every possible combination.

  

  With variant interactions

  With interactive components, we only need to add an instance of the checkbox to our design and its variant interactions are ready to go. When we view the prototype, Figma automatically switches between the checked and unchecked variants.

  

  Create interactive components

  You can only create interactive components using variants from the same component set. If you don't have a component set to work with, you'll need to create one first. Learn how to create variants →

  Create variant interactions

  Interactive components introduces a new prototype action: Change to.

  1. Select the starting variant for the interaction from within the component set.
  2. Navigate to the Prototype tab of the right sidebar.
  3. Click the on the right of the frame's bounding box and drag it to the destination variant. You can also click the in the Interactions section of the Prototype panel, set the action to Change to, then select the destination variant using the dropdown menu.
  4. Once the connection has been made, use the Interaction details panel to adjust the trigger and action.

  

  Note: The Change to action can only be used on variants in a component set. It's not possible to use this action between two separate components or top-level frames.

  Hands-on learner? Explore the interactive components playground file →

  Use interactive components

  Add instances of interactive components to your designs like any other component. The only difference is the instances already have interactions applied for prototyping.

  To use interactive components:

  1. Add an instance of an interactive component to a frame in your design.
  2. When you're ready to prototype your design, navigate to the Prototype tab of the right sidebar.
  3. Build your prototype.
  4. Preview designs and interactions in Presentation view.

  Note: Figma will use the existing rules to preserve any overrides you apply to the default variant in a component set. For example: changing the contents of a button label or swapping an icon.

  When you add an instance of a component set to the canvas, you also bring along the other variants in that component set. While you can technically still apply overrides to those other variants, Figma won't reflect those overrides in presentation view.

  Add more interactions

  When you're building a prototype with interactive components, you can add regular interactions on top of the variant interactions.

  In the example below, we have added an interaction with a click trigger on top of the variant interaction with delay.

  

  The interaction order will depend on whether the triggers you use are the same triggers as the variant interactions. Learn more about prototype triggers →

  Same triggers

  When both interactions use the same trigger, Figma will use the prototype interaction and ignore the variant interaction.

  For example:

  1. A toggle switch has an On click → Change to variant interaction between the On and Off variants in its component set.
  2. You add an On click → Navigate to interaction from the toggle switch to another frame.

  Figma will navigate to the next frame when the user clicks on the toggle switch.

  Different triggers

  When you add an interaction with a different trigger, Figma will play both the interaction and the variant interactions.

  For example:

  1. A button has an On hover → Change to variant interaction between the default and hover variants.
  2. You add an On click → Navigate to interaction when building your prototype.

  Figma will Change to the hover variant on hover , then Navigate to the next frame On click.

  View interactions

  When using interactive components, you will see separate sections for Interactions and Variant interactions in the Prototype tab of the right sidebar.

  • Use the Interactions section to create prototype interactions and animations
  • Use the Variant interactions section view a variant interaction's details

  Edit variant interactions

  You can override a variant interaction for an instance in your prototype. If you want to edit a variant interaction for the main component, you'll need to do so from the source file.

  To access a component set from an instance and make your edits:

  1. Select the instance.
  2. Click in the Instance section of the right sidebar.
  3. Select Go to main component.
  4. Navigate to the Prototype tab of the right sidebar.
  5. Make your edits to the variant interactions.

  Interactive components with custom fonts

  When using custom fonts for text inside interactive components, keep in mind that prototype viewers might not have those custom fonts installed on their devices. In these cases, Figma uses cached information about variants of interactive components to display custom fonts correctly when presenting a prototype, but may replace a font with Inter when we can’t both preserve text overrides and change font settings for an interaction.

  For example, let's say a person viewing your prototype doesn't have the custom font being used installed on their device. If an instance of an interactive component has a text overrides:

  • Figma may replace the custom font with Inter if the change in variants includes changing a font setting like weight or underline.
  • Figma will display the correct font if the change in variant isn't related to a font setting, like a button's background color.

  We recommend using Google fonts for prototypes that are being shared with viewers who may not have access to custom fonts in your designs. If your team is on the Organization or Enterprise plan, you can make sure prototype viewers have access to custom fonts by uploading them as shared fonts.

  Tip! Visit the Figma Forum to ask questions, share feedback, and connect with the Figma community!

• Swap components and instances

  Who can use this feature

  Supported on Education, Professional, and Organization, plans

  Anyone with can edit access to a file can insert components into a file.

  New to components and libraries? Guide to style and component libraries →

  Components let you create and reuse elements of your designs to speed up the process and keep things consistent.

  When building interfaces, we often switch between instances of these components for objects like icons, buttons, and cards.

  The Instance menu lets you quickly search, preview, and swap one component for another. There are a few ways you replace or swap instances in Figma.

  Want to swap instances in bulk? Use the Swap libraries feature to replace local instances with components from another library. Swap libraries →

  Note: Figma will try to preserve any overrides when you select a different variant, or swap between instances in the Instance menu. Learn more about override preservation →

  Instance menu

  The Instance menu allows you to find component replacements from the current file and any of your enabled team libraries.

  Access the Instance menu from the properties panel in the right sidebar, when you have a component selected.

  

  Figma orders components in the Instance menu based on the component's Name and Location.

  • Related components are components that share the same hierarchy. This includes components in the same file, page, and frame.
    
    For example: you can have a file containing your app's UI design system, a page for each operating system, and frames within each page where your components are grouped by type.

  • Figma also groups related components organized using the slash naming structure.
    
    For example: Figma considers UI/Button/Active, UI/Button/Hover, and UI/Button/Inactive as related components.

  

  Learn how to name and organize components →

  To swap an instance using the Instance menu:

  1. Select the instance you want to replace. Figma will display the name of the component in the Instance section of the right sidebar.
  2. Click the name of the component to open the Instance menu.
  3. Use the menu to navigate through components:
     1. Select from the group of related components for your selection.
     2. Use the field to search a component by name.
     3. Click to switch between enabled libraries.
     4. Click to navigate to a different group of components.
     5. Use the and to switch between grid and list view.
  4. Select an instance to replace the current selection.

  

  Assets panel

  The Assets panel in the left sidebar allows you to search for components to add to your file. You can find components from any libraries you have access to.

  You can drag a component onto the canvas to create an instance of that component. If you use the modifier key while dragging a component from the Assets panel, you can replace the existing component.

  1. Open the Assets panel and find the component.
  2. Hold down the modifier key: If the component isn't nested within another frame or component
     • Mac: ⌥ Option
     • Windows: Alt
     If the component is nested within another Frame or component
     • Mac: ⌥ Option - ⌘ Command
     • Windows: Alt + Control
  3. Drag the component above the instance you want to swap in the canvas.
  4. Release the mouse, then release the modifier key. If you release the modifier key first, Figma will only add the new component, not replace.

  Note: Figma only preserves text overrides. To keep any changes you've made to text layers, rename the layers so they're unique. If you swap a component with other overrides applied, we won't apply these to the new component. Learn more about overriding properties of an instance.

  Quick insert

  Swap instances of components from your keyboard using quick insert. Quick insert opens the Resources modal where you can find and view components from enabled libraries. The components found in the Resources modal mirror what you see in the Assets panel.

  1. Select the layer or instance you want to swap.
  2. Use the shortcut Shift I to open quick insert.
  3. To locate a component, do one of the following: 
     • Use the search field to find a specific component. Use your mouse or arrow keys to navigate to the relevant component.
     • Use the and icons to switch between grid and list view.
     • Select from recent components used across your files, or select from an enabled library. If a library is not displaying, you may need to enable the library first. Manage libraries in design files →
  4. Hold down ⌥ Option (Mac) or Ctrl (Windows). 

  

  Right-click menu

  You can also use the right-click menu to switch between related components. This will only allow you to select components in the same frame or hierarchy.

  1. Right-click on the instance in the canvas.
  2. Hover over the Swap Instance option.
  3. Select an instance from the list of related components.