addElementAtPoint
Add element to fixed designs, which use a coordinate-based positioning system.
Usage
Insert an image at specific coordinates
import { addElementAtPoint } from "@canva/design";import type { ImageElementAtPoint } from "@canva/design";import type { ImageRef } from "@canva/asset";const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;const imageElement: ImageElementAtPoint = {type: 'image',ref: exampleImageRef,altText: { text: 'Product image', decorative: false },top: 100,left: 100,width: 300,height: 200};await addElementAtPoint(imageElement);
Insert a video at specific coordinates
import { addElementAtPoint } from "@canva/design";import type { VideoElementAtPoint } from "@canva/design";import type { VideoRef } from "@canva/asset";const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;const videoElement: VideoElementAtPoint = {type: 'video',ref: exampleVideoRef,altText: { text: 'Product demo', decorative: false },top: 100,left: 100,width: 400,height: 300};await addElementAtPoint(videoElement);
Insert embedded content at specific coordinates
import { addElementAtPoint } from "@canva/design";import type { EmbedElementAtPoint } from "@canva/design";const embedElement: EmbedElementAtPoint = {type: 'embed',url: 'https://www.youtube.com/watch?v=...',top: 100,left: 100,width: 560,height: 315};await addElementAtPoint(embedElement);
Insert text at specific coordinates
import { addElementAtPoint } from "@canva/design";import type { TextElementAtPoint } from "@canva/design";const textElement: TextElementAtPoint = {type: 'text',children: ['Hello World'],top: 100,left: 100,width: 200,fontSize: 24,color: '#000000',textAlign: 'justify'};await addElementAtPoint(textElement);
Parameters
elementobjectAn element that's natively supported by the Canva editor.
An element that renders image content.
typestringThe type of element.
The only valid value is "image".
altTextAltText | undefinedA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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. 
dataUrlstringA data URL that contains the image data.
refImageRefA unique identifier that points to an image asset in Canva's backend.
An element that renders video content.
typestringThe type of element.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltText | undefinedA description of the video content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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.
typestringThe type of element.
The only valid value is "embed".
urlstringThe URL of the rich media.
This URL must be supported by the Iframely API.
An element that renders text content.
typestringThe type of element.
The only valid value is "text".
childrenstring[]The text content.
Only the first element in this array is used.
fontSizenumberThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontWeightFontWeightThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the font.
Default value: "none"
Available values:
"none""underline"
An element that renders a vector shape.
typestringThe type of element.
The only valid value is "shape".
viewBoxShapeViewBoxOptions for configuring the scale and cropping of the shape.
topnumberThe distance of the shape from the top edge of the element, in pixels.
leftnumberThe distance of the shape from the left edge of the element, in pixels.
widthnumberThe width of the view box, in pixels.
heightnumberThe height of the view box, in pixels.
pathsShapePath[]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.
 
