# Page Switching and Context Management in use_figma: A Complete Guide

> Master page switching and context management in use_figma. Learn how to explicitly set current pages and navigate your designs for efficient workflow.

- Repository: [Figma/mcp-server-guide](https://github.com/figma/mcp-server-guide)
- Tags: how-to-guide
- Published: 2026-03-30

---

**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](https://github.com/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/skills/figma-use/references/plugin-api-patterns.md) (lines 23‑30), you must use the asynchronous API:

```js
// 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:

```js
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:

```js
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:

```js
// 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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/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`](https://github.com/figma/mcp-server-guide/blob/main/SKILL.md) and [`plugin-api-patterns.md`](https://github.com/figma/mcp-server-guide/blob/main/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.