Swap style and component libraries – Figma Learn - Help Center

If you're using UI3, Figma's new design, some parts of this article might not match what you see in the product today. We appreciate your patience while we make updates. Learn more about Figma’s redesign →

Who can use this feature

Supported on Professional, Education, and Organization plans

Only people with can edit access to the file, and at least can view access to affected libraries

Swap libraries lets you ‌quickly update instances in a file so they use components from another library. Use swap library to:

Use a different or newer version of a library
Swap to external or agency-provided libraries
Manage instances from missing or unpublished libraries

Note: Library swap currently supports swapping components and styles, but not variables. However, if you swap a component or style out for an asset that contains variables applied to it, the variable will remain attached to the asset. You can also head to the Figma Community to find plugins that allow you to swap variables between libraries.

How does swap library work?

Swap library lets you replace styles and component instances in a current file with those of another published library. You can swap any library you have at least can view access to.

Swap library only works if the assets you want to replace originate from a different library. In other words, you cannot replace local assets—assets that live in the same file as their main source—by swapping them with another library.

When swapping, Figma looks for any styles and components in the selected library with matching names. This includes components sets and the variants within them.

If you've deleted components, or recreated them with different names, Figma won't recognize or match these components.

Unmatched assets

If a matching style or component isn't found in the selected library, Figma won't swap those assets and they'll remain connected to the original library.

You can choose to ignore these styles and instances, delete them from the file, or manually swap instances using the Instance menu. Swap between component instances →

Swap or override styles

The Swap default styles in instances setting allows you to control how styles are applied to instances and whether they'll be treated as overrides.

Checked: Figma applies matching styles to instances as overrides. If you swap the instance via swap libraries, the applied matching styles will be preserved.
Unchecked: Figma applies matching styles to instances as normal. If you swap the instance via swap libraries, the applied matching styles will not be preserved.

If you're swapping to an updated version of a library or replacing a missing library, you'll likely have both styles and components available for swap. If you want to swap only the instances and continue using the styles defined on the main components, leave this setting unchecked.

The swapped instances will continue to receive updates from their main components and any changes you applied to them via swap libraries will be overwritten.

Regardless of whether this box is checked, Figma will preserve any overrides—which aren’t related to swapped styles—applied to instances. Learn more about override preservation →

Swap between libraries

Swap styles and components in the current file with instances from another library. This replaces instances with matching instances from another library.

Before you swap, make sure:

The current file you're working from contains at least one instance or style that you wish to swap, and the asset is from a different library.
Both libraries involved in the swap (the library being replaced and the soon-to-be-used library) are published to team libraries.
Any assets you wish to swap have matching names.

To swap between libraries:

Open the Assets panel in the left sidebar.
Click Library to open the library modal.
The Libraries available in this file section contains a list of libraries with styles and components being used in the file. Select the library you wish to replace.
Click Swap library at the bottom of the modal.
Use the Choose library dropdown to find a select a replacement library.
- View libraries available to the entire organization
- Explore published libraries by team
Figma looks for any styles and components with a matching name. Use the checkboxes on the left to choose which assets to swap.
- If a matching style or component is found, the box next to the asset is checked and you'll see a preview in the selected library.
- If no matching styles or components are found, the box is unchecked and you'll see a None found message.
- If there are incorrect or undesired matches, use the checkbox to remove the asset from the swap.
Decide whether to apply matched styles as overrides using the Swap default styles in instances ↑ setting.
- Check to apply matched styles as overrides.
- Leave unchecked to swap instances and use the default styles defined on the main components. Figma will preserve any supported overrides you've applied (default).
Click Swap library to replace assets with assets from your selected library.

Manage missing libraries

Styles and instances can be disconnected from their library when the original file is unpublished, deprecated, or moved to a team you can't access.

Use the library modal to view styles and instances in the current file that aren't connected to an active library. Then use Swap library to replace any instances in the current file with instances from another library.

Figma matches styles and components by name only. It's not possible to manually select a new style or component, or match it to an asset with a slightly different name. Figma won't swap any styles and components without a match. You can also deselect any matched assets you don't want to swap.

Swap missing libraries