Utilities

Overview#

@create-figma-plugin/utilities is a library of utility functions for common Figma/FigJam plugin/widget operations. It is meant to complement the Figma/FigJam plugin API and widget API.

To install:

$ npm install @create-figma-plugin/utilities

When used with the build-figma-plugin CLI, only the functions explicitly imported by your plugin/widget will be included in the generated JavaScript bundle(s).

Color#

import {
  convertHexColorToRgbColor,
  convertNamedColorToHexColor,
  convertRgbColorToHexColor,
  isValidHexColor
} from '@create-figma-plugin/utilities'

convertHexColorToRgbColor(hexColor)#

Converts the given hexColor (eg. 000000) to RGB format (eg. { r: 0, g: 0, b: 0 }). Each value in the returned RGB plain object is between 0 and 1.

Parameters

• hexColor (string)

Return type

Returns an RGB plain object, else null if hexColor was invalid.

null | RGB

convertNamedColorToHexColor(namedColor)#

Converts the given namedColor (eg. black) to hexadecimal format (eg. 000000).

Parameters

• namedColor (string)

Return type

Returns a hexadecimal color as an uppercase string, else null if namedColor was invalid.

null | string

convertRgbColorToHexColor(rgbColor)#

Converts the given rgbColor (eg. { r: 0, g: 0, b: 0 }) to hexadecimal format (eg. 000000). Each value in the given RGB plain object must be between 0 and 1.

Parameters

• rgbColor (RGB)

Return type

Returns a hexadecimal color as an uppercase string, else null if rgbColor was invalid.

null | string

isValidHexColor(hexColor)#

Returns true if hexColor is a valid hexadecimal color.

Parameters

• hexColor (string)

Return type

boolean

Events#

import {
  emit,
  on,
  once
} from '@create-figma-plugin/utilities'

emit<Handler>(name, ...args)#

Calling emit in the main context invokes the event handler for the matching event name in your UI. Correspondingly, calling emit in your UI invokes the event handler for the matching event name in the main context.

All args passed after name will be directly applied on the event handler.

See the recipe for passing data between the main and UI contexts.

Type parameters

• Handler (EventHandler)

Parameters

• name (Handler['name'])
• args (Parameters<Handler['handler']>)

Return type

void

on<Handler>(name, handler)#

Registers an event handler for the given event name.

Type parameters

• Handler (EventHandler)

Parameters

• name (Handler['name'])
• handler (Handler['handler'])

Return type

Returns a function for deregistering the handler.

() => void

once<Handler>(name, handler)#

Registers an event handler that will run at most once for the given event name.

Type parameters

• Handler (EventHandler)

Parameters

• name (Handler['name'])
• handler (Handler['handler'])

Return type

Returns a function for deregistering the handler.

() => void

Function#

import { ensureMinimumTime } from '@create-figma-plugin/utilities'

ensureMinimumTime<S, T>(minimumTime, callback)#

Creates an async function that will invoke the given callback and run for at least minimumTime (in milliseconds).

Type parameters

• S
• T (any[])

Parameters

• minimumTime (number)
• callback ((...args: T) => Promise<S>)

Return type

(...args: T) => Promise<S>

Image#

import {
  createCanvasElementFromBlobAsync,
  createCanvasElementFromBytesAsync,
  createCanvasElementFromImageElement,
  createImageElementFromBlobAsync,
  createImageElementFromBytesAsync,
  createImagePaint,
  readBytesFromCanvasElementAsync
} from '@create-figma-plugin/utilities'

createCanvasElementFromBlobAsync(blob)#

Creates an HTMLCanvasElement from a blob representing an image.

Parameters

• blob (Blob)

Return type

Promise<HTMLCanvasElement>

createCanvasElementFromBytesAsync(bytes)#

Creates an HTMLCanvasElement from the bytes of an image.

Parameters

• bytes (Uint8Array)

Return type

