addElementAtCursor
Add element to responsive documents, which slot things into a text stream
Parameters
element
ElementAtCursor
RequiredElements targeting a cursor are a subset of the base Element
An element that renders image content.
type
string
RequiredThe type of element.
This must be "image"
.
altText
AltText | undefined
RequiredA description of the image content.
Use undefined
for content with no description.
text
string
RequiredThe text content.
decorative
boolean | undefined
RequiredIndicates 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.
dataUrl
string
OptionalA data URL that contains the image data.
ref
ImageRef
OptionalA unique identifier that points to an image asset in Canva's backend.
An element that renders video content.
type
string
RequiredThe type of element.
This must be "video"
.
ref
VideoRef
RequiredA unique identifier that points to a video asset in Canva's backend.
altText
AltText | undefined
RequiredA description of the video content.
Use undefined
for content with no description.
text
string
RequiredThe text content.
decorative
boolean | undefined
RequiredIndicates 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.
type
string
RequiredThe type of element.
This must be "embed"
.
url
string
RequiredThe URL of the rich media.
This URL must be supported by the Iframely API.
An element that renders text content.
type
string
RequiredThe type of element.
This must be "text"
.
children
string[]
RequiredThe text content.
Only the first element in this array is used.
fontSize
number
OptionalThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlign
string
OptionalThe alignment of the text.
Default value: "start"
Available values:
"start"
"center"
"end"
"justify"
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontRef
FontRef
OptionalA unique identifier that points to a font asset in Canva's backend.
fontWeight
FontWeight
OptionalThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the font.
Default value: "none"
Available values:
"none"
"underline"
An element that renders richtext content.
type
string
RequiredThe type of element.
This must be "richtext"
.
range
RichtextRange
RequiredThe richtext content.
formatParagraph
function
RequiredFormats 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
bounds
Bounds
RequiredThe segment of the range on which to apply the formatting.
index
number
RequiredThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
RequiredThe number of characters in the segment, starting from the index.
formatting
RichtextFormatting
RequiredThe formatting to apply to the paragraph(s).
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
OptionalThe 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"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
OptionalThe strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
OptionalAn external URL that the text links to.
fontRef
FontRef
OptionalA unique identifier that points to a font asset in Canva's backend.
fontSize
number
OptionalThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100
textAlign
string
OptionalThe alignment of the text.
Default value: "start"
Available values:
"start"
"center"
"end"
"justify"
listLevel
number
OptionalThe list indentation level of the paragraph.
listMarker
string
OptionalThe 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
formatText
function
RequiredFormats a region of text with inline formatting properties.
Parameters
bounds
Bounds
RequiredThe segment of the range on which to apply the formatting.
index
number
RequiredThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
RequiredThe number of characters in the segment, starting from the index.
formatting
InlineFormatting
RequiredThe formatting to apply to the text.
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
OptionalThe 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"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
OptionalThe strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
OptionalAn external URL that the text links to.
Returns
void
appendText
function
RequiredAppends the specified characters to the end of the range.
Parameters
characters
string
RequiredThe characters to append to the richtext range.
formatting
InlineFormatting
OptionalOptions for formatting inline richtext.
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
OptionalThe 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"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
OptionalThe strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
OptionalAn external URL that the text links to.
Returns
bounds
Bounds
A segment of a richtext range.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
replaceText
function
RequiredReplaces a region of text with the specified characters.
Parameters
bounds
Bounds
RequiredThe segment of the range to replace.
index
number
RequiredThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
RequiredThe number of characters in the segment, starting from the index.
characters
string
RequiredThe replacement characters.
formatting
InlineFormatting
OptionalThe formatting to apply to the replaced text.
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontWeight
FontWeight
OptionalThe 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"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the text.
Default value: "none"
Available values:
"none"
"underline"
strikethrough
string
OptionalThe strikethrough of the text.
Default value: "none"
Available values:
"none"
"strikethrough"
link
string
OptionalAn external URL that the text links to.
Returns
bounds
Bounds
The bounds of the replacement characters within the updated range.
index
number
The starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
length
number
The number of characters in the segment, starting from the index.
readPlaintext
function
RequiredReturns the current state of the richtext as plaintext.
Returns
string
readTextRegions
function
RequiredReturns 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
text
string
The plaintext content of the region.
formatting
Partial<RichtextFormatting>
OptionalThe formatting of the region.
An element that renders a table.
type
string
RequiredThe type of element.
This must be "table"
.
rows
object[]
RequiredThe rows of the table.
cells
Array<Cell | null | undefined>
RequiredThe cells (columns) of the row.
Each row must have the same number of cells.
This should be either the following object, null
, or undefined
.
attributes
CellAttributes
OptionalThe attributes of the cell.
backgroundColor
string
OptionalThe background color of the cell, as a hex code.
fontSize
number
OptionalThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlign
string
OptionalThe alignment of the text.
Default value: "start"
Available values:
"start"
"center"
"end"
"justify"
color
string
OptionalThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a #
symbol.
Example
"#ff0099"
fontRef
FontRef
OptionalA unique identifier that points to a font asset in Canva's backend.
fontWeight
FontWeight
OptionalThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal"
"thin"
"extralight"
"light"
"medium"
"semibold"
"bold"
"ultrabold"
"heavy"
fontStyle
string
OptionalThe style of the font.
Default value: "normal"
Available values:
"normal"
"italic"
decoration
string
OptionalThe decoration of the font.
Default value: "none"
Available values:
"none"
"underline"
colSpan
number
OptionalThe number of columns that the cell occupies.
rowSpan
number
OptionalThe number of rows that the cell occupies.
type
string
RequiredAvailable values:
"empty"
"string"
value
string
The plaintext content of the cell.
If an empty string is provided, the type
will change to "empty"
.
Returns
Promise<void>