Skip to main content

figma

These are methods and properties available on the figma global object.

General

apiVersion: '1.0.0' [readonly]

The version of the Figma API this plugin is running on, as defined in your manifest.json in the "api" field.


fileKey: string | undefined [readonly]

The file key of the current file this plugin is running on. Only private plugins have access to this. To enable this behavior, you need to specify enablePrivatePluginApi in your manifest.json.


command: string [readonly]

The currently executing command from the manifest.json file. It is the command string in the ManifestMenuItem (more details in the manifest guide). If the plugin does not have any menu item, this property is undefined.


pluginId?: string [readonly]

The value specified in the manifest.json "id" field. This only exists for Plugins.


widgetId?: string [readonly]

Similar to figma.pluginId but for widgets. The value specified in the manifest.json "id" field. This only exists for Widgets.


editorType: 'figma' | 'figjam' [readonly]

The current editor type this plugin is running in. See also Setting editor type.


skipInvisibleInstanceChildren: boolean

Defaults to false. When enabled, causes all node properties and methods to skip over invisible nodes (and their descendants) inside instances. This makes operations like document traversal much faster.

View more →

currentPage: PageNode

The page that the user currently viewing. You can set this value to a PageNode to switch pages.


root: DocumentNode [readonly]

The root of the entire Figma document. This node is used to access other pages. Each child is a PageNode.


showUI(html: string, options?: ShowUIOptions): void

Enables you to render UI to interact with the user, or simply to access browser APIs. This function creates a modal dialog with an <iframe> containing the HTML markup in the html argument.

View more →

ui: UIAPI [readonly]

This property contains methods used to modify and communicate with the UI created via figma.showUI(...).

Read more in the UI section.


timer?: TimerAPI [readonly]

info

This API is only available in FigJam

This property contains methods used to read, set, and modify the built in FigJam timer.

Read more in the timer section.


viewport: ViewportAPI [readonly]

This property contains methods used to read and set the viewport, the user-visible area of the current page.

Read more in the viewport section.


clientStorage: ClientStorageAPI [readonly]

This property contains methods to store persistent data on the user's local machine.

Read more in the client storage section.


currentUser: User | null [readonly]

info

currentuser must be specified in the permissions array in manifest.json to access this property.

This property contains details about the current user.


activeUsers: ActiveUser[] [readonly]

info

This API is only available in FigJam.

activeusers must be specified in the permissions array in manifest.json to access this property.

This property contains details about the active users in the file. figma.activeUsers[0] will match figma.currentUser for the id, name, photoUrl, color, and sessionId properties.


closePlugin(message?: string): void

Closes the plugin. You should always call this function once your plugin is done running. When called, any UI that's open will be closed and any setTimeout or setInterval timers will be cancelled.

View more →

on(type: ArgFreeEventType, callback: () => void): void

on(type: 'run', callback: (event: RunEvent) => void): void

on(type: 'drop', callback: (event: DropEvent) => boolean): void

Registers an callback that will be called when an event happens in the editor. Current supported events are:

  • The selection on the current page changed.
  • The current page changed.
  • An object from outside Figma is dropped onto the canvas
  • The plugin has started running.
  • The plugin closed.
  • The plugin has started running.
  • The timer has started running.
  • The timer has paused.
  • The timer has stopped.
  • The timer is done.
  • The timer has resumed.
View more →

once(type: ArgFreeEventType, callback: () => void): void

once(type: 'run', callback: (event: RunEvent) => void): void

once(type: 'drop', callback: (event: DropEvent) => boolean): void

Same as figma.on, but the callback will only be called once, the first time the specified event happens.


off(type: ArgFreeEventType, callback: () => void): void

off(type: 'run', callback: (event: RunEvent) => void): void

off(type: 'drop', callback: (event: DropEvent) => boolean): void

Removes a callback added with figma.on or figma.once.

View more →

notify(message: string, options?: NotificationOptions): NotificationHandler

Shows a notification on the bottom of the screen.

View more →

commitUndo(): void

Commits actions to undo history. This does not trigger an undo.

View more →

triggerUndo(): void

Triggers an undo action. Reverts to the last commitUndo() state.


saveVersionHistoryAsync(title: string, description?: string): Promise<VersionHistoryResult>

Saves a new version of the file and adds it to the version history of the file. Returns the new version id.

View more →

Nodes

This section contains to get or create new nodes.

getNodeById(id: string): BaseNode | null

Finds a node by its id in the current document. Every node has an id property, which is unique within the document. If the id is invalid, or the node cannot be found (e.g. removed), returns null.


createRectangle(): RectangleNode

Creates a new rectangle. The behavior is similar to using the R shortcut followed by a click.

View more →

createLine(): LineNode

Creates a new line.

View more →

