Move published components
Who can use this feature
Supported on Professional, Education, and Organization plans.
Only people with Can edit access to both the origin file and the destination file can move components between files.
Want to move styles to another file? Check out our Manage and share styles article for step-by-step instructions.
Move published components and component sets between files, without breaking links to instances. Use this process to split up large libraries into smaller files.
You can only use this process to move published components. You can still copy and paste main components and their instances between files. Figma will keep connections between components and instances as long as they remain in the same file.
This is a two part process: cut and paste the components, and publish the changes. You must do both to move the component and update connected instances.
How does it work?
Every component has a unique id. Figma uses this id to maintain the connection between the main component and any instances of that component.
When you cut and paste a component between files, Figma treats the pasted component as a new component. The new component has a unique id that's different from the original main component.
When you publish the duplicate to a library, Figma notifies any subscribed files of the changes. It's only when you accept these updates that Figma swaps to instances from the destination library.
Because of how this works behind the scenes, it's not possible to undo or reverse this process. The only way to undo this action ↓ is to move components back to their original file.
Using library analytics? Figma treats moved components as new components in your organization's Library analytics. Learn more about library analytics →
Glossary
- Published component: A component that is published to a team or organization library. Instances across files, projects, or team can receive updates from published components.
- Local components: A component that lives in the current file and isn't published to a library. Local instances are only updated if they live within the same file as the component. This includes any components you've intentionally hidden.
- Origin file: Specific to the action of moving a component. The origin file is the file where components live(d) before being moved to a new location.
- Destination file: Specific to the action of moving a component. The destination file is the file where components are moved to, this can be a new or existing file/library.
- Subscribed file: A Figma design or FigJam file with styles and instances that are linked to an active published library.
Move components or component sets
Before you start moving components, there are a few things to consider. We recommend reviewing these steps to make sure your components work as intended in their new location.
1. Publish hidden components
Hidden components are components that you haven't published to your library. It's not possible to move hidden components between files.
If you have components that use nested instances of a hidden component, you need to publish hidden components, before you can move them to another file. Once you've moved those components and published the changes to the library, you can hide them again.
The entire process looks like this:
2. Check nested instances and overrides
If you have main components that use nested instances, you need to consider where the main components live. Especially if there are overrides applied to them.
If the main components are within the same file, we recommend you move and publish components together. If the main components for nested instances are hidden, you need to publish them first.
If components use main components from another published library, Figma will keep the connection to that library.
We recommend publishing components from the destination library, before you start making changes to those components.
Let's explore an example
You have a main component of a dialog window. In that component, are nested instances of a button component and an icon component. Both the icon and the button are hidden components.
In an instance of the dialog component, the generic information icon was swapped with a warning icon and color overrides were applied to both the icon and primary button.
To successfully move these component and preserve overrides:
- Publish icon and button components to the library. Publish hidden components →
- Cut all components from the current file — this includes the icon and button components and the dialog component that uses instances of those components.
- Paste those components into the destination file. See below ↓
- Publish the destination file as a library. See below ↓
- Accept updates from the library in any subscribed files. Accept library updates →
- Hide both the icon and button main components. Hide components when publishing →
3. Restore deleted variants you want to keep
To move a component set, you need to cut and paste them between files. Figma will only copy the variants that exist at the time you cut and pasted them.
If you have deleted a variant, but want to use it again in the future, you need to restore the variant from the origin file. We recommend doing this before moving the component set. You can restore a deleted variant after you've moved the component set, as long as the origin file still exists.
- Restore deleted variants from any instances. This will restore those variants as main components in the origin file.
- Publish these restored components to the library in the origin file—you can only move published components.
- Move the restored components to the destination file using the cut and paste method ↓.
- Drag any restored component into the existing component set.
Cut and paste components
Move published components and component sets between files and their libraries using cut and paste. You can choose to keep any existing connections between components and instances, or treat them as entirely new components.
You can paste main components into a branch of a file. Figma won't update the libraries and any subscribed files until the branch is merged and the library published.
To move a component or component set:
- Open the file where the main component lives, this is the origin file.
- Select the main components or component sets you want to move.
- Use the cut shortcut to add them to your clipboard:
- Mac: ⌘ Command - X
- Windows: Ctrl + X
- Open the file and you want to move components to, this is the destination file.
- Make sure you have nothing selected, then paste components into the file.
- Mac: ⌘ Command - V
- Windows: Ctrl + V
Note: It's possible to make changes to the components before publishing. We recommend publishing the library first, before making any structural changes to components and variants.
Publish library changes
When you move published components between files, Figma will prompt you to publish your changes to any affected libraries.
You need to publish these changes to complete the move process. Figma will push updates to all subscribed files when you publish your changes.
- Click Publish in the notification, or use the shortcut to open the library modal:
- Mac: ⌥ Option 3
- Windows: Alt 3
- Figma lists any changes to the library, including every component you've moved to this file. For each component, choose to Move to this file or Publish as a copy.
- Select Move to this file for all moved components. This makes sure Figma keeps connections between the main components and any existing instances.
- Select Publish as copy to publish them as new main component. This will break the connection between the component and any instances, instances won't receive further updates.
- Add a description of your changes, Figma shows this in the file's version history.
- Click Publish to publish your changes to the library.
Publish updates to a library →
Receive updates
Figma will push updates to any file that uses those styles and components. You'll see the usual bell notification and a prompt to receive updates from the library. Review and accept updates from libraries →
Instances will stay linked to deleted components in the origin file until you review and accept updates. Accept updates in subscribed files to update local instances.
Subscribed files
If you select or edit an instance before receiving updates, this will still point to the deleted main component in the origin file. Once you receive updates from the library, Figma will point to the main component in the destination file.
Local instances in the origin file
Local instances in the origin file won't receive updates until those components are published to the library of the destination file.
Click Update to receive updates and make sure those instances are now linked to components in their new location.
Local instances in destination file
If instances in the destination file are linked to components you've moved from the original file, Figma will automatically update them to point to the newly moved local components.
Note: If the new library isn't enabled in a subscribed file, Figma will enable the library in that file when instances receive updates.
Reverse or undo move component
It's not possible to undo the action of moving components using any of these methods:
- Using the undo keyboard shortcut
- Restoring deleted components from an instance
- Restoring an earlier version of the file's version history
While you can still take these actions in a file, this won't return components to their original location and you may end up with other unintended consequences.
We recommend using the move component process outlined above ↑ to move components back to their original location.