Page Switching and Context Management in use_figma: A Complete Guide

Every use_figma call executes against a fresh headless runtime where figma.currentPage always resets to the first page, requiring explicit await figma.setCurrentPageAsync() calls to work on other pages.

The use_figma tool in the figma/mcp-server-guide repository provides a JavaScript execution environment for automating Figma files. Because each invocation runs in an isolated, stateless context, understanding how to manage page switching and context management is critical for scripts that operate beyond the default page.

Why Page Context Resets on Every Call

The use_figma runtime is re‑instantiated for each invocation to guarantee script isolation. This architectural choice means any mutable state—including the current page selection—is discarded between calls. According to the source code in skills/figma-use/SKILL.md (lines 42‑46), figma.currentPage always starts on the first page of the file regardless of previous operations.

This design ensures side‑effect‑free execution unless you deliberately mutate the file. Each call is atomic: if a page switch fails, the entire script rolls back without partial changes.

How to Switch Pages in use_figma

The Async Switching Pattern

Unlike browser-based plugin development, the headless runtime does not support the synchronous setter figma.currentPage = page. As documented in skills/figma-use/references/plugin-api-patterns.md (lines 23‑30), you must use the asynchronous API:

// 1️⃣ Find the target page by name (or by index)
const targetPage = figma.root.children.find(p => p.name === "My Page");

// 2️⃣ Load its content – this is the only safe way to change pages
await figma.setCurrentPageAsync(targetPage);

// 3️⃣ Now the page’s children are populated and you can read or modify them
const frame = figma.createFrame();
frame.name = "New Section";
frame.resize(800, 600);
targetPage.appendChild(frame);

Key rules for page switching and context management in use_figma:

• Always await the async call: The synchronous setter throws an error in this runtime.
• Switch before access: Node lookups on the wrong page return null or undefined.
• Iterate explicitly: When working across pages, loop over figma.root.children and switch for each iteration.

Common Page Switching Mistakes and Fixes

Symptom	Cause	Fix
"Setting figma.currentPage is not supported"	Used the synchronous assignment figma.currentPage = …	Replace with await figma.setCurrentPageAsync(page)
"Cannot read properties of null"	Accessing nodes before switching to the correct page	Ensure await figma.setCurrentPageAsync() succeeds before lookups
Nodes appear at (0,0) unexpectedly	Creating top‑level nodes on the default page after a failed switch	Verify the promise resolved and check figma.currentPage.name

Practical Code Examples

Switch to a Named Page and Create a Rectangle

This pattern targets a specific page by name, switches context, and creates a shape:

const page = figma.root.children.find(p => p.name === "Landing");
await figma.setCurrentPageAsync(page);

const rect = figma.createRectangle();
rect.name = "Hero Background";
rect.resize(1440, 800);
rect.fills = [{ type: "SOLID", color: { r: 0.9, g: 0.9, b: 0.95 } }];

page.appendChild(rect);
return { createdNodeIds: [rect.id] };

Iterate Over All Pages to Count Frames

When you need to aggregate data across the entire file, switch pages inside a loop:

const counts = {};

for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);   // load page contents
  const frameCount = page.findAll(n => n.type === "FRAME").length;
  counts[page.name] = frameCount;
}
return counts;   // e.g. {Home: 12, Dashboard: 8}

Multi-Step Workflows with Page Switching

For complex automation, split discovery and modification into separate steps. Pass the target page name from a discovery step to a creation step:

// Step 1 – discover pages (returns list to the agent)
const pages = figma.root.children.map(p => p.name);
return { pages };

// Step 2 – create a component on a specific page (called later with args.pageName)
const targetName = args.pageName;   // passed from previous step's return
const targetPage = figma.root.children.find(p => p.name === targetName);
await figma.setCurrentPageAsync(targetPage);

const comp = figma.createComponent();
comp.name = "Card";
targetPage.appendChild(comp);
return { createdComponentId: comp.id };

Key Source Files and References

Understanding the implementation details requires referencing these specific files in the figma/mcp-server-guide repository:

• skills/figma-use/SKILL.md (lines 42‑46, 56‑60): Defines the use_figma skill and outlines Page Rules, including the requirement to use setCurrentPageAsync and patterns for iterating pages.
• skills/figma-use/references/plugin-api-patterns.md (lines 23‑30): Documents the Page Context behavior and the correct asynchronous API for switching pages.
• README.md: Provides general context on the MCP server architecture powering use_figma.

Summary

• Fresh context: Every use_figma call starts with figma.currentPage set to the first page.
• Async required: Use await figma.setCurrentPageAsync(page)—synchronous assignment throws an error.
• Iterate safely: Loop over figma.root.children and switch pages explicitly when working across the file.
• Atomic execution: Failed page switches roll back the entire script, preventing partial file modifications.
• Source authority: Page behavior is defined in SKILL.md and plugin-api-patterns.md within the figma/mcp-server-guide repository.

Frequently Asked Questions

Why does figma.currentPage reset to the first page on every call?

The headless runtime is instantiated fresh for each use_figma invocation to ensure script isolation and prevent state leakage between automated steps. This guarantees that each script runs against a known, clean state unless the file itself is modified.

What happens if I use figma.currentPage = page instead of setCurrentPageAsync?

The synchronous assignment throws a "Setting figma.currentPage is not supported" error. The use_figma runtime only supports the asynchronous figma.setCurrentPageAsync() method for changing page context.

How do I iterate through multiple pages in a single use_figma call?

Loop over figma.root.children and call await figma.setCurrentPageAsync(page) for each page before accessing its nodes. This loads the page content into the runtime context, allowing you to query or modify nodes on that specific page.

Is page state preserved between use_figma invocations?

No. Because each call runs in an isolated runtime instance, the current page selection and any in-memory variables are discarded after the script completes. You must explicitly switch pages at the start of every call that targets a non-default page.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}