createEllipse(): EllipseNode

Creates a new ellipse. The behavior is similar to using the O shortcut followed by a click.

View more →

createPolygon(): PolygonNode

Creates a new polygon (defaults to a triangle).

View more →

createStar(): StarNode

Creates a new star.

View more →

createVector(): VectorNode

Creates a new, empty vector network with no vertices.

View more →

createText(): TextNode

Creates a new, empty text node.

View more →

createFrame(): FrameNode

Creates a new frame. The behavior is similar to using the F shortcut followed by a click.

View more →

createComponent(): ComponentNode

info

This API is only available in Figma Design

Creates a new, empty component.

View more →

createBooleanOperation(): BooleanOperationNode

[DEPRECATED]. Use figma.union, figma.subtract, figma.intersect, figma.exclude instead.

View more →

createPage(): PageNode

info

This API is only available in Figma Design

Creates a new page, appended to the document's list of children.

View more →

createSlice(): SliceNode

Creates a new slice object.

View more →

createSticky(): StickyNode

info

This API is only available in FigJam

Creates a new sticky. The behavior is similar to using the S shortcut followed by a click.

View more →

createShapeWithText(): ShapeWithTextNode

info

This API is only available in FigJam

Creates a new shape with text.

View more →

createConnector(): ConnectorNode

info

This API is only available in FigJam

Creates a new connector. The behavior is similar to using the Shift-C shortcut followed by a click.

View more →

createCodeBlock(): CodeBlockNode

info

This API is only available in FigJam

Creates a new code block.


createSection(): SectionNode

info

This API is only available in FigJam

Creates a new section


createLinkPreviewAsync(url: string): Promise<EmbedNode | LinkUnfurlNode>

info

This API is only available in FigJam

Resolves link metadata from a URL, and inserts either an embed or a unfurled preview of the link into the document An embed will be inserted if the URL is a valid OEmbed provider (has a <link type="application/json+oembed" ... /> tag). The returned <iframe> source will be converted into an EmbedNode.

Otherwise, the title, description, thumbnail, and favicon will be parsed from the HTML markup of the URL using standard og or twitter meta tags. This information will be converted into a LinkUnfurlNode.

View more →

createGif(hash: string): MediaNode

info

This API is only available in FigJam

Creates a new GIF with the given Image hash.

View more →

createNodeFromSvg(svg: string): FrameNode

Creates a new node from an SVG string. This is equivalent to the SVG import feature in the editor. See the official documentation on SVG paths for more details.


combineAsVariants(nodes: ReadonlyArray<ComponentNode>, parent: BaseNode & ChildrenMixin, index?: number): ComponentSetNode

info

This API is only available in Figma Design

Creates a new ComponentSetNode by combining all the nodes in nodes, which should all have type ComponentNode.

View more →

group(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): GroupNode

Creates new group containing all the nodes in nodes. There is no createGroup function -- use this instead. Group nodes have many quirks, like auto-resizing, that you can read about in the FrameNode section.

View more →