Promise<HTMLCanvasElement>

createCanvasElementFromImageElement(imageElement)#

Creates an HTMLCanvasElement from an HTMLImageElement.

Parameters

• imageElement (HTMLImageElement)

Return type

Promise<HTMLCanvasElement>

createImageElementFromBlobAsync(blob)#

Creates an HTMLImageElement from a blob representing an image.

Parameters

• blob (Blob)

Return type

Promise<HTMLImageElement>

createImageElementFromBytesAsync(bytes)#

Creates an HTMLImageElement from the bytes of an image.

Parameters

• bytes (Uint8Array)

Return type

Promise<HTMLImageElement>

createImagePaint(bytes)#

Creates an ImagePaint object from the bytes of an image.

Parameters

• bytes (Uint8Array)

Return type

ImagePaint

readBytesFromCanvasElementAsync(canvasElement)#

Read the bytes off an HTMLCanvasElement.

Parameters

• canvasElement (HTMLCanvasElement)

Return type

Promise<Uint8Array>

Monetization#

import {
  getDocumentUseCount,
  getTotalUseCountAsync,
  incrementDocumentUseCount,
  incrementTotalUseCountAsync,
  resetDocumentUseCount,
  resetTotalUseCountAsync,
  validateGumroadLicenseKeyMainAsync,
  validateGumroadLicenseKeyUiAsync
} from '@create-figma-plugin/utilities'

getDocumentUseCount([key])#

Returns the plugin’s use count for the current document.

Parameters

• key (string) – Optional. The key on the current document on which to store the use count. Defaults to 'documentUseCount'.

Return type

number

getTotalUseCountAsync([key])#

Returns the plugin’s total use count.

Parameters

• key (string) – Optional. The key in figma.clientStorage on which to store the use count. Defaults to 'totalUseCount'.

Return type

Promise<number>

incrementDocumentUseCount([key])#

Increments the plugin’s use count for the current document.

Parameters

• key (string) – Optional. The key on the current document on which to store the use count. Defaults to 'documentUseCount'.

Return type

Returns the plugin’s new use count for the current document.

number

incrementTotalUseCountAsync([key])#

Increments the plugin’s total use count.

Parameters

• key (string) – Optional. The key in figma.clientStorage on which to store the use count. Defaults to 'totalUseCount'.

Return type

Returns the plugin’s new total use count.

Promise<number>

resetDocumentUseCount([key])#

Resets the plugin’s use count for the current document to 0.

Parameters

• key (string) – Optional. The key on the current document on which to store the use count. Defaults to 'documentUseCount'.

Return type

void

resetTotalUseCountAsync([key])#

Resets the plugin’s total use count to 0.

Parameters

• key (string) – Optional. The key in figma.clientStorage on which to store the use count. Defaults to 'totalUseCount'.

Return type

Promise<void>

validateGumroadLicenseKeyMainAsync(options)#

Validates the given Gumroad license key for the product with the given productPermalink in the main context.

Parameters

• options (object)
  • incrementUseCount (boolean) – Optional. Set to true to increment the license key use count tracked by Gumroad. Defaults to false.
  • licenseKey (string) – The Gumroad license key to validate.
  • productPermalink (string) – The Gumroad “product permalink”. If the Gumroad product URL is https://gumroad.com/l/QGMY, then the product permalink is 'QGMY'.

Return type

Returns a LicenseKeyValidationResult object.

Promise<LicenseKeyValidationResult>

validateGumroadLicenseKeyUiAsync(options)#

Validates the given Gumroad license key for the product with the given productPermalink in the UI context.

Parameters

• options (object)
  • incrementUseCount (boolean) – Optional. Set to true to increment the license key use count tracked by Gumroad. Defaults to false.
  • licenseKey (string) – The Gumroad license key to validate.
  • productPermalink (string) – The Gumroad “product permalink”. If the Gumroad product URL is https://gumroad.com/l/QGMY, then the product permalink is 'QGMY'.

