Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
API reference

addElementAtPoint

API reference for the addElementAtPoint method.
This version of the API is a preview. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Add element to fixed designs, which use a coordinate-based positioning system.

Parameters

elementobjectRequired

An element that's natively supported by the Canva editor.

An element that renders image content.

typestringRequired

The type of element.

This must be "image".

altTextAltText | undefinedRequired

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
dataUrlstringOptional

A data URL that contains the image data.

refImageRefOptional

A unique identifier that points to an image asset in Canva's backend.

An element that renders video content.

typestringRequired

The type of element.

This must be "video".

refVideoRefRequired

A unique identifier that points to a video asset in Canva's backend.

altTextAltText | undefinedRequired

A description of the video content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

An element that renders rich media, such as a YouTube video.

typestringRequired

The type of element.

This must be "embed".

urlstringRequired

The URL of the rich media.

This URL must be supported by the Iframely API.

An element that renders text content.

typestringRequired

The type of element.

This must be "text".

childrenstring[]Required

The text content.

Only the first element in this array is used.

fontSizenumberOptional

The size of the text.

Minimum: 1

Maximum: 100

Default value: 16

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontRefFontRefOptional

A unique identifier that points to a font asset in Canva's backend.

fontWeightFontWeightOptional

The weight (thickness) of the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the font.

Default value: "none"

Available values:

  • "none"
  • "underline"

An element that renders a vector shape.

typestringRequired

The type of element.

This must be "shape".

viewBoxShapeViewBoxRequired

Options for configuring the scale and cropping of the shape.

topnumberRequired

The distance of the shape from the top edge of the element, in pixels.

leftnumberRequired

The distance of the shape from the left edge of the element, in pixels.

widthnumberRequired

The width of the view box, in pixels.

heightnumberRequired

The height of the view box, in pixels.

pathsShapePath[]Required

The paths that define the structure of the shape.

  • There must be between 1 and 30 paths (inclusive).
  • The maximum combined size of all paths must not exceed 2kb.
  • The maximum number of unique fill colors across all paths is 6.
dstringRequired

The shape of the path.

This is similar to the d attribute of an SVG's path element, with some limitations:

  • The path must start with an M command.
  • The path must not have more than one M command.
  • The path must not use the Q command.
  • The path must be closed, either by:
    • Using a Z command at the end of the path
    • Having the last coordinate match the first coordinate
fillFillRequired

The appearance of the path's interior.

dropTargetbooleanOptional

If true, users can replace a fill by dropping an image or video onto it.

colorstringOptional

The color of the fill as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
assetobjectOptional

An image or video to use as the fill.

An image asset that fills a path's interior.

typestringRequired

The type of fill.

This must be "image".

refImageRefRequired

A unique identifier that points to an image asset in Canva's backend.

altTextAltTextOptional

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

A video asset that fills a path's interior.

typestringRequired

The type of fill.

This must be "video".

refVideoRefRequired

A unique identifier that points to a video asset in Canva's backend.

altTextAltTextOptional

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
strokePathStrokeOptional

The outline of the path.

weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorstringRequired

The color of the stroke as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
strokeAlignstringRequired

The alignment of the stroke.

This must be "inset".

An element that contains two or more elements.

typestringRequired

The type of element.

This must be "group".

childrenGroupContentAtPoint[]Required

The elements to render within the group.

  • Each element within a group must have dimensions and a position.
  • The dimensions and positions are relative to the dimensions and positions of the group.

An element that renders richtext content.

typestringRequired

The type of element.

This must be "richtext".

rangeRichtextRangeRequired

The richtext content.

formatParagraphfunctionRequired

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBoundsRequired

The segment of the range on which to apply the formatting.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

A unique identifier that points to a font asset in Canva's backend.

fontSizenumberOptional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default value: "none"

Available values:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

formatTextfunctionRequired

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

The segment of the range on which to apply the formatting.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunctionRequired

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

replaceTextfunctionRequired

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

readPlaintextfunctionRequired

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunctionRequired

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>Optional

The formatting of the region.

An element that renders a table.

typestringRequired

The type of element.

This must be "table".

rowsobject[]Required

The rows of the table.

cellsArray<Cell | null | undefined>Required

The cells (columns) of the row.

Each row must have the same number of cells.

This should be either the following object, null, or undefined.

attributesCellAttributesOptional

The attributes of the cell.

backgroundColorstringOptional

The background color of the cell, as a hex code.

fontSizenumberOptional

The size of the text.

Minimum: 1

Maximum: 100

Default value: 16

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontRefFontRefOptional

A unique identifier that points to a font asset in Canva's backend.

fontWeightFontWeightOptional

The weight (thickness) of the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the font.

Default value: "none"

Available values:

  • "none"
  • "underline"
colSpannumberOptional

The number of columns that the cell occupies.

rowSpannumberOptional

The number of rows that the cell occupies.

typestringRequired

Available values:

  • "empty"
  • "string"
valuestring
Sometimes required

The plaintext content of the cell.

If an empty string is provided, the type will change to "empty".

An element that's natively supported by the Canva editor and has positional properties.

An element that renders image content and has positional properties.

