New​

• DocumentNode.findWidgetNodesByWidgetId was previously undocumented, and has since been added to the documentation and type definitions.

APIs for dynamic page loading​

Over the past few months, Figma has been rolling out dynamic page loading, which allows documents to load pages on demand, rather than all at once. For backward compatibility, Figma loads all pages in the document before attempting to run an extension (a plugin or widget), which can sometimes result in a noticeable delay.

We're pleased to announce a new set of APIs that allow extensions to work safely with dynamic page loading, and avoid triggering the loading delay. Alongside these new APIs, we are deprecating several existing methods and properties. This will help to ensure that new extensions will be compatible with dynamic page loading by default.

To mark an extension as compatible with dynamic page loading, add "documentAccess": "dynamic-page" to manifest.json. Extensions with this manifest field will not encounter loading delays, but they'll be unable to access any of the deprecated methods and properties listed below. New extensions will include this manifest field by default.

To learn more about updating your extension, see our comprehensive migration guide. For TypeScript users, we've also provided an ESLint plugin that can help identify and automatically fix callsites that need to be updated.

Timeline​

As of February 21st, dynamic page loading APIs are generally available (GA). You can update existing extensions and create new extensions using the dynamic page loading APIs and the manifest field "documentAccess": "dynamic-page".

Starting in April, the manifest field "documentAccess": "dynamic-page" will be required for all widgets, and all new plugins.

Net-new methods​

• figma.loadAllPagesAsync()
• figma.variables.createVariableAliasByIdAsync()
• PageNode.loadAsync()

Deprecations and replacements​

Several methods and properties have been deprecated in favor of async replacements:

• Use figma.getFileThumbnailNodeAsync() instead of figma.getFileThumbnailNode().
• Use figma.getLocalEffectStylesAsync() instead of figma.getLocalEffectStyles().
• Use figma.getLocalGridStylesAsync() instead of figma.getLocalGridStyles().
• Use figma.getLocalPaintStylesAsync() instead of figma.getLocalPaintStyles().
• Use figma.getLocalTextStylesAsync() instead of figma.getLocalTextStyles().
• Use figma.getNodeByIdAsync() instead of figma.getNodeById().
• Use figma.getStyleByIdAsync() instead of figma.getStyleById().
• Use figma.variables.getLocalVariableCollectionsAsync() instead of figma.variables.getLocalVariableCollections().
• Use figma.variables.getLocalVariablesAsync() instead of figma.variables.getLocalVariables().
• Use figma.variables.getVariableByIdAsync() instead of figma.variables.getVariableById().
• Use figma.variables.getVariableCollectionByIdAsync() instead of figma.variables.getVariableCollectionById().
• Use setRangeFillStyleIdAsync() instead of setRangeFillStyleId().
• Use setRangeTextStyleIdAsync() instead of setRangeTextStyleId().

In some specific cases, reading node properties has been deprecated in favor of an async getter:

• Use ComponentNode.getInstancesAsync() instead of ComponentNode.instances.
• Use getStyleConsumersAsync() instead of the consumers.
• Use InstanceNode.getMainComponentAsync() instead of InstanceNode.mainComponent.

In some specific cases, assigning values directly to node properties has been deprecated in favor of an async setter:

• Use figma.setCurrentPageAsync() instead of assigning to figma.currentPage.
• Use setEffectStyleIdAsync() instead of assigning to effectStyleId.
• Use setFillStyleIdAsync() instead of assigning to backgroundStyleId.
• Use setFillStyleIdAsync() instead of assigning to fillStyleId.
• Use setGridStyleIdAsync() instead of assigning to gridStyleId.
• Use setReactionsAsync() instead of assigning to reactions.
• Use setStrokeStyleIdAsync() instead of assigning to strokeStyleId.
• Use setVectorNetworkAsync() instead of assigning to vectorNetwork.
• Use TextNode.setTextStyleIdAsync() instead of assigning to TextNode.textStyleId.

If an extension's manifest contains "documentAccess": "dynamic-page", accessing any of the deprecated items listed above will throw an exception.

Method/property usage changes​

If an extension's manifest contains "documentAccess": "dynamic-page", calling any of the following methods will throw an exception unless you first call figma.loadAllPagesAsync():

• DocumentNode.findAll()
• DocumentNode.findAllWithCriteria()
• DocumentNode.findOne()
• DocumentNode.findWidgetNodesByWidgetId()

For the methods listed below, passing a string ID is now deprecated in favor of passing objects that the IDs refer to. If an extension's manifest contains "documentAccess": "dynamic-page", passing an ID will throw an exception.

