Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
API reference

openDesign

API reference for the openDesign 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 a specified part of the user's design and returns all elements in that part.

Parameters

optionsDesignContextOptionsRequired

Options for configuring which part of a design to read.

typestringRequired

The type of context.

This must be "current_page".

callbackfunctionRequired

Parameters

draftCurrentPageResultRequired

The result of reading part of a design when the context is the current page.

savefunctionRequired
  • Any changes to the draft are only reflected in the design after this method is called.
  • Once this method is called, further changes to the draft are not possible.

Returns

Promise<void>

pageFixedPageRequired

The current page of the design.

typestringRequired

The type of page.

This must be "fixed".

lockedbooleanRequired

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

dimensionsundefined | DimensionsRequired

The dimensions of the page. dimensions is undefined for whiteboard pages.

widthnumberRequired

A width, in pixels.

heightnumberRequired

A height, in pixels.

backgroundundefined | FillRequired

The background of the page. background is undefined for whiteboard pages.

mediaundefined | MediaFillRequired

The media fill for the path, if any.

An image that fills the interior of a path.

typestringRequired

The type of media.

This must be "image".

imageRefImageRefRequired

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

flipXbooleanRequired

If true, the image is flipped horizontally.

flipYbooleanRequired

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestringRequired

The type of media.

This must be "video".

videoRefVideoRefRequired

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

flipXbooleanRequired

If true, the video is flipped horizontally.

flipYbooleanRequired

If true, the video is flipped vertically.

colorundefined | ColorFillRequired

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestringRequired

The type of color.

This must be "solid".

colorstringRequired

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestringRequired

The type of element.

This must be "unsupported".

elementsList<FixedElement>Required

The elements on the page.

Elements are rendered in the order they appear in the list. Later elements appear on top of earlier ones.

countfunctionRequired

Returns

The number of items.

number

toArrayfunctionRequired

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunctionRequired

Parameters

callbackForEachCallback<T>Required

The function to run for each item.

Parameters

itemTRequired

The current item in the list.

indexnumberRequired

The index of the current item.

Returns

void

Returns

void

filterfunctionRequired

Parameters

filterFilterPredicate<T>Required

A function that tests each item. Returns true to keep the item.

Parameters

itemTRequired

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

insertBeforefunctionRequired

Parameters

refundefined | TRequired

The existing item to place the new item before. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

itemTRequired

The item to add. A copy of this item will be inserted.

Returns

The added item, or undefined if the operation failed.

undefined | T

insertAfterfunctionRequired

Parameters

refundefined | TRequired

The existing item to place the new item after. If ref is undefined, the new item is added at the end of the list. If ref does not exist in the list, the operation fails.

itemTRequired

The item to add. A copy of this item will be inserted.

Returns

The added item, or undefined if the operation failed.

undefined | T

moveBeforefunctionRequired

Parameters

refundefined | TRequired

The existing item to move the item before. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

itemTRequired

The item to move. The operation fails if the item is not already in the list.

Returns

void

moveAfterfunctionRequired

Parameters

refundefined | TRequired

The existing item to move the item after. If ref is undefined, the item is moved to the end of the list. If ref does not exist in the list, the operation fails.

itemTRequired

The item to move. The operation fails if the item is not already in the list.

Returns

void

deletefunctionRequired

Parameters

itemTRequired

The item to remove from the list.

Returns

void

helpersobjectRequired
elementBuilderElementBuilderRequired

Provides methods for creating elements.

These methods don't add the elements to the design. They only return elements that can be added to a design, such as with the insertAfter method.

createRectElementfunctionRequired

Parameters

optsCreateRectElementOptsRequired

Options for creating the rect element.

fillFillOptsOptional
colorColorFillOpts
Sometimes required
mediaMediaFillOpts
Sometimes required

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

strokeStrokeOptsOptional
colorColorFillOptsRequired
weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

Returns

An element that renders a rectangle.

The rectangle can be filled with image content, video content, or a solid color.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "rect".

fillFill

The appearance of the rectangle's interior.

mediaundefined | MediaFill

The media fill for the path, if any.

An image that fills the interior of a path.

typestring

The type of media.

This must be "image".

imageRefImageRef

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

flipXboolean

If true, the image is flipped horizontally.

flipYboolean

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestring

The type of media.

This must be "video".

videoRefVideoRef

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

flipXboolean

If true, the video is flipped horizontally.

flipYboolean

If true, the video is flipped vertically.

colorundefined | ColorFill

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

strokeStroke

The outline of the rectangle.

weightnumber

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorColorFill

The color of the stroke.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

createShapeElementfunctionRequired

Parameters

optsCreateShapeElementOptsRequired

Options for creating the shape element.

pathsPathOpts[]Required
fillFillOptsOptional
colorColorFillOpts
Sometimes required
mediaMediaFillOpts
Sometimes required

