API reference
Intents
Intents: Asset
Intents: Content
Intents: Design
Intents: Test
Platform: Test

PageHelpers

API reference for the PageHelpers type.

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

groupfunction
Required

Group specified elements.

Parameters

optsAsyncOperationsGroupOpts
Required

Options for grouping elements.

elementsobject[]
Required

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-only
Required

The element type

The only valid value is "rect".

fillFillRead-only
Required

Describes 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-only
Required

The outline of the rectangle.

For more information, see Stroke.

widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency as a percentage.

Minimum: 0

Maximum: 1

An element that renders a vector shape.

typestringRead-only
Required

The type of content.

The only valid value is "shape".

viewBoxAlignedBoxRead-only
Required

The scale and cropping of the shape.

topnumberRead-only
Required

The distance of the shape from the top edge of the element, in pixels.

leftnumberRead-only
Required

The distance of the shape from the left edge of the element, in pixels.

widthnumberRead-only
Required

The width of the view box, in pixels.

heightnumberRead-only
Required

The height of the view box, in pixels.

pathsReadableList<Path>Read-only
Required

The paths that define the structure of the shape.

For more information, see ReadableList and Path.

widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency as a percentage.

Minimum: 0

Maximum: 1

An element that embeds rich media, such as a YouTube video.

typestringRead-only
Required

The type of content.

The only valid value is "embed".

urlstringRead-only
Required

The URL of the rich media.

This URL must be supported by the Iframely API.

widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency as a percentage.

Minimum: 0

Maximum: 1

An element that renders text content.

typestringRead-only
Required

The only valid value is "text".

textRichtextRangeRead-only
Required

Provides methods for interacting with a range of formatted text.

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: 1000

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"
lineHeightEmnumber
Optional

The line height of the paragraph, relative to the font size expressed in Em.

Minimum: 0.5

Maximum: 2.5

Default value: 1.4

letterSpacingEmnumber
Optional

The 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 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: 1000

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"
lineHeightEmnumber
Optional

The line height of the paragraph, relative to the font size expressed in Em.

Minimum: 0.5

Maximum: 2.5

Default value: 1.4

letterSpacingEmnumber
Optional

The 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 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
widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency 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-only

The type of content.

The only valid value is "group".

contentsReadableList<GroupContentElement>Read-only

The elements that exist within the group.

For more information, see ReadableList and GroupContentElement.

widthnumberRead-only

A width, in pixels.

heightnumberRead-only

A height, in pixels.

idElementIdRead-only

The ID of the element.

lockedbooleanRead-only

If true, the element is locked and cannot be modified.

topnumber

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber

Transparency as a percentage.

Minimum: 0

Maximum: 1

ungroupfunction
Required

Ungroup a group element.

Parameters

optsAsyncOperationsUngroupOpts
Required

Options for ungrouping a group element.

elementGroupElement
Required

Group element to be ungroup.

typestringRead-only
Required

The type of content.

The only valid value is "group".

contentsReadableList<GroupContentElement>Read-only
Required

The elements that exist within the group.

For more information, see ReadableList and GroupContentElement.

widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency 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.ElementStateBuilder
Required

Build 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.

getDataFieldForfunction
Required

Returns a DataFieldAccessor for reading or updating the data-field mapping of a target on the current page.

Parameters

optsGetDataFieldForOptions
Required

Identifies the target (a text element, rect element, or editable shape-path fill) to read or update.

targetobject
Required

The target to read or update the data-field mapping for. Must belong to the current page.

  • A DesignEditing.TextElement connects to a text field.
  • A DesignEditing.RectElement connects its fill to a fill field.
  • A DesignEditing.PathFillWithEditableMedia connects that shape-path fill to a fill field. Pass the specific fill to disambiguate a shape with multiple paths.

An element that renders text content.

typestringRead-only
Required

The only valid value is "text".

textRichtextRangeRead-only
Required

Provides methods for interacting with a range of formatted text.

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: 1000

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"
lineHeightEmnumber
Optional

The line height of the paragraph, relative to the font size expressed in Em.

Minimum: 0.5

Maximum: 2.5

Default value: 1.4

letterSpacingEmnumber
Optional

The 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 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: 1000

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"
lineHeightEmnumber
Optional

The line height of the paragraph, relative to the font size expressed in Em.

Minimum: 0.5

Maximum: 2.5

Default value: 1.4

letterSpacingEmnumber
Optional

The 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 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
widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency 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-only
Required

The element type

The only valid value is "rect".

fillFillRead-only
Required

Describes 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-only
Required

The outline of the rectangle.

For more information, see Stroke.

widthnumberRead-only
Required

A width, in pixels.

heightnumberRead-only
Required

A height, in pixels.

idElementIdRead-only
Required

The ID of the element.

lockedbooleanRead-only
Required

If true, the element is locked and cannot be modified.

topnumber
Required

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumber
Required

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumber
Required

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumber
Required

Transparency as a percentage.

Minimum: 0

Maximum: 1

isMediaEditablebooleanRead-only
Required

The only valid value is true.

mediaContainerobjectRead-only
Required

A media fill, if any.

setfunction
Required

Parameters

stateMediaFillState | undefined
Required

A state that creates an image fill.

typestringRead-only
Required

The type of media.

The only valid value is "image".

imageRefImageRefRead-only
Required

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

flipXboolean
Required

If true, the image is flipped horizontally.

flipYboolean
Required

If true, the image is flipped vertically.

A state that creates a video fill.

typestringRead-only
Required

The type of media.

The only valid value is "video".

videoRefVideoRefRead-only
Required

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

flipXboolean
Required

If true, the video is flipped horizontally.

flipYboolean
Required

If true, the video is flipped vertically.

Returns

void

refMediaFill | undefined
Required

An image that fills the interior of a media.

typestringRead-only
Required

The type of media.

The only valid value is "image".

imageRefImageRefRead-only
Required

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

flipXboolean
Required

If true, the image is flipped horizontally.

flipYboolean
Required

If true, the image is flipped vertically.

A video that fills the interior of a media.

typestringRead-only
Required

The type of media.

The only valid value is "video".

videoRefVideoRefRead-only
Required

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

flipXboolean
Required

If true, the video is flipped horizontally.

flipYboolean
Required

If true, the video is flipped vertically.

colorContainerobjectRead-only
Required

A color fill, if any.

setfunction
Required

Parameters

stateSolidFillState | undefined
Required
typestringRead-only
Required

The type of color.

The only valid value is "solid".

colorstring
Required

The 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"
TS

Returns

void

refColorFill | undefined
Required

A solid color that fills an interior.

typestringRead-only
Required

The type of color.

The only valid value is "solid".

colorstring
Required

The 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"
TS

Represents something that's not supported by the Apps SDK.

typestringRead-only
Required

The 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, set resolves to { status: "incompatible_data_field_type" }.
  • If no compatible field exists and the dataset definition has reached the field limit, set resolves 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.