Return type

Returns a LicenseKeyValidationResult object.

Promise<LicenseKeyValidationResult>

Node#

import {
  areSiblingNodes,
  collapseLayer,
  computeBoundingBox,
  computeMaximumBounds,
  computeSiblingNodes,
  deduplicateNodes,
  getAbsolutePosition,
  getDocumentComponents,
  getNodeIndexPath,
  getParentNode,
  getSceneNodeById,
  getSelectedNodesOrAllNodes,
  insertAfterNode,
  insertBeforeNode,
  isLocked,
  isVisible,
  isWithinInstanceNode,
  loadFontsAsync,
  setAbsolutePosition,
  setRelaunchButton,
  sortNodesByCanonicalOrder,
  sortNodesByName,
  traverseNode,
  traverseNodeAsync,
  unsetRelaunchButton,
  updateNodesSortOrder
} from '@create-figma-plugin/utilities'

areSiblingNodes(nodes)#

Checks if all nodes in nodes are sibling nodes.

Parameters

• nodes (Array<SceneNode>)

Return type

Returns true if all nodes in nodes are sibling nodes, else false.

boolean

collapseLayer(node)#

Collapses node and all its child nodes in the layer list.

Parameters

• node (SceneNode)

Return type

Returns true if at least one layer in the layer list was collapsed by the function, else false.

boolean

computeBoundingBox(node)#

Computes the coordinates (x, y) and dimensions (width, height) of the smallest bounding box that contains the given node. (Does not account for strokes or effects that could extend beyond the node’s bounding box.)

Parameters

• node (SceneNode)

Return type

Returns the bounding box as a Rect.

Rect

computeMaximumBounds(nodes)#

Computes the absolute coordinates of the top-left and bottom-right corners of the smallest bounding box that contains the given nodes. (Does not account for strokes or effects that could extend beyond the nodes’ bounding box.)

Parameters

• nodes (Array<SceneNode>)

Return type

Returns an array of two Vector objects, one for the top-left corner and another for the bottom-right corner.

[Vector, Vector]

computeSiblingNodes<Node>(nodes)#

Splits nodes into groups of sibling nodes.

Type parameters

• Node (SceneNode)

Parameters

• nodes (Array<Node>)

Return type

Returns an array of array of sibling SceneNode objects.

Array<Array<Node>>

deduplicateNodes<Node>(nodes)#

Returns the result of deduplicating the nodes in nodes. Does not modify the original nodes array.

Type parameters

• Node (SceneNode)

Parameters

• nodes (Array<Node>)

Return type

Returns a new array of unique SceneNode objects.

Array<Node>

getAbsolutePosition(node)#

Returns the x and y position of the given node relative to the page.

Parameters

• node (SceneNode)

Return type

Returns a Vector.

Vector

getDocumentComponents()#

Returns all the local Components in the current document.

Return type

Array<ComponentNode>

getNodeIndexPath(node)#

Gets the index path to the node.

Parameters

• node (SceneNode)

Return type

Returns an array representing the index path to the given node, starting from figma.root

Array<number>

getParentNode(node)#

Returns the parent node of the given node.

Parameters

• node (BaseNode)

Return type

Throws an error if node.parent is null, else returns node.parent.

BaseNode & ChildrenMixin

getSceneNodeById<Node>(id)#

Returns the SceneNode in the current document with the given id. This is a convenience function that wraps the figma.getNodeById function.

Type parameters

• Node (SceneNode)

Parameters

• id (string)

Return type

Throws an error if no SceneNode with the given id exists, else returns the node cast to the specified Node type parameter.

Node

getSelectedNodesOrAllNodes()#

Returns the selected nodes, or all the top-level nodes on the current page if no nodes are selected.

Return type

Array<SceneNode>

insertAfterNode(node, referenceNode)#

Inserts node after the referenceNode in the layer list.

