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

addPage

API reference for the addPage method.
This version of the API is in beta. Beta APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Adds a new page immediately after the currently selected page.

Parameters

optsobject
OPTIONAL

Configuration for the new page to be added.

Properties of opts
elementsElementAtPoint[]
OPTIONAL

Elements to be added to the page

An element that renders image content and has positional properties.

typestring
REQUIRED

The type of element.

This must be "image".

altTextAltText | undefined
REQUIRED

A description of the image content.

Properties of altText
textstring
REQUIRED

The text content.

decorativeboolean | undefined
REQUIRED

Indicates where the alternative text should be displayed.

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

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
dataUrlstring
OPTIONAL

A data URL that contains the image data.

refImageRef
OPTIONAL

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

An element that renders video content and has positional properties.

typestring
REQUIRED

The type of element.

This must be "video".

refVideoRef
REQUIRED

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

altTextAltText | undefined
REQUIRED

A description of the video content.

Properties of altText
textstring
REQUIRED

The text content.

decorativeboolean | undefined
REQUIRED

Indicates where the alternative text should be displayed.

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

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

An element that renders rich media, such as a YouTube video, and has positional properties.

typestring
REQUIRED

The type of element.

This must be "embed".

urlstring
REQUIRED

The URL of the rich media.

This URL must be supported by the Iframely API.

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
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

An element that renders text content and has positional properties.

typestring
REQUIRED

The type of element.

This must be "text".

childrenstring[]
REQUIRED

The text content.

Only the first element in this array is used.

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
fontSizenumber
OPTIONAL

The size of the text.

  • Minimum: 1
  • Maximum: 100

Default Value: 16

textAlignstring
OPTIONAL

The alignment of the text.

Default Value: "start"

The available options include:

  • "start"
  • "center"
  • "end"
  • "justify"
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
fontRefFontRef
OPTIONAL

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

fontWeightFontWeight
OPTIONAL

The weight (thickness) of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the font.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
widthnumber
OPTIONAL

The width of the element, in pixels.

  • Minimum: 0
  • Maximum: 32767

An element that renders a vector shape and has positional properties.

typestring
REQUIRED

The type of element.

This must be "shape".

viewBoxShapeViewBox
REQUIRED

Options for configuring the scale and cropping of the shape.

Properties of viewBox
topnumber
REQUIRED

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

leftnumber
REQUIRED

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

widthnumber
REQUIRED

The width of the view box, in pixels.

heightnumber
REQUIRED

The height of the view box, in pixels.

pathsShapePath[]
REQUIRED

The paths that define the structure of the shape.

  • There must be between 1 and 30 paths (inclusive).
  • The maximum combined size of all paths must not exceed 2kb.
  • The maximum number of unique fill colors across all paths is 6.
Properties of paths
dstring
REQUIRED

The shape of the path.

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

  • The path must start with an M command.
  • The path must not have more than one M command.
  • The path must not use the Q command.
  • The path must be closed, either by:
    • Using a Z command at the end of the path
    • Having the last coordinate match the first coordinate
fillFill
REQUIRED

The appearance of the path's interior.

Properties of fill
dropTargetboolean
OPTIONAL

If true, users can replace a fill by dropping an image or video onto it.

colorstring
OPTIONAL

The color of the fill as a hex code.

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

Example

" #ff0099"
TS
assetobject
OPTIONAL

An image or video to use as the fill.

An image asset that fills a path's interior.

typestring
REQUIRED

The type of fill.

This must be "image".

refImageRef
REQUIRED

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

A video asset that fills a path's interior.

typestring
REQUIRED

The type of fill.

This must be "video".

refVideoRef
REQUIRED

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

strokePathStroke
OPTIONAL

The outline of the path.

Properties of stroke
weightnumber
REQUIRED

The weight (thickness) of the stroke.

  • Minimum: 0
  • Maximum: 100
colorstring
REQUIRED

The color of the stroke as a hex code.

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

Example

"#ff0099"
TS
strokeAlignstring
REQUIRED

The alignment of the stroke.

This must be "inset".

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
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

An element that contains two or more elements and has positional properties.

typestring
REQUIRED

The type of element.

This must be "group".

childrenGroupContentAtPoint[]
REQUIRED

The elements to render within the group.

  • Each element within a group must have dimensions and a position.
  • The dimensions and positions are relative to the dimensions and positions of the group.
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
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

An element that renders richtext content.

This type includes properties for controlling the position and dimensions of the element. It will be positioned and sized relative to its parent container. The parent container may be an app element, or the current page.

typestring
REQUIRED

The type of element.

This must be "richtext".

rangeRichtextRange
REQUIRED

The richtext content.

Properties of range
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.

Properties of bounds
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).

Properties of formatting
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"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"
fontRefFontRef
OPTIONAL

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

fontSizenumber
OPTIONAL

The size of the text, in pixels.

  • In the Canva editor, this number is shown as points (pts), not pixels.
  • Minimum: 1
  • Maximum: 100
textAlignstring
OPTIONAL

The alignment of the text.

Default Value: "start"

The available options include:

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

The available options include:

  • "none"
  • "disc"
  • "circle"
  • "square"
  • "decimal"
  • "lower-alpha"
  • "lower-roman"
  • "checked"
  • "unchecked"

Returns

void

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.

Properties of bounds
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.

Properties of formatting
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"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

void

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

Options for formatting inline richtext.

Properties of formatting
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"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

A segment of a richtext range.

Properties of bounds
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
REQUIRED

Replaces a region of text with the specified characters.

Parameters

boundsBounds
REQUIRED

The segment of the range to replace.

Properties of bounds
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.

Properties of formatting
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"

The available options include:

  • "normal"
  • "thin"
  • "extralight"
  • "light"
  • "medium"
  • "semibold"
  • "bold"
  • "ultrabold"
  • "heavy"
fontStylestring
OPTIONAL

The style of the font.

Default Value: "normal"

The available options include:

  • "normal"
  • "italic"
decorationstring
OPTIONAL

The decoration of the text.

Default Value: "none"

The available options include:

  • "none"
  • "underline"
strikethroughstring
OPTIONAL

The strikethrough of the text.

Default Value: "none"

The available options include:

  • "none"
  • "strikethrough"

Returns

boundsBounds

The bounds of the replacement characters within the updated range.

Properties of bounds
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
REQUIRED

Returns the current state of the richtext as plaintext.

Returns

string

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.

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
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180
widthnumber
OPTIONAL

The width of the element, in pixels.

  • Minimum: 0
  • Maximum: 32767
backgroundPageBackgroundFill
OPTIONAL

The page background. This can be a solid color, an image or a video.

Properties of background
assetobject
OPTIONAL

An image or video to use as the fill.

An image asset that fills a path's interior.

typestring
REQUIRED

The type of fill.

This must be "image".

refImageRef
REQUIRED

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

A video asset that fills a path's interior.

typestring
REQUIRED

The type of fill.

This must be "video".

refVideoRef
REQUIRED

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

colorstring
OPTIONAL

The color of the fill as a hex code.

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

Example

" #ff0099"
TS
titlestring
OPTIONAL

A page title which must be no longer than 255 characters

Returns

Promise<void>