dstringThe 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
 
 
fillFillThe appearance of the path's interior.
dropTargetbooleanIf true, users can replace a fill by dropping an image or video onto it.
colorstringThe color of the fill as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
assetobjectAn image or video to use as the fill.
An image asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "image".
refImageRefA unique identifier that points to an image asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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.
typestringThe type of fill.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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. 
strokePathStrokeThe outline of the path.
weightnumberThe weight (thickness) of the stroke.
Minimum: 0
Maximum: 100
colorstringThe color of the stroke as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
strokeAlignstringThe alignment of the stroke.
The only valid value is "inset".
An element that contains two or more elements.
typestringThe type of element.
The only valid value is "group".
childrenGroupContentAtPoint[]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.
typestringThe type of element.
The only valid value is "richtext".
rangeRichtextRangeThe richtext content.
formatParagraphfunctionFormats all of the paragraphs that overlap the given bounds.
- The 
\ncharacter indicates the end of a paragraph. - All paragraphs that overlap the provided bounds will be formatted in their entirety.
 
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingRichtextFormattingThe formatting to apply to the paragraph(s).
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
 
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe 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
Examples
Format paragraph as a heading
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Heading Text\nRegular paragraph text.");// Format just the first paragraph as a headingrange.formatParagraph({ index: 0, length: 12 }, // Only need to include part of the paragraph{fontSize: 24,fontWeight: 'bold',textAlign: 'center'});
Create a bulleted list
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();const text = "Item 1\nItem 2\nItem 3";range.appendText(text);// Format all paragraphs as a bulleted listrange.formatParagraph({ index: 0, length: text.length },{listLevel: 1,listMarker: 'disc'});
formatTextfunctionFormats a region of text with inline formatting properties.
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingInlineFormattingThe formatting to apply to the text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
void
Examples
Format specific words in a paragraph
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains important information.");// Format just the word "important"range.formatText({ index: 16, length: 9 },{fontWeight: 'bold',color: '#FF0000'});
Add a link to text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Visit our website for more information.");// Add a link to "our website"range.formatText({ index: 6, length: 11 },{link: "https://www.example.com",decoration: 'underline',color: '#0066CC'});
appendTextfunctionAppends the specified characters to the end of the range.
Parameters
charactersstringThe characters to append to the richtext range.
formattingInlineFormattingOptional formatting to apply to the appended text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsA segment of a richtext range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Append plain text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph. ");// Append more text to the existing contentconst result = range.appendText("This is additional text.");// The bounds of the newly added text are returned// Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 }
Append formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text followed by ");// Append formatted textrange.appendText("bold red text", {fontWeight: 'bold',color: '#FF0000'});// Append a new paragraphrange.appendText("\nThis is a new paragraph.");
replaceTextfunctionReplaces a region of text with the specified characters.
Parameters
boundsBoundsThe segment of the range to replace.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
charactersstringThe replacement characters.
formattingInlineFormattingThe formatting to apply to the replaced text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsThe bounds of the replacement characters within the updated range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Replace text while maintaining some formatting
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text needs correction.");// Replace "needs correction" with "is correct"const result = range.replaceText({ index: 10, length: 16 },"is correct");// The bounds of the replaced text are returned// Do something with the bounds - result.bounds, e.g. { index: 10, length: 10 }
Replace text with formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Regular text that needs emphasis.");// Replace "needs emphasis" with formatted textrange.replaceText({ index: 17, length: 15 },"is important",{fontWeight: 'bold',fontStyle: 'italic',color: '#0066CC'});
readPlaintextfunctionReturns the current state of the richtext as plaintext.
Returns
string
Examples
Extract plain text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph.\n", { fontWeight: 'bold' });range.appendText("Second paragraph with formatting.", { color: '#FF0000' });// Get plain text content without formattingconst plainText = range.readPlaintext();// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
Search within text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains a searchable term.");// Search for a specific wordconst plainText = range.readPlaintext();const searchTerm = "searchable";const index = plainText.indexOf(searchTerm);if (index !== -1) {// Format the found termrange.formatText({ index, length: searchTerm.length },{ fontWeight: 'bold', decoration: 'underline' });}
readTextRegionsfunctionReturns 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
textstringThe plaintext content of the region.
formattingPartial<RichtextFormatting>The formatting of the region.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
 
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe 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"
Examples
Get text with formatting information
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text ", {});range.appendText("bold text", { fontWeight: 'bold' });range.appendText(" and ", {});range.appendText("red text", { color: '#FF0000' });// Get formatted regionsconst regions = range.readTextRegions();// Do something with the regions, e.g.// [// { text: "Normal text ", formatting: {} },// { text: "bold text", formatting: { fontWeight: 'bold' } },// { text: " and ", formatting: {} },// { text: "red text", formatting: { color: '#FF0000' } }// ]
Analyze formatting variations
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Mixed ", {});range.appendText("formatted ", { fontWeight: 'bold' });range.appendText("text", { color: '#0066CC' });// Analyze formatting variationsconst regions = range.readTextRegions();const formattingTypes = regions.map(region => {const formatting = region.formatting || {};return {text: region.text,hasWeight: !!formatting.fontWeight,hasColor: !!formatting.color};});
An element that renders a table.
typestringThe type of element.
The only valid value is "table".
rowsobject[]The rows of the table.
cellsArray<Cell | null | undefined>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.
attributesCellAttributesThe attributes of the cell.
backgroundColorstringThe background color of the cell, as a hex code.
fontSizenumberThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontWeightFontWeightThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the font.
Default value: "none"
Available values:
"none""underline"
colSpannumberThe number of columns that the cell occupies.
rowSpannumberThe number of rows that the cell occupies.
typestringAvailable values:
"empty""string"
valuestringThe 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.
typestringThe type of element.
The only valid value is "image".
altTextAltText | undefinedA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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. 
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
dataUrlstringA data URL that contains the image data.
refImageRefA unique identifier that points to an image asset in Canva's backend.
An element that renders video content and has positional properties.
typestringThe type of element.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltText | undefinedA description of the video content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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. 
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that renders rich media, such as a YouTube video, and has positional properties.
typestringThe type of element.
The only valid value is "embed".
urlstringThe URL of the rich media.
This URL must be supported by the Iframely API.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that renders text content and has positional properties.
typestringThe type of element.
The only valid value is "text".
childrenstring[]The text content.
Only the first element in this array is used.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
fontSizenumberThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontWeightFontWeightThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the font.
Default value: "none"
Available values:
"none""underline"
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
widthnumberThe width of the element, in pixels.
Minimum: 0
Maximum: 32767
An element that renders a vector shape and has positional properties.
typestringThe type of element.
The only valid value is "shape".
viewBoxShapeViewBoxOptions for configuring the scale and cropping of the shape.
topnumberThe distance of the shape from the top edge of the element, in pixels.
leftnumberThe distance of the shape from the left edge of the element, in pixels.
widthnumberThe width of the view box, in pixels.
heightnumberThe height of the view box, in pixels.
pathsShapePath[]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.
 