Parameters

• node (SceneNode)
• referenceNode (SceneNode)

Return type

void

insertBeforeNode(node, referenceNode)#

Inserts node before the referenceNode in the layer list.

Parameters

• node (SceneNode)
• referenceNode (SceneNode)

Return type

void

isLocked(node)#

Checks if the given node is locked.

Parameters

• node (SceneNode)

Return type

Returns true if the node or one of its parent nodes is locked, else false.

boolean

isVisible(node)#

Checks if the given node is visible.

Parameters

• node (SceneNode)

Return type

Returns true if the node and all its parent nodes are visible, else false.

boolean

isWithinInstanceNode(node)#

Checks if the given node is within an Instance node.

Parameters

• node (SceneNode)

Return type

Returns true if the node is within an Instance node, else false.

boolean

loadFontsAsync(nodes)#

Loads the fonts used in all the text nodes within the nodes array. This function must be called before modifying any property of a text node that may cause the rendered text to change.

Parameters

• nodes (Array<SceneNode>)

Return type

Promise<void>

setAbsolutePosition(node, vector)#

Moves the node to the given x and y position relative to the page. At least one of x or y of vector must be specified.

Parameters

• node (SceneNode)
• vector (Partial<Vector>)

Return type

void

setRelaunchButton(node, relaunchButtonId [, options])#

Sets a relaunch button on node for the command with the given relaunchButtonId as configured under the "relaunchButtons" key in package.json. Any relaunch buttons set previously will be retained.

See the recipe for configuring relaunch buttons.

Parameters

• node (BaseNode)
• relaunchButtonId (string)
• options (object) – Optional.
  • description (string) – The text to display below the relaunch button in the Figma UI.

Return type

void

sortNodesByCanonicalOrder<Node>(siblingNodes)#

Returns the result of sorting the nodes in siblingNodes by their layer list order. Does not modify the original siblingNodes array.

Type parameters

• Node (SceneNode)

Parameters

• siblingNodes (Array<Node>)

Return type

Returns a new array of SceneNode objects.

Array<Node>

sortNodesByName<Node>(nodes)#

Returns the result of sorting nodes in alphabetical order. Does not modify the original nodes array.

Type parameters

• Node (SceneNode)

Parameters

• nodes (Array<Node>)

Return type

Returns a new array of SceneNode objects.

Array<Node>

traverseNode(node, processNode [, stopTraversal])#

Traverses node and its child nodes recursively in a depth-first manner, passing each node to the specified processNode callback.

Each node is also passed to a stopTraversal function. If you return true in stopTraversal for a particular node, then its child nodes will not be traversed.

Parameters

• node (SceneNode)
• processNode ((node: SceneNode) => void)
• stopTraversal ((node: SceneNode) => boolean) – Optional.

Return type

void

traverseNodeAsync(node, processNodeAsync [, stopTraversalAsync])#

An async version of traverseNode, in which both callbacks are async.

Parameters

• node (SceneNode)
• processNodeAsync ((node: SceneNode) => Promise<void>)
• stopTraversalAsync ((node: SceneNode) => Promise<boolean>) – Optional.

Return type

Promise<void>

unsetRelaunchButton(node [, relaunchButtonId])#

Unsets the relaunch button on node for the command with the given relaunchButtonId. If relaunchButtonId is not specified, unsets all relaunch buttons on node.

Parameters

• node (BaseNode)
• relaunchButtonId (string) – Optional.

Return type

void

updateNodesSortOrder(siblingNodes)#

Updates the layer list sort order to follow the sort order of the nodes in the siblingNodes array. Does not modify the original siblingNodes array.

Parameters

• siblingNodes (Array<SceneNode>)

Return type

Returns true if the layer list sort order was changed by the function, else false.

boolean

Number#

import {
  evaluateNumericExpression,
  isValidNumericInput
} from '@create-figma-plugin/utilities'

