editContent
Reads and edits content from the user's design.
Parameters
optionsobjectOptions for configuring how a design is read. Must specify a content type.
targetstringThe only valid value is "current_page".
contentTypeTAvailable values:
"richtext""fill"
callbackfunctionA callback that receives a session for editing.
Parameters
sessionobjectA callback for reading and updating the requested design content.
Param: session
The result of reading the content in the design.
Examples
Read and update richtext content
import { editContent } from "@canva/design";await editContent({ contentType: 'richtext', target: 'current_page' },async (session) => {// Read the contentconst contents = session.contents;if (contents.length > 0) {const range = contents[0];// Modify the content (e.g., adding text)range.appendText("\nAppended text from app");// Sync changes back to the designawait session.sync();}});
Format all richtext content in the design
import { editContent } from "@canva/design";await editContent({ contentType: 'richtext', target: 'current_page' },async (session) => {// Process each richtext range in the contentfor (const range of session.contents) {// Skip if the content has been deletedif (range.deleted) continue;// Get the text contentconst text = range.readPlaintext();if (text.length === 0) continue;// Apply consistent formattingrange.formatParagraph({ index: 0, length: text.length },{fontRef: 'YOUR_FONT_REF',fontSize: 16,textAlign: 'start'});}// Sync all changes back to the designawait session.sync();});
Modify content without saving changes
import { editContent } from "@canva/design";await editContent({ contentType: 'richtext', target: 'current_page' },async (session) => {// Read and analyze the content without making changesfor (const range of session.contents) {const text = range.readPlaintext();// Do something with the content preview, e.g. `text.substring(0, 50)`// No call to session.sync() means no changes are saved}// Since we're not calling sync(), no changes will be made to the design});
contentsRichtextContentRange[]Read-onlyRichtext content in the design.
deletedbooleanRead-onlyIndicates whether the object containing this richtext range has been deleted.
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};});
syncfunctionSaves any changes made during the session while keeping the transaction open.
- Any changes in the session are only reflected in the design after this method is called.
- Once this method is called, further changes in the session can still be made.
Returns
Promise<void>
Example: Sync changes after modifying content
import { editContent } from "@canva/design";await editContent({ contentType: 'richtext', target: 'current_page' },async (session) => {if (session.contents.length > 0) {const range = session.contents[0];// Make modifications to the contentrange.appendText(" - Modified by app");try {// Save changes back to the designawait session.sync();} catch (error) {console.error('Failed to sync changes:', error);}}});
Session for reading and updating fill content in a user's design.
contentsFillContent[]Read-onlyFill content in the design.
typestringThe only valid value is "image".
refImageRefA unique identifier that points to an image asset in Canva's backend.
deletedbooleanIndicates whether the object containing this fill has been deleted.
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.
typestringThe only valid value is "video".
refVideoRefA unique identifier that points to an video asset in Canva's backend.
deletedbooleanIndicates whether the object containing this fill has been deleted.
altTextAltTextA 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.
syncfunction- Any changes in the session are only reflected in the design after this method is called.
- Once this method is called, further changes in the session can still be made.
Returns
Promise<void>
Returns
void or Promise<void>
Returns
A promise that resolves when editing is complete.
Promise<void>