Options for creating an image fill in the element builder

Options for creating a video fill in the element builder

strokeStrokeOptsOptional
colorColorFillOptsRequired
weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

dstringRequired

The shape of the path.

This is similar to the d attribute of an SVG's path element, with some limitations:

  • Must start with an M command.
  • Only one M command is allowed.
  • Q and T commands are not permitted.
  • The path must be closed using a Z command or matching start and end coordinates.

Returns

An element that renders a vector shape.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "shape".

viewBoxAlignedBox

The scale and cropping of the shape.

topnumber

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

leftnumber

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

widthnumber

The width of the view box, in pixels.

heightnumber

The height of the view box, in pixels.

pathsReadableList<Path>

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.
countfunction

Returns

The number of items.

number

toArrayfunction

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunction

Parameters

callbackForEachCallback<T>Required

The function to run for each item.

Parameters

itemTRequired

The current item in the list.

indexnumberRequired

The index of the current item.

Returns

void

Returns

void

filterfunction

Parameters

filterFilterPredicate<T>Required

A function that tests each item. Returns true to keep the item.

Parameters

itemTRequired

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

createEmbedElementfunctionRequired

Parameters

optsCreateEmbedElementOptsRequired

Options for creating the embed element.

Returns

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

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "embed".

urlstring

The URL of the rich media.

This URL must be supported by the Iframely API.

createTextElementfunctionRequired

Parameters

optsCreateTextElementOptsRequired

Options for creating the text element.

Returns

An element that renders text content.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "text".

textRichtextRange

The text content.

formatParagraphfunction

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

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

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

fontSizenumberOptional

The size of the text, in pixels.

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

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

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

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

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.

createRichtextRangefunctionRequired

Returns

Provides methods for interacting with a range of formatted text.

formatParagraphfunction

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

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

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

fontSizenumberOptional

The size of the text, in pixels.

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

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

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

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

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.

cloneElementfunctionRequired

Parameters

elementobjectRequired

An element that renders a rectangle.

The rectangle can be filled with image content, video content, or a solid color.

widthnumberRequired

A width, in pixels.

heightnumberRequired

A height, in pixels.

lockedbooleanRequired

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

topnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

typestringRequired

The type of content.

This must be "rect".

fillFillRequired

The appearance of the rectangle's interior.

mediaundefined | MediaFillRequired

The media fill for the path, if any.

An image that fills the interior of a path.

typestringRequired

The type of media.

This must be "image".

imageRefImageRefRequired

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

flipXbooleanRequired

If true, the image is flipped horizontally.

flipYbooleanRequired

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestringRequired

The type of media.

This must be "video".

videoRefVideoRefRequired

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

flipXbooleanRequired

If true, the video is flipped horizontally.

flipYbooleanRequired

If true, the video is flipped vertically.

colorundefined | ColorFillRequired

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestringRequired

The type of color.

This must be "solid".

colorstringRequired

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestringRequired

The type of element.

This must be "unsupported".

strokeStrokeRequired

The outline of the rectangle.

weightnumberRequired

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorColorFillRequired

The color of the stroke.

A solid color that fills the interior of a path.

typestringRequired

The type of color.

This must be "solid".

colorstringRequired

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestringRequired

The type of element.

This must be "unsupported".

An element that renders a vector shape.

widthnumberRequired

A width, in pixels.

heightnumberRequired

A height, in pixels.

lockedbooleanRequired

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

topnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

typestringRequired

The type of content.

This must be "shape".

viewBoxAlignedBoxRequired

The scale and cropping of the shape.

topnumberRequired

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

leftnumberRequired

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

widthnumberRequired

The width of the view box, in pixels.

heightnumberRequired

The height of the view box, in pixels.

pathsReadableList<Path>Required

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.
countfunctionRequired

Returns

The number of items.

number

toArrayfunctionRequired

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunctionRequired

Parameters

callbackForEachCallback<T>Required

The function to run for each item.

Parameters

itemTRequired

The current item in the list.

indexnumberRequired

The index of the current item.

Returns

void

Returns

void

filterfunctionRequired

Parameters

filterFilterPredicate<T>Required

A function that tests each item. Returns true to keep the item.

Parameters

itemTRequired

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

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

widthnumberRequired

A width, in pixels.

heightnumberRequired

A height, in pixels.

lockedbooleanRequired

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

topnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

typestringRequired

The type of content.

This must be "embed".

urlstringRequired

The URL of the rich media.

This URL must be supported by the Iframely API.

An element that renders text content.

widthnumberRequired

A width, in pixels.

heightnumberRequired

A height, in pixels.

lockedbooleanRequired

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

topnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

leftnumberRequired

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

  • The pixels are relative to their container.

Minimum: -32768

Maximum: 32767

rotationnumberRequired

A rotation, in degrees.

Minimum: -180

Maximum: 180

transparencynumberRequired

