1# Component & Variant API Patterns
2 
3> Part of the [use_figma skill](../SKILL.md). How to correctly use the Plugin API for components, variants, and component properties.
4>
5> For design system context (when to use variants vs properties, code-to-Figma translation, property model), see [wwds-components](working-with-design-systems/wwds-components.md).
6 
7## Contents
8 
9- Creating a Component
10- Combining Components into a Component Set (Variants)
11- Laying Out Variants After combineAsVariants (Required)
12- Component Properties: addComponentProperty API
13- Linking Properties to Child Nodes (Required)
14- INSTANCE_SWAP: Avoiding Variant Explosion
15- Discovering Existing Conventions in the File
16- Importing Components by Key
17- Working with Instances (finding variants, setProperties, text overrides, detachInstance)
18 
19 
20## Creating a Component
21 
22`figma.createComponent()` returns a `ComponentNode`, which behaves like a `FrameNode` but can be published, instanced, and combined into variant sets.
23 
24```javascript
25const comp = figma.createComponent();
26comp.name = "MyComponent";
27comp.layoutMode = "HORIZONTAL";
28comp.primaryAxisAlignItems = "CENTER";
29comp.counterAxisAlignItems = "CENTER";
30comp.paddingLeft = 12;
31comp.paddingRight = 12;
32comp.layoutSizingHorizontal = "HUG";
33comp.layoutSizingVertical = "HUG";
34comp.fills = [{ type: "SOLID", color: { r: 0.2, g: 0.36, b: 0.96 } }];
35```
36 
37## Combining Components into a Component Set (Variants)
38 
39`figma.combineAsVariants(components, parent)` takes an array of `ComponentNode`s (not frames — frames will throw) and groups them into a `ComponentSetNode`.
40 
41Variant names use a `Property=Value` format. Every unique combination must exist as a child component — missing ones show as blank gaps in the variant picker.
42 
43```javascript
44// Each component's name encodes its variant properties
45const comp1 = figma.createComponent();
46comp1.name = "size=md, style=primary";
47const comp2 = figma.createComponent();
48comp2.name = "size=md, style=secondary";
49 
50const componentSet = figma.combineAsVariants([comp1, comp2], figma.currentPage);
51componentSet.name = "Button";
52```
53 
54**Before creating variants, inspect the file** for existing naming patterns. Different files use different conventions (`State=Default` vs `state=default` vs `State/Default`). Always match what's already there.
55 
56## Laying Out Variants After combineAsVariants (Required)
57 
58After `combineAsVariants`, all children stack at `(0, 0)`. You **must** position them or the component set will appear as a single collapsed element with all variants overlapping.
59 
60```javascript
61const cs = figma.combineAsVariants(components, figma.currentPage);
62 
63// Simple row layout
64cs.children.forEach((child, i) => {
65  child.x = i * 150;
66  child.y = 0;
67});
68 
69// CRITICAL: resize the component set from actual child bounds
70let maxX = 0, maxY = 0;
71for (const child of cs.children) {
72  maxX = Math.max(maxX, child.x + child.width);
73  maxY = Math.max(maxY, child.y + child.height);
74}
75cs.resizeWithoutConstraints(maxX + 40, maxY + 40);
76```
77 
78For multi-axis variants (e.g., size × style × state), parse the child's name to determine grid position:
79 
80```javascript
81for (const child of cs.children) {
82  const props = Object.fromEntries(
83    child.name.split(', ').map(p => p.split('='))
84  );
85  const col = stateValues.indexOf(props.state);
86  const row = styleValues.indexOf(props.style);
87  child.x = col * colWidth;
88  child.y = row * rowHeight;
89}
90```
91 
92## Component Properties: addComponentProperty API
93 
94`addComponentProperty` adds a TEXT, BOOLEAN, or INSTANCE_SWAP property to a component. It returns a **string key** (e.g., `"label#4:0"`) — never hardcode or guess this key.
95 
96```javascript
97// Returns the key as a string — capture it!
98const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Default text');
99const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', true);
100const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComponentId);
101```
102 
103**Timing**: Add component properties to each variant component **before** calling `combineAsVariants`. After combining, the component set inherits all properties from its children. Do not add properties to the `ComponentSetNode` directly.
104 
105## Linking Properties to Child Nodes (Required)
106 
107A property that is added but not linked to a child node does **nothing**. You must set `componentPropertyReferences` on the child:
108 
109```javascript
110// TEXT property → link to a text node's characters
111const labelKey = comp.addComponentProperty('Label', 'TEXT', 'Button');
112const textNode = figma.createText();
113textNode.characters = "Button";
114comp.appendChild(textNode);
115textNode.componentPropertyReferences = { characters: labelKey };
116 
117// BOOLEAN + INSTANCE_SWAP → link to an instance node
118const showIconKey = comp.addComponentProperty('Show Icon', 'BOOLEAN', true);
119const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComp.id);
120const iconInstance = iconComp.createInstance();
121comp.appendChild(iconInstance);
122iconInstance.componentPropertyReferences = {
123  visible: showIconKey,        // BOOLEAN controls show/hide
124  mainComponent: iconSlotKey   // INSTANCE_SWAP controls which component
125};
126```
127 
128**Valid `componentPropertyReferences` keys:**
129- `characters` — TEXT property on a TextNode
130- `visible` — BOOLEAN property (any node)
131- `mainComponent` — INSTANCE_SWAP property on an InstanceNode
132 
133## INSTANCE_SWAP: Avoiding Variant Explosion
134 
135When a component has many possible sub-elements (e.g., 30 different icons), **never** create a variant per sub-element. Use a single INSTANCE_SWAP property instead — the user picks from any compatible component at design time.
136 
137```javascript
138// Create icon as its own ComponentNode
139const iconComp = figma.createComponent();
140iconComp.name = "Icon/Search";
141iconComp.resize(24, 24);
142const svgNode = figma.createNodeFromSvg('<svg>...</svg>');
143iconComp.appendChild(svgNode);
144 
145// Use it as the default for INSTANCE_SWAP
146const iconSlotKey = comp.addComponentProperty('Icon', 'INSTANCE_SWAP', iconComp.id);
147const instance = iconComp.createInstance();
148comp.appendChild(instance);
149instance.componentPropertyReferences = { mainComponent: iconSlotKey };
150```
151 
152This works for icons, avatars, badges, or any swappable nested element.
153 
154## Discovering Existing Conventions in the File
155 
156**Always inspect the file before creating components.** Different files have different naming styles, structures, and conventions. Your code should match what's already there.
157 
158### List all existing components across all pages
159 
160```javascript
161const results = [];
162for (const page of figma.root.children) {
163  await figma.setCurrentPageAsync(page);
164  page.findAll(n => {
165    if (n.type === 'COMPONENT') results.push(`[${page.name}] ${n.name} (COMPONENT) id=${n.id}`);
166    if (n.type === 'COMPONENT_SET') results.push(`[${page.name}] ${n.name} (COMPONENT_SET) id=${n.id}`);
167    return false;
168  });
169}
170return results.join('\n');
171```
172 
173### Inspect an existing component set's variant naming pattern
174 
175```javascript
176const cs = await figma.getNodeByIdAsync('COMPONENT_SET_ID');
177const variantNames = cs.children.map(c => c.name);
178const propDefs = cs.componentPropertyDefinitions;
179return { variantNames, propDefs };
180```
181 
182### Find existing components in the file
183 
184```javascript
185const components = [];
186for (const page of figma.root.children) {
187  await figma.setCurrentPageAsync(page);
188  page.findAll(n => {
189    if (n.type === 'COMPONENT') {
190      components.push({ name: n.name, id: n.id, page: page.name, w: n.width, h: n.height });
191    }
192    return false;
193  });
194}
195return components;
196```
197 
198## Importing Components by Key (Team Libraries)
199 
200`importComponentByKeyAsync` and `importComponentSetByKeyAsync` import components from **team libraries** (not the same file you're working in). For components in the current file, use `figma.getNodeByIdAsync()` or `findOne()`/`findAll()` to locate them directly.
201 
202```javascript
203// Import a component from a team library
204const comp = await figma.importComponentByKeyAsync("COMPONENT_KEY");
205const instance = comp.createInstance();
206 
207// Import a component set from a team library and pick a variant
208const set = await figma.importComponentSetByKeyAsync("COMPONENT_SET_KEY");
209const variant = set.children.find(c =>
210  c.type === "COMPONENT" && c.name.includes("size=md")
211) || set.defaultVariant;
212const variantInstance = variant.createInstance();
213```
214 
215## Working with Instances
216 
217### Finding the right variant in a component set
218 
219Parse variant names to match on multiple properties simultaneously:
220 
221```javascript
222const compSet = await figma.importComponentSetByKeyAsync("KEY");
223 
224const variant = compSet.children.find(c => {
225  const props = Object.fromEntries(
226    c.name.split(', ').map(p => p.split('='))
227  );
228  return props.variant === "primary" && props.size === "md";
229}) || compSet.defaultVariant;
230 
231const instance = variant.createInstance();
232```
233 
234### Setting variant properties on an instance
235 
236After creating an instance from a component set, you can set variant properties via `setProperties`:
237 
238```javascript
239const instance = defaultVariant.createInstance();
240instance.setProperties({
241  "variant": "primary",
242  "size": "medium"
243});
244```
245 
246### Overriding text in a component instance
247 
248**Always discover component properties BEFORE writing text overrides.** Components expose text as `TEXT`-type component properties, and `setProperties()` is the correct way to override them. Direct `node.characters` changes on property-managed text may be overridden by the component property system on render.
249 
250**Step 1: Inspect componentProperties on a sample instance:**
251 
252```javascript
253const instance = comp.createInstance();
254const propDefs = instance.componentProperties;
255// Returns e.g.: { "Label#2:0": { type: "TEXT", value: "Button" }, "Has Icon#4:64": { type: "BOOLEAN", value: true } }
256return propDefs;
257```
258 
259Also check nested instances — a parent component may not expose text properties directly, but its nested child instances might:
260 
261```javascript
262const nestedInstances = instance.findAll(n => n.type === "INSTANCE");
263const nestedProps = nestedInstances.map(ni => ({
264  name: ni.name,
265  id: ni.id,
266  properties: ni.componentProperties
267}));
268```
269 
270**Step 2: Use setProperties() for TEXT-type properties:**
271 
272```javascript
273const instance = comp.createInstance();
274const propDefs = instance.componentProperties;
275for (const [key, def] of Object.entries(propDefs)) {
276  if (def.type === "TEXT") {
277    instance.setProperties({ [key]: "New text value" });
278  }
279}
280```
281 
282For nested instances that expose their own TEXT properties, call `setProperties()` on the nested instance:
283 
284```javascript
285const nestedHeading = instance.findOne(n => n.type === "INSTANCE" && n.name === "Text Heading");
286if (nestedHeading) {
287  nestedHeading.setProperties({ "Text#2104:5": "Actual heading text" });
288}
289```
290 
291**Step 3: Only fall back to direct node.characters for unmanaged text.** If text is NOT controlled by any component property, find text nodes directly. **Always load the node's actual font first** — instance text nodes inherit fonts from the source component, so don't assume Inter Regular:
292 
293```javascript
294const textNodes = instance.findAll(n => n.type === "TEXT");
295for (const t of textNodes) {
296  await figma.loadFontAsync(t.fontName);
297  t.characters = "Updated text";
298}
299```
300 
301### detachInstance() invalidates ancestor node IDs
302 
303**Warning:** When `detachInstance()` is called on a nested instance inside a library component instance, the parent instance may also get implicitly detached (converted from INSTANCE to FRAME with a **new ID**). Subsequent `getNodeByIdAsync(oldParentId)` returns null.
304 
305```javascript
306// WRONG — cached parent ID becomes invalid after child detach
307const parentId = parentInstance.id;
308nestedChild.detachInstance();
309const parent = await figma.getNodeByIdAsync(parentId); // null!
310 
311// CORRECT — re-discover nodes by traversal from a stable (non-instance) parent
312const stableFrame = await figma.getNodeByIdAsync(manualFrameId); // a frame YOU created
313nestedChild.detachInstance();
314// Re-find the parent by traversing from the stable frame
315const parent = stableFrame.findOne(n => n.name === "ParentName");
316```
317 
318If you must detach multiple nested instances across sibling components, do it in a **single** `use_figma` call — discover all targets by traversal at the start before any detachment mutates the tree.
319 
320## Inspecting Component Metadata (Deep Traversal)
321 
322These helpers extract the full property schema and descendant structure of a component. Useful for understanding complex components before creating instances or setting properties.
323 
324```javascript
325/**
326 * Imports a component or component set from a library by its published key.
327 * Tries COMPONENT first, then falls back to COMPONENT_SET.
328 *
329 * @param {string} componentKey - The published key of the component or component set.
330 * @returns {Promise<ComponentNode|ComponentSetNode>}
331 */
332async function importComponentByKey(componentKey) {
333  try {
334    return await figma.importComponentByKeyAsync(componentKey);
335  } catch {
336    try {
337      return await figma.importComponentSetByKeyAsync(componentKey);
338    } catch {
339      throw new Error(`No Component or Component Set available with key '${componentKey}'`);
340    }
341  }
342}
343 
344/**
345 * Given a main component node, returns the component set parent if one exists,
346 * otherwise returns the component itself. Used to get the top-level node that
347 * holds `componentPropertyDefinitions`.
348 *
349 * @param {ComponentNode} mainComponent
350 * @returns {ComponentNode|ComponentSetNode}
351 */
352function getRelevantComponentNode(mainComponent) {
353  return mainComponent.parent.type === "COMPONENT_SET"
354    ? mainComponent.parent
355    : mainComponent;
356}
357 
358/**
359 * Extracts `componentPropertyDefinitions` from a component or component set node
360 * into a flat map keyed by property key.
361 *
362 * @param {ComponentNode|ComponentSetNode} node
363 * @returns {Record<string, {name: string, type: string, key: string, variantOptions?: string[]}>}
364 */
365function getComponentProps(node) {
366  const result = {};
367  for (let key in node.componentPropertyDefinitions) {
368    const prop = {
369      name: key.replace(/#[^#]+$/, ""),
370      type: node.componentPropertyDefinitions[key].type,
371      key: key
372    };
373    if (prop.type === "VARIANT") {
374      prop.variantOptions = node.componentPropertyDefinitions[key].variantOptions;
375    }
376    result[key] = prop;
377  }
378  return result;
379}
380 
381/**
382 * Recursively walks a component tree and collects all INSTANCE and TEXT nodes
383 * into `result`, keyed by `TYPE[name]`. Handles variant namespacing and
384 * deduplicates nodes with identical names but differing property references.
385 *
386 * @param {SceneNode} node - The node to traverse.
387 * @param {string[]} namespace - Accumulated variant names for the current path.
388 * @param {Record<string, object>} result - Accumulator object populated in place.
389 */
390function collectDescendants(node, namespace, result) {
391  if (node.type === "INSTANCE" || node.type === "TEXT") {
392    const references = node.componentPropertyReferences || {};
393    if (!node.visible && !references.visible) return;
394 
395    const object = { type: node.type, name: node.name, references };
396    let key = `${node.type}[${node.name}]`;
397 
398    if (result[key] && JSON.stringify(references) !== JSON.stringify(result[key].references)) {
399      key += btoa(btoa(unescape(encodeURIComponent(JSON.stringify(references)))));
400    }
401 
402    if (node.type === "INSTANCE") {
403      const mainComponent = getRelevantComponentNode(node.mainComponent);
404      object.properties = getComponentProps(mainComponent);
405      object.descendants = {};
406      object.mainComponentName = mainComponent.name;
407      collectDescendants(mainComponent, [], object.descendants);
408    }
409 
410    const start = namespace.length ? { variants: [] } : {};
411    result[key] = Object.assign(object, result[key] || start);
412    if (namespace.length) result[key].variants.push(namespace[namespace.length - 1]);
413  } else if ("children" in node && node.visible) {
414    if (node.type === "COMPONENT" && node.parent.type === "COMPONENT_SET") namespace.push(node.name);
415    node.children.forEac