• figma.variables.createVariable() - Pass a VariableCollection object instead of a collection ID.
• clearExplicitVariableModeForCollection() (present on multiple node types) - Pass a VariableCollection object instead of a collection ID.
• setExplicitVariableModeForCollection() (present on multiple node types) - Pass a VariableCollection object instead of a collection ID.
• setBoundVariable() (present on multiple node types) - Pass a Variable object instead of a variable ID.

If an extension's manifest contains "documentAccess": "dynamic-page", some properties and methods of PageNode will throw an exception unless you explicitly load the page first using PageNode.loadAsync(). These include:

• PageNode.appendChild()

• PageNode.exportAsync

• PageNode.findAll()

• PageNode.findAllWithCriteria()

• PageNode.findChild()

• PageNode.findChildren()

• PageNode.findOne()

• PageNode.findWidgetNodesByWidgetId()

• PageNode.insertChild()

Changes to events​

• If an extension's manifest contains "documentAccess": "dynamic-page", the documentchange event will not be available unless you first call figma.loadAllPagesAsync().
• Where possible, prefer using the nodechange and stylechange events, which do not require triggering a full-document load.

New:

• Add a figma.createComponentFromNode function to create a component from an existing node, preserving all of its properties and children.

New:

• Measurements can be added to pin distances between nodes in Dev Mode. See Measurement.
• Private beta only: annotations can be set on nodes to leave notes and pin properties in Dev Mode. See Annotation. More details on the public beta release of these APIs will be announced soon.

• null is now supported for the variable field in setBoundVariableForPaint, setBoundVariableForEffect, and setBoundVariableForLayoutGrid. Passing in null will detach the bound variables.

• For plugins that can run in VSCode, we now recommend replacing alert() and confirm() dialogs in the plugin UI with custom UI, since VS Code blocks native dialogs. The Working in Dev Mode page is updated accordingly.

Updates:

• Plugins can now view and set explicit modes for each variable collection on PageNodes.
• The BaseStyle type is now defined as a union of all possible derived style interfaces, such as PaintStyle and GridStyle. This allows you to use type narrowing on the the type property to go from an instance of BaseStyle to a child style type.
• Updated the color token values in the CSS Variables and Theming page for the “Figma Design: Light” and “Figma Design: Dark” modes to reflect recent formatting changes to token values injected into the plugin iframe (rgba() values were changed to #rrggbbaa format).
• Variables can now be bound to Effect and Layout Grid styles. On a selection, variables bound to a given style are populated in boundVariables keyed by style type (effects or layoutGrids).

This update includes changes to the Variables API to support binding variables to effects, layout grids, stroke weights, and layer opacity. We are also releasing support to run Dev Mode plugins in the Figma for VS Code extension.

Changes to the Variables API:

• FLOAT and COLOR variables can be bound to Effects via the setBoundVariablesForEffect() helper.
• FLOAT variables can be bound to LayoutGrids via the setBoundVariablesForLayoutGrid() helper.
• New VariableBindableNodeField types, FLOAT variables can be bound to layer opacity, stroke weights, and individual stroke weights.
• New VariableScope types for scoping variables to layer opacity, stroke weights, and effects.

Dev Mode plugins can now run in the Figma for VS Code extension with some minor manifest and code changes:

• manifest.json changes - added new vscode capability
• figma.vscode - this new namespace allows the plugin to determine whether it's running in the VS Code Extension or not.
• figma.openExternal - this API enables opening a URL externally and is necessary to use in the VS Code Extension.
• See all of the details in Dev Mode Plugins in VS Code

Fixes:

• fillGeometry and strokeGeometry properties are correctly marked as readonly

New:

• We are introducing NEGATE as a Prototyping ExpressionFunction type!

New:

• Plugins are now able to explicitly unbind variables from nodes. See setBoundVariable.
• variableIds are now returned in a similar order to the Figma Design UI. See VariableCollection#variableIds
• Adds ability to set and query pluginData on Variable and Variable Collection nodes.
• Adds textRangeFills to the boundVariables structure. This will be populated on text nodes which have color variables bound to substrings.
• Plugins/widgets that touch straight connectors and set endpoint magnets other than CENTER or NONE will now error in development. Please update your code to use the CENTER or NONE magnets for straight connectors before 2024. See Version 1, Update 79 for more details.
• Added support for the devStatus field on Frames, Components, Component Sets, and Instances.

The Plugin API runtime has been updated to ensure proper usage of figma.showUI.

It is unsafe to call figma.showUI within an event handler for the figma.codegen.on("generate") event. In development, figma.showUI will now throw an error when called as a result of a figma.codegen.on("generate")

If you need to trigger code inside an iframe as the result of a generate callback, you should instead move the call to showUI outside of the event handler and use figma.ui.postMessage to communicate with the iframe from within the callback. This will ensure that your plugin can to handle concurrent generate events. Here's a code example for how to do this.