editContent

API reference for the editContent method.
This version of the 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.

Reads and edits content from the user's design.

Parameters

optionsobject
Required

Options for configuring how a design is read. Must specify a content type.

targetstring
Required

The only valid value is "current_page".

contentTypeT
Required

Available values:

  • "richtext"
  • "fill"
callbackfunction
Required

A callback that receives a session for editing.

Parameters

sessionobject
Required

A 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 content
const 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 design
await session.sync();
}
}
);
TYPESCRIPT

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 content
for (const range of session.contents) {
// Skip if the content has been deleted
if (range.deleted) continue;
// Get the text content
const text = range.readPlaintext();
if (text.length === 0) continue;
// Apply consistent formatting
range.formatParagraph(
{ index: 0, length: text.length },
{
fontRef: 'YOUR_FONT_REF',
fontSize: 16,
textAlign: 'start'
}
);
}
// Sync all changes back to the design
await session.sync();
}
);
TYPESCRIPT

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 changes
for (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
}
);
TYPESCRIPT
contentsRichtextContentRange[]Read-only
Required

Richtext content in the design.

deletedbooleanRead-only
Required

Indicates whether the object containing this richtext range has been deleted.

formatParagraphfunction
Required

Formats all of the paragraphs that overlap the given bounds.

  • The \n character indicates the end of a paragraph.
  • All paragraphs that overlap the provided bounds will be formatted in their entirety.

Parameters

boundsBounds
Required

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

indexnumber
Required

The starting position of the segment.

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

lengthnumber
Required

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

formattingRichtextFormatting
Required

The formatting to apply to the paragraph(s).

colorstring
Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
Optional

The 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"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRef
Optional

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

fontSizenumber
Optional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
Optional

The list indentation level of the paragraph.

listMarkerstring
Optional

The appearance of list item markers.

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

Default value: "none"

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 heading
range.formatParagraph(
{ index: 0, length: 12 }, // Only need to include part of the paragraph
{
fontSize: 24,
fontWeight: 'bold',
textAlign: 'center'
}
);
TYPESCRIPT

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 list
range.formatParagraph(
{ index: 0, length: text.length },
{
listLevel: 1,
listMarker: 'disc'
}
);
TYPESCRIPT
formatTextfunction
Required

Formats a region of text with inline formatting properties.

Parameters

boundsBounds
Required

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

indexnumber
Required

The starting position of the segment.

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

lengthnumber
Required

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

formattingInlineFormatting
Required

The formatting to apply to the text.

colorstring
Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
Optional

The 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"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

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'
}
);
TYPESCRIPT

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'
}
);
TYPESCRIPT
appendTextfunction
Required

Appends the specified characters to the end of the range.

Parameters

charactersstring
Required

The characters to append to the richtext range.

formattingInlineFormatting
Optional

Optional formatting to apply to the appended text.

colorstring
Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
Optional

The 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"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

indexnumber

The starting position of the segment.

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

lengthnumber

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

Examples

Append plain text

import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("First paragraph. ");
// Append more text to the existing content
const 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 }
TYPESCRIPT

Append formatted text

import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("Normal text followed by ");
// Append formatted text
range.appendText("bold red text", {
fontWeight: 'bold',
color: '#FF0000'
});
// Append a new paragraph
range.appendText("\nThis is a new paragraph.");
TYPESCRIPT
replaceTextfunction
Required

Replaces a region of text with the specified characters.

Parameters

boundsBounds
Required

The segment of the range to replace.

indexnumber
Required

The starting position of the segment.

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

lengthnumber
Required

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

charactersstring
Required

The replacement characters.

formattingInlineFormatting
Optional

The formatting to apply to the replaced text.

colorstring
Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
Optional

The 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"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

indexnumber

The starting position of the segment.

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

lengthnumber

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

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 }
TYPESCRIPT

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 text
range.replaceText(
{ index: 17, length: 15 },
"is important",
{
fontWeight: 'bold',
fontStyle: 'italic',
color: '#0066CC'
}
);
TYPESCRIPT
readPlaintextfunction
Required

Returns 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 formatting
const plainText = range.readPlaintext();
// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
TYPESCRIPT

Search within text content

import { createRichtextRange } from "@canva/design";
const range = createRichtextRange();
range.appendText("This text contains a searchable term.");
// Search for a specific word
const plainText = range.readPlaintext();
const searchTerm = "searchable";
const index = plainText.indexOf(searchTerm);
if (index !== -1) {
// Format the found term
range.formatText(
{ index, length: searchTerm.length },
{ fontWeight: 'bold', decoration: 'underline' }
);
}
TYPESCRIPT
readTextRegionsfunction
Required

Returns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.

Returns

textstring

The plaintext content of the region.

formattingPartial<RichtextFormatting>
Optional

The formatting of the region.

colorstring
Optional

The color of the text as a hex code.

The hex code must include all six characters and be prefixed with a # symbol.

Example

"#ff0099"
TS
fontWeightFontWeight
Optional

The 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"
fontStylestring
Optional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstring
Optional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstring
Optional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRef
Optional

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

fontSizenumber
Optional

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.

Minimum: 1

Maximum: 100

textAlignstring
Optional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumber
Optional

The list indentation level of the paragraph.

listMarkerstring
Optional

The appearance of list item markers.

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

Default value: "none"

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 regions
const 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' } }
// ]
TYPESCRIPT

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 variations
const regions = range.readTextRegions();
const formattingTypes = regions.map(region => {
const formatting = region.formatting || {};
return {
text: region.text,
hasWeight: !!formatting.fontWeight,
hasColor: !!formatting.color
};
});
TYPESCRIPT
syncfunction
Required

Saves 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 content
range.appendText(" - Modified by app");
try {
// Save changes back to the design
await session.sync();
} catch (error) {
console.error('Failed to sync changes:', error);
}
}
}
);
TYPESCRIPT

Session for reading and updating fill content in a user's design.

contentsFillContent[]Read-only
Required

Fill content in the design.

typestring
Required

The only valid value is "image".

refImageRef
Required

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

deletedboolean
Required

Indicates whether the object containing this fill has been deleted.

altTextAltText
Optional

A description of the image content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
typestring
Required

The only valid value is "video".

refVideoRef
Required

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

deletedboolean
Required

Indicates whether the object containing this fill has been deleted.

altTextAltText
Optional

A description of the video content.

Use undefined for content with no description.

textstring
Required

The text content.

decorativeboolean | undefined
Required

Indicates where the alternative text should be displayed.

  • If true, the alternative text will only be displayed in the editor.
  • If false, the alternative text will be displayed in the editor and in view-only mode.
syncfunction
Required
  • 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>