dstringThe 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
 
 
fillFillThe appearance of the path's interior.
dropTargetbooleanIf true, users can replace a fill by dropping an image or video onto it.
colorstringThe color of the fill as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
assetobjectAn image or video to use as the fill.
An image asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "image".
refImageRefA unique identifier that points to an image asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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.
typestringThe type of fill.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates 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. 
strokePathStrokeThe outline of the path.
weightnumberThe weight (thickness) of the stroke.
Minimum: 0
Maximum: 100
colorstringThe color of the stroke as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
strokeAlignstringThe alignment of the stroke.
The only valid value is "inset".
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that contains two or more elements and has positional properties.
typestringThe type of element.
The only valid value is "group".
childrenGroupContentAtPoint[]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.
 
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
 
Minimum: 0
Maximum: 32767
rotationnumberA 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.
typestringThe type of element.
The only valid value is "richtext".
rangeRichtextRangeThe richtext content.
formatParagraphfunctionFormats all of the paragraphs that overlap the given bounds.
- The 
\ncharacter indicates the end of a paragraph. - All paragraphs that overlap the provided bounds will be formatted in their entirety.
 
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingRichtextFormattingThe formatting to apply to the paragraph(s).
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
 
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe 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
Examples
Format paragraph as a heading
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Heading Text\nRegular paragraph text.");// Format just the first paragraph as a headingrange.formatParagraph({ index: 0, length: 12 }, // Only need to include part of the paragraph{fontSize: 24,fontWeight: 'bold',textAlign: 'center'});
Create a bulleted list
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();const text = "Item 1\nItem 2\nItem 3";range.appendText(text);// Format all paragraphs as a bulleted listrange.formatParagraph({ index: 0, length: text.length },{listLevel: 1,listMarker: 'disc'});
formatTextfunctionFormats a region of text with inline formatting properties.
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingInlineFormattingThe formatting to apply to the text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
void
Examples
Format specific words in a paragraph
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains important information.");// Format just the word "important"range.formatText({ index: 16, length: 9 },{fontWeight: 'bold',color: '#FF0000'});
Add a link to text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Visit our website for more information.");// Add a link to "our website"range.formatText({ index: 6, length: 11 },{link: "https://www.example.com",decoration: 'underline',color: '#0066CC'});
appendTextfunctionAppends the specified characters to the end of the range.
Parameters
charactersstringThe characters to append to the richtext range.
formattingInlineFormattingOptional formatting to apply to the appended text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsA segment of a richtext range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Append plain text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph. ");// Append more text to the existing contentconst result = range.appendText("This is additional text.");// The bounds of the newly added text are returned// Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 }
Append formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text followed by ");// Append formatted textrange.appendText("bold red text", {fontWeight: 'bold',color: '#FF0000'});// Append a new paragraphrange.appendText("\nThis is a new paragraph.");
replaceTextfunctionReplaces a region of text with the specified characters.
Parameters
boundsBoundsThe segment of the range to replace.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
charactersstringThe replacement characters.
formattingInlineFormattingThe formatting to apply to the replaced text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsThe bounds of the replacement characters within the updated range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Replace text while maintaining some formatting
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text needs correction.");// Replace "needs correction" with "is correct"const result = range.replaceText({ index: 10, length: 16 },"is correct");// The bounds of the replaced text are returned// Do something with the bounds - result.bounds, e.g. { index: 10, length: 10 }
Replace text with formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Regular text that needs emphasis.");// Replace "needs emphasis" with formatted textrange.replaceText({ index: 17, length: 15 },"is important",{fontWeight: 'bold',fontStyle: 'italic',color: '#0066CC'});
readPlaintextfunctionReturns the current state of the richtext as plaintext.
Returns
string
Examples
Extract plain text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph.\n", { fontWeight: 'bold' });range.appendText("Second paragraph with formatting.", { color: '#FF0000' });// Get plain text content without formattingconst plainText = range.readPlaintext();// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
Search within text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains a searchable term.");// Search for a specific wordconst plainText = range.readPlaintext();const searchTerm = "searchable";const index = plainText.indexOf(searchTerm);if (index !== -1) {// Format the found termrange.formatText({ index, length: searchTerm.length },{ fontWeight: 'bold', decoration: 'underline' });}
readTextRegionsfunctionReturns 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
textstringThe plaintext content of the region.
formattingPartial<RichtextFormatting>The formatting of the region.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe 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"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
 
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe 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"
Examples
Get text with formatting information
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text ", {});range.appendText("bold text", { fontWeight: 'bold' });range.appendText(" and ", {});range.appendText("red text", { color: '#FF0000' });// Get formatted regionsconst regions = range.readTextRegions();// Do something with the regions, e.g.// [// { text: "Normal text ", formatting: {} },// { text: "bold text", formatting: { fontWeight: 'bold' } },// { text: " and ", formatting: {} },// { text: "red text", formatting: { color: '#FF0000' } }// ]
Analyze formatting variations
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Mixed ", {});range.appendText("formatted ", { fontWeight: 'bold' });range.appendText("text", { color: '#0066CC' });// Analyze formatting variationsconst regions = range.readTextRegions();const formattingTypes = regions.map(region => {const formatting = region.formatting || {};return {text: region.text,hasWeight: !!formatting.fontWeight,hasColor: !!formatting.color};});
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
 
Minimum: -32768
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
widthnumberThe width of the element, in pixels.
Minimum: 0
Maximum: 32767
Returns
Promise<void>