switch_page
Switch to a specific Figma page using its unique page ID. Use without arguments to retrieve the full list of pages.
Instructions
Navigate between pages in the Figma file. ID-driven — names are not addressable (they can collide and change).
Two modes:
switch_page({}) → return the page roster only, no switch (use to discover IDs on first call)
switch_page({pageId: "1:23"}) → switch and return the updated state + roster
Pages are top-level containers under the file root. Most read/write operations default to figma.currentPage. Call this when you need to operate on nodes that live on a different page than the current one.
Returns:
currentPageId, currentPageName — the now-current page (always present)
pages — full roster [{id, name}] of every page in the file (always present)
previousPageId, previousPageName — what you switched from (only when an actual switch happened)
unchanged — true if target was already current
Typical flow:
switch_page({}) // get IDs
switch_page({pageId: ""}) // switch
When to call:
User mentions content on a different page than the current one
A previous tool reported a node ID is on a non-current page
You need to inspect/modify nodes outside the active page
Don't call:
For nodes already on the current page — figma.currentPage is the default scope, this would just waste an iteration
Repeatedly to "explore" — every call returns the full pages roster, cache it
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageId | No | Target page ID (e.g., "0:1"). Omit to just fetch the page roster without switching. |