InstanceNode
Instances are a copy of a component (see ComponentNode
). They will always be automatically updated if a component is modified.
⚠️ Updating an instance when a component changes has the potential to be slow. Try to avoid access patterns that involve alternating
component write
,instance read
,component write
,instance read
, ...
Instance properties
[readonly]
type: 'INSTANCE'The type of this node, represented by the string literal "INSTANCE"
InstanceNode
clone():Duplicates the instance node. The new instance will have the same master component. By default, the duplicate will be parented under figma.currentPage
.
ComponentNode | null
mainComponent:The component that this instance reflects. This could be a remote, read-only component. This can be set to turn this instance into a different component. On nested instances (instances inside other instances), setting this value clears all overrides and performs nested instance swapping.
swapComponent(componentNode: ComponentNode): void
Swaps this instance's current main component with componentNode
and preserves overrides using the same heuristics as instance swap in the Figma editor UI. Note that we may update these override preservation heuristics from time to time. [Read more]
setProperties(properties: { [property: string]: string }): void
Sets the properties and values of this instance node. This function only works on instances of variants and will error otherwise.
FrameNode
detachInstance():Detaches the given instance from its component. Returns the frame node that results from detaching the instance. For nested instances (instances inside of other instances), also detaches all ancestors nodes that are instances.
scaleFactor: number
The scale factor applied to the instance. [Read more]
Base node properties
id: string [readonly]
An internal identifier for a node. Plugins typically don't need to use this since you can usually just access a node directly. [Read more]
parent: (BaseNode & ChildrenMixin) | null [readonly]
Returns the parent of this node, if any. This property is not meant to be directly edited. To reparent, see appendChild
. [Read more]
name: string
The name of the layer that appears in the layers panel. This may update automatically for text layers. Returns the name of the current file on figma.root
(read-only). [Read more]
removed: boolean [readonly]
Returns true if this node has been removed since it was first accessed. If your plugin stays open for a while and stores references to nodes, you should write your code defensively and check that the nodes haven't been removed by the user. [Read more]
toString(): string
Returns a string representation of the node. For debugging purposes only, do not rely on the exact output of this string in production code. [Read more]
remove(): void
Removes this node and all of its children from the document. [Read more]
setRelaunchData(data: { [command: string]: string }): void
Sets state on the node to show a button and description when the node is selected. Clears the button and description when relaunchData
is {}
.
In Figma, this shows up in the properties panel. In FigJam, this shows up in the property menu. See here for examples. [Read more]
getRelaunchData(): { [command: string]: string }
Retreives the reluanch data stored on this node using setRelaunchData
getPluginData(key: string): string
Retrieves custom information that was stored on this node or style using setPluginData
. If there is no data stored for the provided key, an empty string is returned.
setPluginData(key: string, value: string): void
Lets you store custom information on any node or style, private to your plugin. [Read more]
getPluginDataKeys(): string[]
Retrieves a list of all keys stored on this node or style using using setPluginData
. This enables iterating through all data stored privately on a node or style by your plugin.
getSharedPluginData(namespace: string, key: string): string
Retrieves custom information that was stored on this node or style using setSharedPluginData
. If there is no data stored for the provided namespace and key, an empty string is returned.
setSharedPluginData(namespace: string, key: string, value: string): void
Lets you store custom information on any node or style, public to all plugins. [Read more]
getSharedPluginDataKeys(namespace: string): string[]
Retrieves a list of all keys stored on this node or style using setSharedPluginData
. This enables iterating through all data stored in a given namespace.
Scene node properties
visible: boolean
Whether the node is visible or not. Does not affect a plugin's ability to access the node. [Read more]
locked: boolean
Whether the node is locked or not, preventing certain user interactions on the canvas such as selecting and dragging. Does not affect a plugin's ability to write to those properties. [Read more]
stuckNodes: SceneNode[]
An array of nodes that are "stuck" to this node. In FigJam, stamps, highlights, and some widgets can "stick" to other nodes if they are dragged on top of another node. [Read more]
Children-related properties
children: ReadonlyArray<SceneNode> [readonly]
The list of children, sorted back-to-front. That is, the first child in the array is the bottommost layer on the screen, and the last child in the array is the topmost layer. [Read more]
appendChild(child: SceneNode): void
Adds a new child to the end of the children
array. That is, visually on top of all other children. [Read more]
insertChild(index: number, child: SceneNode): void
Adds a new child at the specified index in the children
array. [Read more]
findChildren(callback?: (node: SceneNode) => boolean): SceneNode[]
Searches the immediate children of this node (i.e. not including the children's children). Returns all nodes for which callback
returns true. [Read more]
findChild(callback: (node: SceneNode) => boolean): SceneNode | null
Searches the immediate children of this node (i.e. not including the children's children). Returns the first node for which callback
returns true. [Read more]
findAll(callback?: (node: SceneNode) => boolean): SceneNode[]
Searches this entire subtree (this node's children, its children's children, etc). Returns all nodes for which callback
returns true. [Read more]
findOne(callback: (node: SceneNode) => boolean): SceneNode | null
Searches this entire subtree (this node's children, its children's children, etc). Returns the first node for which callback
returns true. [Read more]
findAllWithCriteria<T extends NodeType[]>(criteria: { types: T }): Array<{ type: T[number] } & SceneNode>
Searches this entire subtree (this node's children, its children's children, etc). Returns all nodes that satisfy any of the types defined in the criteria. [Read more]
findWidgetNodesByWidgetId(widgetId: string): Array<WidgetNode>
Searches this entire subtree (this node's children, its children's children, etc). Returns all widget nodes that match the provided widgetId
. [Read more]
Frame properties
layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL'
Determines whether this layer uses auto-layout to position its children. Defaults to "NONE". [Read more]
primaryAxisSizingMode: 'FIXED' | 'AUTO'
Applicable only on auto-layout frames. Determines whether the primary axis has a fixed length (determined by the user) or an automatic length (determined by the layout engine). [Read more]
counterAxisSizingMode: 'FIXED' | 'AUTO'
Applicable only on auto-layout frames. Determines whether the counter axis has a fixed length (determined by the user) or an automatic length (determined by the layout engine). [Read more]
primaryAxisAlignItems: 'MIN' | 'MAX' | 'CENTER' | 'SPACE_BETWEEN'
Applicable only on auto-layout frames, ignored otherwise. Determines how the auto-layout frame’s children should be aligned in the primary axis direction. [Read more]
counterAxisAlignItems: 'MIN' | 'MAX' | 'CENTER'
Applicable only on auto-layout frames, ignored otherwise. Determines how the auto-layout frame’s children should be aligned in the counter axis direction. [Read more]
paddingLeft: number
Applicable only on auto-layout frames, ignored otherwise. Determines the left padding between the border of the frame and its children.
paddingRight: number
Applicable only on auto-layout frames, ignored otherwise. Determines the right padding between the border of the frame and its children.
paddingTop: number
Applicable only on auto-layout frames, ignored otherwise. Determines the top padding between the border of the frame and its children.
paddingBottom: number
Applicable only on auto-layout frames, ignored otherwise. Determines the bottom padding between the border of the frame and its children.
itemSpacing: number
Applicable only on auto-layout frames. Determines distance between children of the frame.
horizontalPadding: number
[DEPRECATED]
Use paddingLeft
and paddingRight
instead.
verticalPadding: number
[DEPRECATED]
Use paddingTop
and paddingBottom
instead.
LayoutGrid>
layoutGrids: ReadonlyArray<Array of LayoutGrid
objects used as layout grids on this node. For help on how to change this value, see Editing Properties.
gridStyleId: string
The id of the GridStyle
object that the layoutGrids
property of this node is linked to.
clipsContent: boolean
Whether the frame clips its contents. That is, whether layers inside the frame are visible outside the bounds of the frame.
Guide>
guides: ReadonlyArray<Array of Guide
used inside the frame. Note that each frame has it's own guides, separate from the canvas-wide guides. For help on how to change this value, see Editing Properties.
Container-related properties
expanded: boolean
Whether this container is shown as expanded in the layers panel.
Paint>
backgrounds: ReadonlyArray<[DEPRECATED]
Use fills
instead.
backgroundStyleId: string
[DEPRECATED]
Use fillStyleId
instead.
Geometry-related properties
fills: ReadonlyArray<Paint> | PluginAPI['mixed']
The paints used to fill the area of the shape. For help on how to change this value, see Editing Properties. [Read more]
fillStyleId: string | PluginAPI['mixed']
The id of the PaintStyle
object that the fills
property of this node is linked to. [Read more]
VectorPaths
fillGeometry:An array of paths representing the object fills relative to the node.
Paint>
strokes: ReadonlyArray<The paints used to fill the area of the shape's strokes. For help on how to change this value, see Editing Properties.
strokeStyleId: string
The id of the PaintStyle
object that the strokes
property of this node is linked to.
strokeWeight: number
The thickness of the stroke, in pixels. This value must be non-negative and can be fractional.
strokeJoin: StrokeJoin | PluginAPI['mixed']
The decoration applied to vertices which have two or more connected segments. [Read more]
strokeAlign: 'CENTER' | 'INSIDE' | 'OUTSIDE'
The alignment of the stroke with respect to the boundaries of the shape. [Read more]
dashPattern: ReadonlyArray<number>
A list of numbers specifying alternating dash and gap lengths, in pixels.
VectorPaths
strokeGeometry:An array of paths representing the object strokes relative to the node.
StrokeGeometry is always from the center regardless of the nodes strokeAlign
.
strokeCap: StrokeCap | PluginAPI['mixed']
The decoration applied to vertices which have only one connected segment. [Read more]
strokeMiterLimit: number
The miter limit on the stroke. This is the same as the SVG miter limit.
VectorNode | null
outlineStroke():This method performs an action similar to using the "Outline Stroke" function in the editor from the right-click menu. However, this method creates and returns a new node while leaving the original intact. Returns null
if the node has no strokes.
Corner-related properties
cornerRadius: number | PluginAPI['mixed']
The number of pixels to round the corners of the object by. [Read more]
cornerSmoothing: number
A value that lets you control how "smooth" the corners are. Ranges from 0 to 1. [Read more]
topLeftRadius: number
topRightRadius: number
bottomLeftRadius: number
bottomRightRadius: number
You can set individual corner radius of each of the four corners of a rectangle node or frame-like node. Similar to cornerRadius
, these value must be non-negative and can be fractional. If an edge length is less than twice the corner radius, the corner radius for each vertex of the edge will be clamped to half the edge length.
Setting cornerRadius
sets the property for all four corners. Setting these corners to different values makes cornerRadius
return mixed
.
Blend-related properties
opacity: number
Opacity of the node, as shown in the Layer panel. Must be between 0 and 1.
BlendMode
blendMode: 'PASS_THROUGH' |Blend mode of this node, as shown in the Layer panel. In addition to the blend modes that paints & effects support, the layer blend mode can also have the value PASS_THROUGH.
isMask: boolean
Whether this node is a mask. A mask node masks its subsequent siblings.
Effect>
effects: ReadonlyArray<Array of effects. See Effect
type. For help on how to change this value, see Editing Properties.
effectStyleId: string
The id of the EffectStyle
object that the properties of this node are linked to.
Layout-related properties
Transform [readonly]
absoluteTransform:The position of a node relative to its containing page as a Transform
matrix.
relativeTransform: Transform
The position of a node relative to its containing parent as a Transform
matrix. Not used for scaling, see width
and height
instead. Read the details page to understand the nuances of this property. [Read more]
x: number
The position of the node. Identical to relativeTransform[0][2]
. [Read more]
y: number
The position of the node. Identical to relativeTransform[1][2]
. [Read more]
rotation: number
The rotation of the node in degrees. Returns values from -180 to 180. Identical to Math.atan2(-m10, m00)
in the relativeTransform
matrix. When setting rotation
, it will also set m00
, m01
, m10
, m11
. [Read more]
[readonly]
width: numberThe width of the node. Use a resizing method to change this value.
[readonly]
height: numberThe height of the node. Use a resizing method to change this value.
Rect | null [readonly]
absoluteRenderBounds:The actual bounds of a node accounting for drop shadows, thick strokes, and anything else that may fall outside the node's regular bounding box defined in x
, y
, width
, and height
. The x
and y
inside this property represent the absolute position of the node on the page. This value will be null
if the node is invisible.
constrainProportions: boolean
When toggled, causes the layer to keep its proportions when the user resizes it via the properties panel.
layoutAlign: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'INHERIT'
Applicable only on direct children of auto-layout frames, ignored otherwise. Determines if the layer should stretch along the parent’s counter axis. Defaults to “INHERIT”
. [Read more]
layoutGrow: number
This property is applicable only for direct children of auto-layout frames, ignored otherwise. Determines whether a layer should stretch along the parent’s primary axis. 0 corresponds to a fixed size and 1 corresponds to stretch. [Read more]
resize(width: number, height: number): void
Resizes the node. If the node contains children with constraints, it applies those constraints during resizing. If the parent has auto-layout, causes the parent to be resized. [Read more]
resizeWithoutConstraints(width: number, height: number): void
Resizes the node. Children of the node are never resized, even if those children have constraints. If the parent has auto-layout, causes the parent to be resized (this constraint cannot be ignored). [Read more]
rescale(scale: number): void
Rescales the node. This API function is the equivalent of using the Scale Tool from the toolbar. [Read more]
constraints: Constraints
Constraints of this node relative to its containing FrameNode
, if any. [Read more]
Export-related properties
ExportSettings>
exportSettings: ReadonlyArray<List of export settings stored on the node. For help on how to change this value, see Editing Properties.
ExportSettings): Promise<Uint8Array>
exportAsync(settings?:Exports the node as an encoded image. [Read more]
Reaction prototyping-related properties
Reaction>
reactions: ReadonlyArray<List of Reaction
s on this node, which includes both the method of interaction with this node in a prototype, and the behavior of that interaction. For help on how to change this value, see Editing Properties.
Frame prototyping-related properties
overflowDirection: OverflowDirection
Determines whether a frame will scroll in presentation mode when the frame contains content that exceed the frame's bounds. Reflects the value shown in "Overflow Behavior" in the Prototype tab. [Read more]
numberOfFixedChildren: number
Determines which children of the frame are fixed children in a scrolling frame. [Read more]
OverlayPositionType [readonly]
overlayPositionType:How this frame is positioned when opened as an overlay.
OverlayBackground [readonly]
overlayBackground:How this frame obscures the content under it when opened as an overlay.
OverlayBackgroundInteraction [readonly]
overlayBackgroundInteraction:How the user can interact with the content under this frame when opened as an overlay.
Variant-related properties
[readonly]
variantProperties: { [property: string]: string } | nullVariant properties and values for this node. Is null
for nodes that are not variants or instances of variants.