TextNode
The text node represents text where both the whole node or individual character ranges can have properties such as color (fills), font size, font name, etc.
When working with text nodes, there are a lot of things to consider:
- Mixed styles
- Loading fonts
- Missing fonts
Mixed styles
Many text properties can be set on individual characters. For that reason, you will find that many of text properties can return the special value figma.mixed
if there are characters in the text with different values for that property. Always consider that a text properties could have mixed values.
Loading fonts
The important thing with text is that changing the content of a text node requires its font to be loaded and that fonts are not always available. If you attempt to change, say, fontSize
without first loading the font for that text node, the plugin will throw an exception.
When setting the .fontName
or .textStyleId
property, you do only need to load the new font. When setting any other property that affects text layout, you need to load all the fonts that the text node already use. This includes the following properties and functions:
characters
fontSize
fontName
textStyleId
textCase
textDecoration
letterSpacing
lineHeight
setRangeFontSize()
setRangeFontName()
setRangeTextCase()
setRangeTextDecoration()
setRangeLetterSpacing()
setRangeLineHeight()
setRangeTextStyleId()
You do not need to load a font in order to change properties that only affects colors and strokes, such as .fills
, .fillStyleId
, .setRangeFills()
, .strokes
, .strokeWeight
, .strokeAlign
, .strokeStyleId
, .dashPattern
.
Loading a font is done via figma.loadFontAsync(fontname)
.
For text nodes that contain a single font, you can call figma.loadFontAsync(node.fontName)
. For nodes that contain multiple fonts you need to use the getRangeFontName
API to get all the fonts that the node is using. As an example:
let len = node.characters.length
for (let i = 0; i < len; i++) {
await figma.loadFontAsync(node.getRangeFontName(i, i+1))
}
Missing fonts
You will also need to check text.hasMissingFont
before loading a font. If your plugin works with text, do not to ignore this. While less frequent during testing, it's very common in the real world that your users will attempt to run your plugin in a file with missing fonts.
How text works in Figma (and why you need to load fonts)
When a user types into a text node or changes one of its properties, we generate a path to represent the text, and store it along with the text node. This way, sharing a file (e.g. to a client) allows them to see the design as-is. Even if they don't have the fonts installed on their system! However, this means that even when a text node looks fine, it may not be editable.
This is one of the many subtleties that Figma needs to do to uphold the core value proposition of a cloud tool: that everyone looking at the same file always sees the same thing.
In addition to this, a font file is not always loaded in memory even when it is available from the user's local machine. This is because font files can be big, there could be many of them, and they aren't needed until text is edited. This makes loading them at startup time potentially very expensive. As such, calling
loadFontAsync
is necessary to ensure that the font is available.
Text node properties
[readonly]
type: "TEXT"The type of this node, represented by the string literal "TEXT"
TextNode
clone():Duplicates the text node. By default, the duplicate will be parented under figma.currentPage
.
[readonly]
hasMissingFont: booleanReturns whether the text uses a font currently not available to the document.
textAlignHorizontal: "LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED"
The horizontal alignment of the text with respect to the textbox. Setting this property requires the font the be loaded.
textAlignVertical: "TOP" | "CENTER" | "BOTTOM"
The vertical alignment of the text with respect to the textbox. Setting this property requires the font the be loaded.
textAutoResize: "NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT"
The behavior of how the size of the text box adjusts to fit the characters. Setting this property requires the font the be loaded. [Read more]
paragraphIndent: number
The indentation of paragraphs (offset of the first line from the left). Setting this property requires the font the be loaded.
paragraphSpacing: number
The vertical distance between paragraphs. Setting this property requires the font the be loaded.
autoRename: boolean
Whether updating the characters in the text node should update the name of the node. If this is set to true, name
will be auto-derived from characters
. [Read more]
Text content
characters: string
The raw characters in the text node. Setting this property requires the font the be loaded. [Read more]
insertCharacters(start: number, characters: string, useStyle?: "BEFORE" | "AFTER"): void
Insert characters
at index start
in the text. [Read more]
deleteCharacters(start: number, end: number): void
Remove characters in the text from start
(inclusive) to end
(exclusive). [Read more]
Text and text range properties
These properties can be applied to the whole text node, or parts of the text on specific character ranges.
PluginAPI['mixed']
fontSize: number |The size of the font. Has minimum value of 1.
FontName | PluginAPI['mixed']
fontName:The font family (e.g. "Roboto"), and font style (e.g. "Regular"). Setting this property to a different value requires the new font to be loaded.
TextCase | PluginAPI['mixed']
textCase:Overrides the case of the raw characters in the text node. Requires the font to be loaded.
TextDecoration | PluginAPI['mixed']
textDecoration:Whether the text is underlined or has a strikethrough. Requires the font to be loaded.
LetterSpacing | PluginAPI['mixed']
letterSpacing:The spacing between the individual characters. Requires the font to be loaded.
LineHeight | PluginAPI['mixed']
lineHeight:The spacing between the lines in a paragraph of text. Requires the font to be loaded.
PluginAPI['mixed']
textStyleId: string |The id of the TextStyle
object that the text properties of this node are linked to. Requires the font to be loaded.
Text range functions
These functions allow you to set text properties on parts of the text.
PluginAPI['mixed']
getRangeFontSize(start: number, end: number): number |Get the fontSize
from characters in range start
(inclusive) to end
(exclusive).
setRangeFontSize(start: number, end: number, value: number): void
Set the fontSize
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
FontName | PluginAPI['mixed']
getRangeFontName(start: number, end: number):Get the fontName
from characters in range start
(inclusive) to end
(exclusive).
FontName): void
setRangeFontName(start: number, end: number, value:Set the fontName
from characters in range start
(inclusive) to end
(exclusive). Requires the new font to be loaded.
TextCase | PluginAPI['mixed']
getRangeTextCase(start: number, end: number):Get the textCase
from characters in range start
(inclusive) to end
(exclusive).
TextCase): void
setRangeTextCase(start: number, end: number, value:Set the textCase
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
TextDecoration | PluginAPI['mixed']
getRangeTextDecoration(start: number, end: number):Get the textDecoration
from characters in range start
(inclusive) to end
(exclusive).
TextDecoration): void
setRangeTextDecoration(start: number, end: number, value:Set the textDecoration
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
LetterSpacing | PluginAPI['mixed']
getRangeLetterSpacing(start: number, end: number):Get the letterSpacing
from characters in range start
(inclusive) to end
(exclusive).
LetterSpacing): void
setRangeLetterSpacing(start: number, end: number, value:Set the letterSpacing
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
LineHeight | PluginAPI['mixed']
getRangeLineHeight(start: number, end: number):Get the lineHeight
from characters in range start
(inclusive) to end
(exclusive).
LineHeight): void
setRangeLineHeight(start: number, end: number, value:Set the lineHeight
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
Paint[] | PluginAPI['mixed']
getRangeFills(start: number, end: number):Get the fills
from characters in range start
(inclusive) to end
(exclusive).
Paint[]): void
setRangeFills(start: number, end: number, value:Set the fills
from characters in range start
(inclusive) to end
(exclusive).
PluginAPI['mixed']
getRangeTextStyleId(start: number, end: number): string |Get the textStyleId
from characters in range start
(inclusive) to end
(exclusive).
setRangeTextStyleId(start: number, end: number, value: string): void
Set the textStyleId
from characters in range start
(inclusive) to end
(exclusive). Requires the font to be loaded.
PluginAPI['mixed']
getRangeFillStyleId(start: number, end: number): string |Get the fillStyleId
from characters in range start
(inclusive) to end
(exclusive).
setRangeFillStyleId(start: number, end: number, value: string): void
Set the fillStyleId
from characters in range start
(inclusive) to end
(exclusive).
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]
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]
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]
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]
getPluginData(key: string): string
Retrieves custom information that was stored on this node using setPluginData
.
setPluginData(key: string, value: string): void
Lets you store custom information on any node, private to your plugin. [Read more]
getSharedPluginData(namespace: string, key: string): string
Retrieves custom information that was stored on this node using setSharedPluginData
.
setSharedPluginData(namespace: string, key: string, value: string): void
Lets you store custom information on any node, public to all plugins. [Read more]
setRelaunchData(relaunchData: RelaunchData): void
Sets state on the node to show a button and description in the properties panel when the node is selected. Clears the button and description when relaunchData
is {}
. [Read more]
RelaunchData = { [command: string]: /* description */ string }
e.g. relaunchData = { myCommand: 'Short description' }
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]
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.
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]
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.
strokeWeight: number
The thickness of the stroke, in pixels. This value must be non-negative and can be fractional.
strokeMiterLimit: number
The miter limit on the stroke. This is the same as the SVG miter limit.
strokeAlign: "CENTER" | "INSIDE" | "OUTSIDE"
The alignment of the stroke with respect to the boundaries of the shape. [Read more]
strokeCap: StrokeCap | PluginAPI['mixed']
The decoration applied to vertices which have only one connected segment. [Read more]
strokeJoin: StrokeJoin | PluginAPI['mixed']
The decoration applied to vertices which have two or more connected segments. [Read more]
dashPattern: ReadonlyArray<number>
A list of numbers specifying alternating dash and gap lengths, in pixels.
fillStyleId: string | PluginAPI['mixed']
The id of the PaintStyle
object that the fills
property of this node is linked to. [Read more]
strokeStyleId: string
The id of the PaintStyle
object that the strokes
property of this node is linked to.
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.
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.
[readonly]
constrainProportions: booleanWhen toggled, causes the layer to keep its proportions when the user resizes it via the properties panel.
layoutAlign: "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> [readonly]
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.
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.