typestringRequired

The type of element.

This must be "image".

altTextAltText | undefinedRequired

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumberRequired

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumberRequired

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

dataUrlstringOptional

A data URL that contains the image data.

refImageRefOptional

A unique identifier that points to an image asset in Canva's backend.

An element that renders video content and has positional properties.

typestringRequired

The type of element.

This must be "video".

refVideoRefRequired

A unique identifier that points to a video asset in Canva's backend.

altTextAltText | undefinedRequired

A description of the video content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumberRequired

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumberRequired

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

An element that renders rich media, such as a YouTube video, and has positional properties.

typestringRequired

The type of element.

This must be "embed".

urlstringRequired

The URL of the rich media.

This URL must be supported by the Iframely API.

topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumberRequired

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumberRequired

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

An element that renders text content and has positional properties.

typestringRequired

The type of element.

This must be "text".

childrenstring[]Required

The text content.

Only the first element in this array is used.

topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

fontSizenumberOptional

The size of the text.

Minimum: 1

Maximum: 100

Default value: 16

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontRefFontRefOptional

A unique identifier that points to a font asset in Canva's backend.

fontWeightFontWeightOptional

The weight (thickness) of the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the font.

Default value: "none"

Available values:

  • "none"
  • "underline"
rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

widthnumberOptional

The width of the element, in pixels.

Minimum: 0

Maximum: 32767

An element that renders a vector shape and has positional properties.

typestringRequired

The type of element.

This must be "shape".

viewBoxShapeViewBoxRequired

Options for configuring the scale and cropping of the shape.

topnumberRequired

The distance of the shape from the top edge of the element, in pixels.

leftnumberRequired

The distance of the shape from the left edge of the element, in pixels.

widthnumberRequired

The width of the view box, in pixels.

heightnumberRequired

The height of the view box, in pixels.

pathsShapePath[]Required

The paths that define the structure of the shape.

  • There must be between 1 and 30 paths (inclusive).
  • The maximum combined size of all paths must not exceed 2kb.
  • The maximum number of unique fill colors across all paths is 6.
dstringRequired

The shape of the path.

This is similar to the d attribute of an SVG's path element, with some limitations:

  • The path must start with an M command.
  • The path must not have more than one M command.
  • The path must not use the Q command.
  • The path must be closed, either by:
    • Using a Z command at the end of the path
    • Having the last coordinate match the first coordinate
fillFillRequired

The appearance of the path's interior.

dropTargetbooleanOptional

If true, users can replace a fill by dropping an image or video onto it.

colorstringOptional

The color of the fill as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
assetobjectOptional

An image or video to use as the fill.

An image asset that fills a path's interior.

typestringRequired

The type of fill.

This must be "image".

refImageRefRequired

A unique identifier that points to an image asset in Canva's backend.

altTextAltTextOptional

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.

A video asset that fills a path's interior.

typestringRequired

The type of fill.

This must be "video".

refVideoRefRequired

A unique identifier that points to a video asset in Canva's backend.

altTextAltTextOptional

A description of the image content.

Use undefined for content with no description.

textstringRequired

The text content.

decorativeboolean | undefinedRequired

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
strokePathStrokeOptional

The outline of the path.

weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorstringRequired

The color of the stroke as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
strokeAlignstringRequired

The alignment of the stroke.

This must be "inset".

topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumberRequired

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumberRequired

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

An element that contains two or more elements and has positional properties.

typestringRequired

The type of element.

This must be "group".

childrenGroupContentAtPoint[]Required

The elements to render within the group.

  • Each element within a group must have dimensions and a position.
  • The dimensions and positions are relative to the dimensions and positions of the group.
topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

widthnumberRequired

A width, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

heightnumberRequired

A height, in pixels.

  • The pixels are relative to their container.

Minimum: 0

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

An element that renders richtext content.

This type includes properties for controlling the position and dimensions of the element. It will be positioned and sized relative to its parent container. The parent container may be an app element, or the current page.

typestringRequired

The type of element.

This must be "richtext".

rangeRichtextRangeRequired

The richtext content.

formatParagraphfunctionRequired

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBoundsRequired

The segment of the range on which to apply the formatting.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

A unique identifier that points to a font asset in Canva's backend.

fontSizenumberOptional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

The appearance of list item markers.

This property only has an effect if listLevel is greater than 0.

Default value: "none"

Available values:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

formatTextfunctionRequired

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

The segment of the range on which to apply the formatting.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunctionRequired

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

replaceTextfunctionRequired

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumberRequired

The number of characters in the segment, starting from the index.

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeightOptional

The weight (thickness) of the font.

The available font weights depend on the font.

Default value: "normal"

Available values:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

indexnumber

The starting position of the segment.

This is zero-based, meaning the first character of the range is at index 0.

lengthnumber

The number of characters in the segment, starting from the index.

readPlaintextfunctionRequired

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunctionRequired

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>Optional

The formatting of the region.

topnumberRequired

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberOptional

A rotation, in degrees.

Minimum: -180

Maximum: 180

widthnumberOptional

The width of the element, in pixels.

Minimum: 0

Maximum: 32767

Returns

Promise<void>