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.
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.
Want to move styles to another file? The process for moving styles is different to moving components. Check out our Manage and share styles article for step-by-step instructions.
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.
- 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.
Using library analytics? Figma treats moved components as new components in your organization's Library analytics. Learn more about library analytics →
Move components or component sets
Move published components and component sets between files and their libraries using cut and paste. Keep existing connections between components and instances, or treat them as entirely new components.
Before you move components
There are a few things to consider before moving components:
Publish hidden components
It's not possible to move hidden components between files. This is something to look out for, especially 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 mark hide them again.
Nested instances and overrides
If you have nested instances within the components you're moving, you need to consider where the main components live. Especially if you've applied overrides 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 think about 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 →
Moving components and component sets requires you to cut and paste those components between files. Figma will only move variants that exist in the file at the time you cut and paste them.
If you have deleted variants and anticipate restoring them in the future, you need to do this from the origin file. We recommend doing this before moving the component set, but you can do this after, 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 components to the destination file using the cut and paste method below.
- Drag the moved component into an existing component set.
Note: 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.
Cut and paste components
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 →
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.
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.