PageHelpers
This 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.
Helpers for use with supported pages.
Not applicable to unsupported pages.
Type declaration
groupfunctionGroup specified elements.
Parameters
optsAsyncOperationsGroupOptsOptions for grouping elements.
elementsobject[]Elements to be grouped.
An element that renders a rectangle.
The rectangle can be filled with image content, video content, or a solid color.
typestringRead-onlyThe element type
The only valid value is "rect".
fillFillRead-onlyDescribes how a fill is filled with color or media.
If both media and color are defined, media takes precedence.
For more information, see Fill.
strokeStrokeRead-onlyThe outline of the rectangle.
For more information, see Stroke.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
An element that renders a vector shape.
typestringRead-onlyThe type of content.
The only valid value is "shape".
viewBoxAlignedBoxRead-onlyThe scale and cropping of the shape.
topnumberRead-onlyThe distance of the shape from the top edge of the element, in pixels.
leftnumberRead-onlyThe distance of the shape from the left edge of the element, in pixels.
widthnumberRead-onlyThe width of the view box, in pixels.
heightnumberRead-onlyThe height of the view box, in pixels.
pathsReadableList<Path>Read-onlyThe paths that define the structure of the shape.
For more information, see ReadableList and Path.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
An element that embeds rich media, such as a YouTube video.
typestringRead-onlyThe type of content.
The only valid value is "embed".
urlstringRead-onlyThe URL of the rich media.
This URL must be supported by the Iframely API.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
An element that renders text content.
typestringRead-onlyThe only valid value is "text".
textRichtextRangeRead-onlyProvides methods for interacting with a range of formatted text.
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: 1000
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"
lineHeightEmnumberThe line height of the paragraph, relative to the font size expressed in Em.
Minimum: 0.5
Maximum: 2.5
Default value: 1.4
letterSpacingEmnumberThe spacing between characters, relative to the font size expressed in Em.
- In the Canva editor, this number is shown as a multiple of 1000.
Minimum: -0.2
Maximum: 0.8
Default value: 0
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: 1000
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"
lineHeightEmnumberThe line height of the paragraph, relative to the font size expressed in Em.
Minimum: 0.5
Maximum: 2.5
Default value: 1.4
letterSpacingEmnumberThe spacing between characters, relative to the font size expressed in Em.
- In the Canva editor, this number is shown as a multiple of 1000.
Minimum: -0.2
Maximum: 0.8
Default value: 0
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};});
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
Returns
a new group element containing all the given elements. This is a Promise that resolves with the following object:
typestringRead-onlyThe type of content.
The only valid value is "group".
contentsReadableList<GroupContentElement>Read-onlyThe elements that exist within the group.
For more information, see ReadableList and GroupContentElement.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
ungroupfunctionUngroup a group element.
Parameters
optsAsyncOperationsUngroupOptsOptions for ungrouping a group element.
elementGroupElementGroup element to be ungroup.
typestringRead-onlyThe type of content.
The only valid value is "group".
contentsReadableList<GroupContentElement>Read-onlyThe elements that exist within the group.
For more information, see ReadableList and GroupContentElement.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
Returns
new elements that are ungrouped from the given group. This is a Promise that resolves with a AbsoluteElement[] object.
For more information, see AbsoluteElement.
elementStateBuilderDesignEditing.ElementStateBuilderBuild an element state that can be used to create an element with the insert methods of
the page's element list
For more information, see ElementStateBuilder.
getDataFieldForfunctionReturns a DataFieldAccessor for reading or updating the data-field mapping of a target on the current page.
Parameters
optsGetDataFieldForOptionsIdentifies the target (a text element, rect element, or editable shape-path fill) to read or update.
targetobjectThe target to read or update the data-field mapping for. Must belong to the current page.
- A DesignEditing.TextElement connects to a
textfield. - A DesignEditing.RectElement connects its fill to a
fillfield. - A DesignEditing.PathFillWithEditableMedia connects that shape-path fill to a
fillfield. Pass the specific fill to disambiguate a shape with multiple paths.
An element that renders text content.
typestringRead-onlyThe only valid value is "text".
textRichtextRangeRead-onlyProvides methods for interacting with a range of formatted text.
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: 1000
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"
lineHeightEmnumberThe line height of the paragraph, relative to the font size expressed in Em.
Minimum: 0.5
Maximum: 2.5
Default value: 1.4
letterSpacingEmnumberThe spacing between characters, relative to the font size expressed in Em.
- In the Canva editor, this number is shown as a multiple of 1000.
Minimum: -0.2
Maximum: 0.8
Default value: 0
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: 1000
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"
lineHeightEmnumberThe line height of the paragraph, relative to the font size expressed in Em.
Minimum: 0.5
Maximum: 2.5
Default value: 1.4
letterSpacingEmnumberThe spacing between characters, relative to the font size expressed in Em.
- In the Canva editor, this number is shown as a multiple of 1000.
Minimum: -0.2
Maximum: 0.8
Default value: 0
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};});
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
An element that renders a rectangle.
The rectangle can be filled with image content, video content, or a solid color.
typestringRead-onlyThe element type
The only valid value is "rect".
fillFillRead-onlyDescribes how a fill is filled with color or media.
If both media and color are defined, media takes precedence.
For more information, see Fill.
strokeStrokeRead-onlyThe outline of the rectangle.
For more information, see Stroke.
widthnumberRead-onlyA width, in pixels.
heightnumberRead-onlyA height, in pixels.
idElementIdRead-onlyThe ID of the element.
lockedbooleanRead-onlyIf true, the element is locked and cannot be modified.
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
transparencynumberTransparency as a percentage.
Minimum: 0
Maximum: 1
isMediaEditablebooleanRead-onlyThe only valid value is true.
mediaContainerobjectRead-onlyA media fill, if any.
setfunctionParameters
stateMediaFillState | undefinedA state that creates an image fill.
typestringRead-onlyThe type of media.
The only valid value is "image".
imageRefImageRefRead-onlyA unique identifier that points to an image asset in Canva's backend.
flipXbooleanIf true, the image is flipped horizontally.
flipYbooleanIf true, the image is flipped vertically.
A state that creates a video fill.
typestringRead-onlyThe type of media.
The only valid value is "video".
videoRefVideoRefRead-onlyA unique identifier that points to a video asset in Canva's backend.
flipXbooleanIf true, the video is flipped horizontally.
flipYbooleanIf true, the video is flipped vertically.
Returns
void
refMediaFill | undefinedAn image that fills the interior of a media.
typestringRead-onlyThe type of media.
The only valid value is "image".
imageRefImageRefRead-onlyA unique identifier that points to an image asset in Canva's backend.
flipXbooleanIf true, the image is flipped horizontally.
flipYbooleanIf true, the image is flipped vertically.
A video that fills the interior of a media.
typestringRead-onlyThe type of media.
The only valid value is "video".
videoRefVideoRefRead-onlyA unique identifier that points to a video asset in Canva's backend.
flipXbooleanIf true, the video is flipped horizontally.
flipYbooleanIf true, the video is flipped vertically.
colorContainerobjectRead-onlyA color fill, if any.
setfunctionParameters
stateSolidFillState | undefinedtypestringRead-onlyThe type of color.
The only valid value is "solid".
colorstringThe color of the fill.
This must be a valid, six-digit hex code, prefixed with a # symbol.
- Must be six characters long.
- Must start with a
#. - Must use lowercase letters.
Example
"#ff0099"
Returns
void
refColorFill | undefinedA solid color that fills an interior.
typestringRead-onlyThe type of color.
The only valid value is "solid".
colorstringThe color of the fill.
This must be a valid, six-digit hex code, prefixed with a # symbol.
- Must be six characters long.
- Must start with a
#. - Must use lowercase letters.
Example
"#ff0099"
Represents something that's not supported by the Apps SDK.
typestringRead-onlyThe only valid value is "unsupported".
Returns
Reads and updates the data-field mapping of a single target — obtained from DesignEditing.PageHelpers.getDataFieldFor.
Updates the data-field mapping and the dataset definition. Supported targets are text (connected
to a field of type text) and fills (connected to a field of type fill).
When label is present:
- If a field with the same label already exists in the dataset definition and its type is compatible with the target type, the target is connected to that existing field.
- If a field with the same label exists but has a different type,
setresolves to{ status: "incompatible_data_field_type" }. - If no compatible field exists and the dataset definition has reached the field limit,
setresolves to{ status: "data_field_limit_exceeded" }. - Otherwise a new field is added to the dataset definition with a randomly generated id. The field type is inferred from the target type, and the target is connected to it.
When label is Unset:
- The data-field mapping is removed from the target.
- The dataset definition is not cleaned up; unused fields are left in place. Unused fields
continue to count toward the document's data-field limit and may be reused by later calls to
set.
Developer mistakes, such as unsupported targets or invalid fill/parent combinations, throw
CanvaError({ code: "bad_request" }).
getDesignMetadata() only returns committed data fields. Fields staged during the current
openDesign transaction are not visible through getDesignMetadata() until sync() commits the
changes.
For more information, see DataFieldAccessor.