evaluateNumericExpression(value)#

Evaluates the given numeric expression.

Parameters

• value (string)

Return type

Returns the result of evaluating the given numeric expression, else null for an invalid expression.

null | number

isValidNumericInput(value [, options])#

Checks if value is a numeric expression, as input by a user. “Partial” inputs are considered valid.

Parameters

• value (string)
• options (object) – Optional.
  • integersOnly (boolean) – Set to true to check that the expression contains only integers. Defaults to false.

Return type

Returns true if value is a valid numeric expression, else false.

boolean

Object#

import {
  cloneObject,
  compareObjects,
  compareStringArrays,
  deduplicateArray,
  extractAttributes
} from '@create-figma-plugin/utilities'

cloneObject<T>(object)#

Creates a deep copy of the given object.

Type parameters

• T

Parameters

• object (T)

Return type

T

compareObjects(a, b)#

Performs a deep equality comparison of objects a and b.

Parameters

• a (any)
• b (any)

Return type

Returns true if a and b are the same, else false.

boolean

compareStringArrays(a, b)#

Compares the string arrays a and b.

Parameters

• a (Array<string>)
• b (Array<string>)

Return type

Returns true if a and b are the same, else false.

boolean

deduplicateArray<T>(array)#

Returns the result of deduplicating the given array. Does not modify the original array.

Type parameters

• T (boolean | number | string)

Parameters

• array (Array<T>)

Return type

Returns a new array with unique values.

Array<T>

extractAttributes<PlainObject, Key>(array, attributes)#

Extracts the specified list of attributes from the given array of plain objects.

Type parameters

• PlainObject
• Key (keyof PlainObject)

Parameters

• array (Array<PlainObject>)
• attributes (Key[])

Return type

Returns an array of plain objects.

Array<Pick<PlainObject, Key>>

Settings#

import {
  loadSettingsAsync,
  saveSettingsAsync
} from '@create-figma-plugin/utilities'

loadSettingsAsync<Settings>(defaultSettings [, settingsKey])#

Loads your plugin/widget’s settings (stored locally on the user’s computer under the given settingsKey).

Type parameters

• Settings

Parameters

• defaultSettings (Settings)
• settingsKey (string) – Optional. The key in figma.clientStorage on which to store the settings. Defaults to 'settings'.

Return type

Promise<Settings>

saveSettingsAsync<Settings>(settings [, settingsKey])#

Saves the given settings for your plugin/widget (stored locally on the user’s computer under the given settingsKey).

Type parameters

• Settings

Parameters

• settings (Settings)
• settingsKey (string) – Optional. The key in figma.clientStorage on which to store the settings. Defaults to 'settings'.

Return type

Promise<void>

String#

import {
  formatErrorMessage,
  formatSuccessMessage,
  formatWarningMessage,
  pluralize
} from '@create-figma-plugin/utilities'

formatErrorMessage(message)#

Adds a ✘ prefix to the given message.

Parameters

• message (string)

Return type

string

formatSuccessMessage(message)#

Adds a ✔ prefix to the given message.

Parameters

• message (string)

Return type

string

formatWarningMessage(message)#

Adds a ⚠ prefix to the given message.

Parameters

• message (string)

Return type

string

pluralize(number, singular [, plural])#

Returns singular if number is exactly 1, else returns plural. plural defaults to `${singular}s` if not specified.

Parameters

• number (number)
• singular (string)
• plural (string) – Optional.

Return type

string

UI#

import { showUI } from '@create-figma-plugin/utilities'

showUI<Data>(options [, data])#

Renders the UI correponding to the command in a modal within the Figma UI. Specify the modal’s width, height, title, and whether it is visible via options. Optionally pass on some initialising data from the command to the UI.

Learn how to add a UI to your plugin/widget.

Type parameters

• Data (Record<string, unknown>)

Parameters

• options (ShowUIOptions)
• data (Data) – Optional.

Return type

void