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/utilitiesWhen 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
ST(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
} 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 infigma.clientStorageon 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 infigma.clientStorageon 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 infigma.clientStorageon which to store the use count. Defaults to'totalUseCount'.
Return type
Promise<void>
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 totrueto check that the expression contains only integers. Defaults tofalse.
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
PlainObjectKey(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 infigma.clientStorageon 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 infigma.clientStorageon 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