figma_swap_component
Swap one or more Figma instances to a different main component in one transaction, preserving compatible overrides and previewing losses via dry-run before applying.
Instructions
Swap one or more INSTANCEs to another main component in ONE transaction, preserving the overrides that still fit. The dry run (default) compares the old and new structures and returns, per target: a fingerprint of the instance and the target component, an exact or name-remapped path for every direct layer override, mapped component properties (by display name and type), root-level instance overrides (custom name, resized geometry, opacity, fills/strokes/effects and style links, layout placement) and every named loss. Apply with the returned planId and expectedFingerprints; it refuses a document that moved, a lossy swap unless allowLoss:true, and a library component whose structure could not be checked unless allowUnverified:true. Variant properties are not replayed — the chosen target component decides them. A layer whose node type changed, a missing layer, a changed nested component and a SLOT property are reported, never applied to a guessed layer. A target nested inside another INSTANCE is refused: that is an override of the outer instance, not an independent swap. The apply is one undo step; a failure rolls the whole call back, and the report says what rolled back. Plugin API swapComponent is the mechanism; Figma's own override heuristics are re-checked, not trusted.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"nodeIds": "<nodeIds>"
},
"name": "figma_swap_component"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | TRUE (default): compare and fingerprint only. FALSE: apply in one undo transaction. | |
| planId | No | The planId returned by figma_swap_component; if supplied on apply, a different request is refused before it is sent | |
| fileKey | No | Which connected Figma file to use: its fileKey (figma_whoami) or, when omitted, the only connected file. Required once more than one file is connected; figma_ping lists them. | |
| nodeIds | Yes | INSTANCE targets (1–50). Their current main components may differ. | |
| allowLoss | No | Apply even when the dry run named a layer/property loss; the same losses are then reported | |
| componentId | No | A local COMPONENT to swap to | |
| componentKey | No | A local or library COMPONENT key; a library key is imported on apply | |
| preserveSize | No | Keep an instance that was manually resized at its old size; false adopts the new component's size | |
| componentName | No | Exact local COMPONENT or COMPONENT_SET name; ambiguous names are refused | |
| componentSetId | No | A local COMPONENT_SET; combine with variantProperties to pick a variant | |
| allowUnverified | No | Apply a library component whose structure could not be compared before import | |
| componentSetKey | No | A local or library COMPONENT_SET key; combine with variantProperties to pick a variant | |
| variantProperties | No | Variant selector for a component set, e.g. {"Size":"L","Tone":"Dark"}. Omit for the default variant. | |
| expectedFingerprints | No | Required on apply: nodeId -> fingerprint from the dry run, covering the instance state and target component. A changed target is refused before writing. | |
| preserveRootOverrides | No | Reapply custom name, size, opacity, paints, effects, layout placement and style links that differ from the old main component |