addElementAtCursor

API reference for the addElementAtCursor method.

Add element to responsive documents, which slot things into a text stream

Parameters

#elementElementAtCursor

Required

Elements targeting a cursor are a subset of the base Element

An element that renders image content.

#typestring

Required

The type of element.

This must be "image".

#altTextAltText | undefined

Required

A description of the image content.

Properties of altText

#textstring

Required

The text content.

#decorativeboolean | undefined

Required

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.

#dataUrlstring

Optional

A data URL that contains the image data.

#refImageRef

Optional

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

An element that renders video content.

#typestring

Required

The type of element.

This must be "video".

#refVideoRef

Required

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

#altTextAltText | undefined

Required

A description of the video content.

Properties of altText

#textstring

Required

The text content.

#decorativeboolean | undefined

Required

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 text content.

#typestring

Required

The type of element.

This must be "text".

#childrenstring[]

Required

The text content.

Only the first element in this array is used.

#fontSizenumber

Optional

The size of the text.

Minimum: 1
Maximum: 100

Default Value: 16

#textAlignstring

Optional

The alignment of the text.

Default Value: "start"

The available options include:

"start"
"center"
"end"
"justify"

#colorstring

Optional

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"

#fontRefFontRef

Optional

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

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the font.

Default Value: "none"

The available options include:

"none"
"underline"

An element that renders richtext content.

#typestring

Required

The type of element.

This must be "richtext".

#rangeRichtextRange

Required

The richtext content.

Properties of range

#formatParagraphfunction

Required

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

#boundsBounds

Required

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

Properties of bounds

#indexnumber

Required

The starting position of the segment.

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

#lengthnumber

Required

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

#formattingRichtextFormatting

Required

The formatting to apply to the paragraph(s).

Properties of formatting

#colorstring

Optional

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"

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the text.

Default Value: "none"

The available options include:

"none"
"underline"

#strikethroughstring

Optional

The strikethrough of the text.

Default Value: "none"

The available options include:

"none"
"strikethrough"

#linkstring

Optional

An external URL that the text links to.

#fontRefFontRef

Optional

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

#fontSizenumber

Optional

The size of the text, in pixels.

In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100

#textAlignstring

Optional

The alignment of the text.

Default Value: "start"

The available options include:

"start"
"center"
"end"
"justify"

#listLevelnumber

Optional

The list indentation level of the paragraph.

#listMarkerstring

Optional

The appearance of list item markers.

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

Default Value: "none"

The available options include:

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

Returns

void

#formatTextfunction

Required

Formats a region of text with inline formatting properties.

Parameters

#boundsBounds

Required

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

Properties of bounds

#indexnumber

Required

The starting position of the segment.

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

#lengthnumber

Required

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

#formattingInlineFormatting

Required

The formatting to apply to the text.

Properties of formatting

#colorstring

Optional

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"

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the text.

Default Value: "none"

The available options include:

"none"
"underline"

#strikethroughstring

Optional

The strikethrough of the text.

Default Value: "none"

The available options include:

"none"
"strikethrough"

#linkstring

Optional

An external URL that the text links to.

Returns

void

#appendTextfunction

Required

Appends the specified characters to the end of the range.

Parameters

#charactersstring

Required

The characters to append to the richtext range.

#formattingInlineFormatting

Optional

Options for formatting inline richtext.

Properties of formatting

#colorstring

Optional

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"

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the text.

Default Value: "none"

The available options include:

"none"
"underline"

#strikethroughstring

Optional

The strikethrough of the text.

Default Value: "none"

The available options include:

"none"
"strikethrough"

#linkstring

Optional

An external URL that the text links to.

Returns

#boundsBounds

A segment of a richtext range.

Properties of bounds

#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.

#replaceTextfunction

Required

Replaces a region of text with the specified characters.

Parameters

#boundsBounds

Required

The segment of the range to replace.

Properties of bounds

#indexnumber

Required

The starting position of the segment.

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

#lengthnumber

Required

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

#charactersstring

Required

The replacement characters.

#formattingInlineFormatting

Optional

The formatting to apply to the replaced text.

Properties of formatting

#colorstring

Optional

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"

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

The available font weights depend on the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the text.

Default Value: "none"

The available options include:

"none"
"underline"

#strikethroughstring

Optional

The strikethrough of the text.

Default Value: "none"

The available options include:

"none"
"strikethrough"

#linkstring

Optional

An external URL that the text links to.

Returns

#boundsBounds

The bounds of the replacement characters within the updated range.

Properties of bounds

#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.

#readPlaintextfunction

Required

Returns the current state of the richtext as plaintext.

Returns

string

#readTextRegionsfunction

Required

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.

#typestring

Required

The type of element.

This must be "table".

#rowsobject[]

Required

The rows of the table.

Properties of rows

#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.

#attributesCellAttributes

Optional

The attributes of the cell.

Properties of attributes

#backgroundColorstring

Optional

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

#fontSizenumber

Optional

The size of the text.

Minimum: 1
Maximum: 100

Default Value: 16

#textAlignstring

Optional

The alignment of the text.

Default Value: "start"

The available options include:

"start"
"center"
"end"
"justify"

#colorstring

Optional

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"

#fontRefFontRef

Optional

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

#fontWeightFontWeight

Optional

The weight (thickness) of the font.

Default Value: "normal"

The available options include:

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

#fontStylestring

Optional

The style of the font.

Default Value: "normal"

The available options include:

"normal"
"italic"

#decorationstring

Optional

The decoration of the font.

Default Value: "none"

The available options include:

"none"
"underline"

#colSpannumber

Optional

The number of columns that the cell occupies.

#rowSpannumber

Optional

The number of rows that the cell occupies.

#typestring

Required

The available options include:

"empty"
"string"

#valuestring

Sometimes required

The plaintext content of the cell.

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

Returns

Promise<void>