union(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

Creates a new BooleanOperationNode using the UNION operation using the contents of nodes. The arguments to union are the same as in figma.group.


subtract(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

Creates a new BooleanOperationNode using the SUBTRACT operation using the contents of nodes. The arguments to union are the same as in figma.subtract.


intersect(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

Creates a new BooleanOperationNode using the INTERSECT operation using the contents of nodes. The arguments to union are the same as in figma.intersect.


exclude(nodes: ReadonlyArray<BaseNode>, parent: BaseNode & ChildrenMixin, index?: number): BooleanOperationNode

Creates a new BooleanOperationNode using the EXCLUDE operation using the contents of nodes. The arguments to union are the same as in figma.exclude.


flatten(nodes: ReadonlyArray<BaseNode>, parent?: BaseNode & ChildrenMixin, index?: number): VectorNode

Flattens every node in nodes into a new vector network.

View more →

ungroup(node: SceneNode & ChildrenMixin): Array<SceneNode>

Ungroups the given node, moving all of node's children into node's parent and removing node. Returns an array of nodes that were children of node.

View more →

Styles

These are APIs available to create new styles and retrieve existing ones in the current document. The newly created styles are local to the current document and do not contain default properties (except for TextStyle).

getStyleById(id: string): BaseStyle | null

Finds a style by its id in the current document. If not found, returns null.


createPaintStyle(): PaintStyle

info

This API is only available in Figma Design

Creates a new Paint style. This might be referred to as a Color style, or Fill style more colloquially. However, since this type of style may contain images, and may be used for backgrounds, strokes, and fills, it is called a Paint.


createTextStyle(): TextStyle

info

This API is only available in Figma Design

Creates a new Text style. By default, the text style has the Figma default text properties (font family Inter Regular, font size 12).


createEffectStyle(): EffectStyle

info

This API is only available in Figma Design

Creates a new Effect style.


createGridStyle(): GridStyle

info

This API is only available in Figma Design

Creates a new Grid style.


The APIs below allow access to local styles, which are returned in the same order as displayed in the UI. Only local styles are returned, not the ones from the team library.

getLocalPaintStyles(): PaintStyle[]

Returns the list of local paint styles.


getLocalTextStyles(): TextStyle[]

Returns the list of local text styles.


getLocalEffectStyles(): EffectStyle[]

Returns the list of local effect styles.


getLocalGridStyles(): GridStyle[]

Returns the list of local grid styles.


moveLocalPaintStyleAfter(targetNode: PaintStyle, reference: PaintStyle | null): void

info

This API is only available in Figma Design

Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local paint styles.


moveLocalTextStyleAfter(targetNode: TextStyle, reference: TextStyle | null): void

info

This API is only available in Figma Design

Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local text styles.


moveLocalEffectStyleAfter(targetNode: EffectStyle, reference: EffectStyle | null): void

info

This API is only available in Figma Design

Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local effect styles.


moveLocalGridStyleAfter(targetNode: GridStyle, reference: GridStyle | null): void

info

This API is only available in Figma Design

Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local grid styles.


moveLocalPaintFolderAfter(targetFolder: string, reference: string | null): void

info

This API is only available in Figma Design

Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain paint styles. When referring to nested folders, the full delimited folder name must be used. See the BaseStyle section for more info.


moveLocalTextFolderAfter(targetFolder: string, reference: string | null): void

info

This API is only available in Figma Design

Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain text styles. When referring to nested folders, the full delimited folder name must be used. See the BaseStyle section for more info.


moveLocalEffectFolderAfter(targetFolder: string, reference: string | null): void

info

This API is only available in Figma Design

Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain effect styles. When referring to nested folders, the full delimited folder name must be used. See the BaseStyle section for more info.


moveLocalGridFolderAfter(targetFolder: string, reference: string | null): void

info

This API is only available in Figma Design

Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain grid styles. When referring to nested folders, the full delimited folder name must be used. See the BaseStyle section for more info.


Team Library

These APIs allow you to get a component or style from the team library. This requires you to have a key, which you can obtain from component.key or style.key either while the plugin is running or obtaining it via a test plugin, then hardcoding it in your actual plugin.

importComponentByKeyAsync(key: string): Promise<ComponentNode>

Loads a component node from the team library. Promise is rejected if there is no published component with that key or if the request fails.


importComponentSetByKeyAsync(key: string): Promise<ComponentSetNode>

Loads a component set node from the team library. Promise is rejected if there is no published component set with that key or if the request fails.


importStyleByKeyAsync(key: string): Promise<BaseStyle>

Loads a style from the team library. Promise is rejected if there is no style with that key or if the request fails.


Other

listAvailableFontsAsync(): Promise<Font[]>

Returns the lists of currently available fonts. This should be the same list as the one you'd see if you manually used the font picker.


loadFontAsync(fontName: FontName): Promise<void>

Makes a font available in the plugin for use when creating and modifying text. Calling this function is necessary to modify any property of a text node that may cause the rendered text to change, including .characters, .fontSize, .fontName, etc.

You can either pass in a hardcoded font, a font loaded via listAvailableFontsAsync, or the font stored on an existing text node.

Read more about how to work with fonts, when to load them, and how to load them in the Working with Text page.

View more →

createImage(data: Uint8Array): Image

Creates an Image object from the raw bytes of a file content. Note that Image objects are not nodes. They are handles to images stored by Figma. Frame backgrounds, or fills of shapes (e.g. a rectangle) may contain images. Example: how to work with images.

View more →

getImageByHash(hash: string): Image | null

This gets the corresponding Image object for a given image hash, which can then be used to obtain the bytes of the image. This hash is found in a node's fill property as part of the ImagePaint object. If there is no image with this hash, returns null.


mixed: unique symbol [readonly]

This a constant value that some node properties return when they are a mix of multiple values. An example might be font size: a single text node can use multiple different font sizes for different character ranges. For those properties, you should always compare against figma.mixed.

View more →

base64Encode(data: Uint8Array): string

Returns a base64-encoded string from the Uint8Array data.


base64Decode(data: string): Uint8Array

Decodes and returns a Uint8Array from the base64-encoded string data.


getFileThumbnailNode(): FrameNode | ComponentNode | ComponentSetNode | null

Gets the node that is currently being used for file thumbnail, or null if the default thumbnail is used.


setFileThumbnailNodeAsync(node: FrameNode | ComponentNode | ComponentSetNode | null): Promise<void>

Set node to be the thumbnail for the file. If node is null, then use the default thumbnail.