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 and Figma-owned resources (such as the Jira and Asana widgets) 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.
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.
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.
parameters: ParametersAPI [readonly]
This property contains methods to handle user inputs when a plugin is launched in query mode. See Accepting Parameters as Input for more details.
payments?: PaymentsAPI [readonly]
info
payments must be specified in the permissions array in manifest.json to access this property.
This property contains methods for plugins that require payment.
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.
textreview?: TextReviewAPI [readonly]
info
textreview must be specified in the capabilities array in manifest.json to access this property.
This property contains methods that enable text review features in your plugin.
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.
on(type: ArgFreeEventType, callback: () => void): void
on(type: 'run', callback: (event: RunEvent) => void): void
on(type: 'drop', callback: (event: DropEvent) => boolean): void
on(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void
on(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): 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.
- The document has 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.
once(type: ArgFreeEventType, callback: () => void): void
once(type: 'run', callback: (event: RunEvent) => void): void
once(type: 'drop', callback: (event: DropEvent) => boolean): void
once(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void
once(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): 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
off(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void
off(type: 'textreview', callback: (event: TextReviewEvent) => Promise<TextReviewRange[]> | TextReviewRange[]): void
Removes a callback added with figma.on or figma.once.
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.
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.
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.
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.
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.
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.
createCodeBlock(): CodeBlockNode
info
This API is only available in FigJam
Creates a new code block.
createSection(): SectionNode
Creates a new section
createTable(numRows?: number, numColumns?: number): TableNode
info
This API is only available in FigJam
Creates a new table.
View more →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.
createGif(hash: string): MediaNode
info
This API is only available in FigJam
Creates a new GIF with the given Image hash.
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.
createNodeFromJSXAsync(jsx: any): Promise<SceneNode>
This API creates a new node using the JSX API used by widgets.
View more →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.
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.
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.
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. You can get a key by calling component.key or style.key while a plugin is running.
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 →hasMissingFont: boolean [readonly]
Returns true if the document contains text with missing fonts.
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.
createImageAsync(src: string): Promise<Image>
Creates an Image object from a src URL. 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.
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.
createVideoAsync(data: Uint8Array): Promise<Video>
Creates a Video object from the raw bytes of a file content. Like Image objects, Video objects are not nodes. They are handles to images stored by Figma. Frame backgrounds, or fills of shapes (e.g. a rectangle) may contain videos.
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.
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.