Transparency as a percentage.

Minimum: 0

Maximum: 1

typestringRequired

The type of content.

This must be "text".

textRichtextRangeRequired

The text content.

formatParagraphfunctionRequired

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

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

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

fontSizenumberOptional

The size of the text, in pixels.

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

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

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

formatTextfunctionRequired

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunctionRequired

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

replaceTextfunctionRequired

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

readPlaintextfunctionRequired

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunctionRequired

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.

Returns

An element that renders a rectangle.

The rectangle can be filled with image content, video content, or a solid color.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "rect".

fillFill

The appearance of the rectangle's interior.

mediaundefined | MediaFill

The media fill for the path, if any.

An image that fills the interior of a path.

typestring

The type of media.

This must be "image".

imageRefImageRef

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

flipXboolean

If true, the image is flipped horizontally.

flipYboolean

If true, the image is flipped vertically.

A video that fills the interior of a path.

typestring

The type of media.

This must be "video".

videoRefVideoRef

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

flipXboolean

If true, the video is flipped horizontally.

flipYboolean

If true, the video is flipped vertically.

colorundefined | ColorFill

The color fill for the path, if any.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

strokeStroke

The outline of the rectangle.

weightnumber

The weight (thickness) of the stroke.

Minimum: 0

Maximum: 100

colorColorFill

The color of the stroke.

A solid color that fills the interior of a path.

typestring

The type of color.

This must be "solid".

colorstring

The color of the fill, as a hex code.

  • Must be six characters long.
  • Must start with a #.
  • Must use lowercase letters.

Represents an element that's not supported by the Apps SDK.

typestring

The type of element.

This must be "unsupported".

An element that renders a vector shape.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "shape".

viewBoxAlignedBox

The scale and cropping of the shape.

topnumber

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

leftnumber

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

widthnumber

The width of the view box, in pixels.

heightnumber

The height of the view box, in pixels.

pathsReadableList<Path>

The paths that define the structure of the shape.

  • Must have between 1 and 30 paths.
  • Total size of all paths must not exceed 2kb.
  • Maximum of 6 unique fill colors across all paths.
countfunction

Returns

The number of items.

number

toArrayfunction

Returns

An array containing all items. The items are the same as in the list.

readonly T[]

forEachfunction

Parameters

callbackForEachCallback<T>Required

The function to run for each item.

Parameters

itemTRequired

The current item in the list.

indexnumberRequired

The index of the current item.

Returns

void

Returns

void

filterfunction

Parameters

filterFilterPredicate<T>Required

A function that tests each item. Returns true to keep the item.

Parameters

itemTRequired

The item to test.

Returns

true if the item should be included, otherwise false.

boolean

Returns

An array of items that passed the test.

readonly T[]

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

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "embed".

urlstring

The URL of the rich media.

This URL must be supported by the Iframely API.

An element that renders text content.

widthnumber

A width, in pixels.

heightnumber

A height, in pixels.

lockedboolean

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

typestring

The type of content.

This must be "text".

textRichtextRange

The text content.

formatParagraphfunction

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

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingRichtextFormattingRequired

The formatting to apply to the paragraph(s).

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"
fontRefFontRefOptional

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

fontSizenumberOptional

The size of the text, in pixels.

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

Minimum: 1

Maximum: 100

textAlignstringOptional

The alignment of the text.

Default value: "start"

Available values:

  • "start"
  • "center"
  • "end"
  • "justify"
listLevelnumberOptional

The list indentation level of the paragraph.

listMarkerstringOptional

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

formatTextfunction

Formats a region of text with inline formatting properties.

Parameters

boundsBoundsRequired

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

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

formattingInlineFormattingRequired

The formatting to apply to the text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

The strikethrough of the text.

Default value: "none"

Available values:

  • "none"
  • "strikethrough"

Returns

void

appendTextfunction

Appends the specified characters to the end of the range.

Parameters

charactersstringRequired

The characters to append to the richtext range.

formattingInlineFormattingOptional

Options for formatting inline richtext.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

replaceTextfunction

Replaces a region of text with the specified characters.

Parameters

boundsBoundsRequired

The segment of the range to replace.

indexnumberRequired

The starting position of the segment.

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

lengthnumberRequired

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

charactersstringRequired

The replacement characters.

formattingInlineFormattingOptional

The formatting to apply to the replaced text.

colorstringOptional

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
fontWeightFontWeightOptional

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"
fontStylestringOptional

The style of the font.

Default value: "normal"

Available values:

  • "normal"
  • "italic"
decorationstringOptional

The decoration of the text.

Default value: "none"

Available values:

  • "none"
  • "underline"
strikethroughstringOptional

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.

readPlaintextfunction

Returns the current state of the richtext as plaintext.

Returns

string

readTextRegionsfunction

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.

Returns

void or Promise<void>

Returns

Promise<void>