addPage
Adds a new page immediately after the currently selected page.
Usage
Create empty page
import { addPage } from "@canva/design";await addPage();
Create page with title
import { addPage } from "@canva/design";await addPage({title: 'My New Page'});
Create page with background color
import { addPage } from "@canva/design";import type { PageBackgroundFill } from "@canva/design";const background: PageBackgroundFill = {color: '#F5F5F5',};await addPage({ background });
Create page with background image
import { addPage } from "@canva/design";import type { PageBackgroundFill } from "@canva/design";import type { ImageRef } from "@canva/asset";const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;const background: PageBackgroundFill = {asset: {type: 'image',ref: exampleImageRef,altText: { text: 'Background image', decorative: true }},};await addPage({ background });
Create page with multiple elements
import { addPage } from "@canva/design";import type { TextElementAtPoint, ImageElementAtPoint } from "@canva/design";import type { ImageRef } from "@canva/asset";const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;await addPage({elements: [{type: 'text',children: ['Page Title'],top: 50,left: 100,width: 400,fontSize: 32,textAlign: 'center'} as TextElementAtPoint,{type: 'text',children: ['Subtitle text'],top: 100,left: 100,width: 400,fontSize: 18,textAlign: 'center'} as TextElementAtPoint,{type: 'image',ref: exampleImageRef,altText: { text: 'Featured image', decorative: false },top: 150,left: 200,width: 200,height: 200} as ImageElementAtPoint,]});
Parameters
optsobjectConfiguration for the new page to be added.
elementsElementAtPoint[]Elements to be added to the page
An element that renders image content and has positional properties.
typestringThe type of element.
The only valid value is "image".
altTextAltText | undefinedA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
dataUrlstringA data URL that contains the image data.
refImageRefA unique identifier that points to an image asset in Canva's backend.
An element that renders video content and has positional properties.
typestringThe type of element.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltText | undefinedA description of the video content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that renders rich media, such as a YouTube video, and has positional properties.
typestringThe type of element.
The only valid value is "embed".
urlstringThe URL of the rich media.
This URL must be supported by the Iframely API.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that renders text content and has positional properties.
typestringThe type of element.
The only valid value is "text".
childrenstring[]The text content.
Only the first element in this array is used.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
fontSizenumberThe size of the text.
Minimum: 1
Maximum: 100
Default value: 16
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontWeightFontWeightThe weight (thickness) of the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the font.
Default value: "none"
Available values:
"none""underline"
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
widthnumberThe width of the element, in pixels.
Minimum: 0
Maximum: 32767
An element that renders a vector shape and has positional properties.
typestringThe type of element.
The only valid value is "shape".
viewBoxShapeViewBoxOptions for configuring the scale and cropping of the shape.
topnumberThe distance of the shape from the top edge of the element, in pixels.
leftnumberThe distance of the shape from the left edge of the element, in pixels.
widthnumberThe width of the view box, in pixels.
heightnumberThe height of the view box, in pixels.
pathsShapePath[]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.
dstringThe 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
fillFillThe appearance of the path's interior.
dropTargetbooleanIf true, users can replace a fill by dropping an image or video onto it.
colorstringThe color of the fill as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
assetobjectAn image or video to use as the fill.
An image asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "image".
refImageRefA unique identifier that points to an image asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
A video asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
strokePathStrokeThe outline of the path.
weightnumberThe weight (thickness) of the stroke.
Minimum: 0
Maximum: 100
colorstringThe color of the stroke as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
strokeAlignstringThe alignment of the stroke.
The only valid value is "inset".
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
An element that contains two or more elements and has positional properties.
typestringThe type of element.
The only valid value is "group".
childrenGroupContentAtPoint[]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.
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
widthnumberA width, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
heightnumberA height, in pixels.
- The pixels are relative to their container.
Minimum: 0
Maximum: 32767
rotationnumberA 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.
typestringThe type of element.
The only valid value is "richtext".
rangeRichtextRangeThe richtext content.
formatParagraphfunctionFormats all of the paragraphs that overlap the given bounds.
- The
\ncharacter indicates the end of a paragraph. - All paragraphs that overlap the provided bounds will be formatted in their entirety.
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingRichtextFormattingThe formatting to apply to the paragraph(s).
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe appearance of list item markers.
This property only has an effect if listLevel is greater than 0.
Default value: "none"
Available values:
"none""disc""circle""square""decimal""lower-alpha""lower-roman""checked""unchecked"
Returns
void
Examples
Format paragraph as a heading
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Heading Text\nRegular paragraph text.");// Format just the first paragraph as a headingrange.formatParagraph({ index: 0, length: 12 }, // Only need to include part of the paragraph{fontSize: 24,fontWeight: 'bold',textAlign: 'center'});
Create a bulleted list
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();const text = "Item 1\nItem 2\nItem 3";range.appendText(text);// Format all paragraphs as a bulleted listrange.formatParagraph({ index: 0, length: text.length },{listLevel: 1,listMarker: 'disc'});
formatTextfunctionFormats a region of text with inline formatting properties.
Parameters
boundsBoundsThe segment of the range on which to apply the formatting.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
formattingInlineFormattingThe formatting to apply to the text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
void
Examples
Format specific words in a paragraph
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains important information.");// Format just the word "important"range.formatText({ index: 16, length: 9 },{fontWeight: 'bold',color: '#FF0000'});
Add a link to text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Visit our website for more information.");// Add a link to "our website"range.formatText({ index: 6, length: 11 },{link: "https://www.example.com",decoration: 'underline',color: '#0066CC'});
appendTextfunctionAppends the specified characters to the end of the range.
Parameters
charactersstringThe characters to append to the richtext range.
formattingInlineFormattingOptional formatting to apply to the appended text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsA segment of a richtext range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Append plain text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph. ");// Append more text to the existing contentconst result = range.appendText("This is additional text.");// The bounds of the newly added text are returned// Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 }
Append formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text followed by ");// Append formatted textrange.appendText("bold red text", {fontWeight: 'bold',color: '#FF0000'});// Append a new paragraphrange.appendText("\nThis is a new paragraph.");
replaceTextfunctionReplaces a region of text with the specified characters.
Parameters
boundsBoundsThe segment of the range to replace.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
charactersstringThe replacement characters.
formattingInlineFormattingThe formatting to apply to the replaced text.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
Returns
boundsBoundsThe bounds of the replacement characters within the updated range.
indexnumberThe starting position of the segment.
This is zero-based, meaning the first character of the range is at index 0.
lengthnumberThe number of characters in the segment, starting from the index.
Examples
Replace text while maintaining some formatting
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text needs correction.");// Replace "needs correction" with "is correct"const result = range.replaceText({ index: 10, length: 16 },"is correct");// The bounds of the replaced text are returned// Do something with the bounds - result.bounds, e.g. { index: 10, length: 10 }
Replace text with formatted text
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Regular text that needs emphasis.");// Replace "needs emphasis" with formatted textrange.replaceText({ index: 17, length: 15 },"is important",{fontWeight: 'bold',fontStyle: 'italic',color: '#0066CC'});
readPlaintextfunctionReturns the current state of the richtext as plaintext.
Returns
string
Examples
Extract plain text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("First paragraph.\n", { fontWeight: 'bold' });range.appendText("Second paragraph with formatting.", { color: '#FF0000' });// Get plain text content without formattingconst plainText = range.readPlaintext();// Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting."
Search within text content
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("This text contains a searchable term.");// Search for a specific wordconst plainText = range.readPlaintext();const searchTerm = "searchable";const index = plainText.indexOf(searchTerm);if (index !== -1) {// Format the found termrange.formatText({ index, length: searchTerm.length },{ fontWeight: 'bold', decoration: 'underline' });}
readTextRegionsfunctionReturns the current state of the richtext as one or more text regions. Each region is an object that contains the text content and its formatting.
Returns
textstringThe plaintext content of the region.
formattingPartial<RichtextFormatting>The formatting of the region.
colorstringThe color of the text as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
fontWeightFontWeightThe weight (thickness) of the font.
The available font weights depend on the font.
Default value: "normal"
Available values:
"normal""thin""extralight""light""medium""semibold""bold""ultrabold""heavy"
fontStylestringThe style of the font.
Default value: "normal"
Available values:
"normal""italic"
decorationstringThe decoration of the text.
Default value: "none"
Available values:
"none""underline"
strikethroughstringThe strikethrough of the text.
Default value: "none"
Available values:
"none""strikethrough"
linkstringAn external URL that the text links to.
fontRefFontRefA unique identifier that points to a font asset in Canva's backend.
fontSizenumberThe size of the text, in pixels.
- In the Canva editor, this number is shown as points (pts), not pixels.
Minimum: 1
Maximum: 100
textAlignstringThe alignment of the text.
Default value: "start"
Available values:
"start""center""end""justify"
listLevelnumberThe list indentation level of the paragraph.
listMarkerstringThe appearance of list item markers.
This property only has an effect if listLevel is greater than 0.
Default value: "none"
Available values:
"none""disc""circle""square""decimal""lower-alpha""lower-roman""checked""unchecked"
Examples
Get text with formatting information
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Normal text ", {});range.appendText("bold text", { fontWeight: 'bold' });range.appendText(" and ", {});range.appendText("red text", { color: '#FF0000' });// Get formatted regionsconst regions = range.readTextRegions();// Do something with the regions, e.g.// [// { text: "Normal text ", formatting: {} },// { text: "bold text", formatting: { fontWeight: 'bold' } },// { text: " and ", formatting: {} },// { text: "red text", formatting: { color: '#FF0000' } }// ]
Analyze formatting variations
import { createRichtextRange } from "@canva/design";const range = createRichtextRange();range.appendText("Mixed ", {});range.appendText("formatted ", { fontWeight: 'bold' });range.appendText("text", { color: '#0066CC' });// Analyze formatting variationsconst regions = range.readTextRegions();const formattingTypes = regions.map(region => {const formatting = region.formatting || {};return {text: region.text,hasWeight: !!formatting.fontWeight,hasColor: !!formatting.color};});
topnumberThe distance from the top edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
leftnumberThe distance from the left edge of the container, in pixels.
- The pixels are relative to their container.
Minimum: -32768
Maximum: 32767
rotationnumberA rotation, in degrees.
Minimum: -180
Maximum: 180
widthnumberThe width of the element, in pixels.
Minimum: 0
Maximum: 32767
backgroundPageBackgroundFillThe page background. This can be a solid color, an image or a video.
colorstringThe color of the fill as a hex code.
The hex code must include all six characters and be prefixed with a # symbol.
Example
"#ff0099"
assetobjectAn image or video to use as the fill.
An image asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "image".
refImageRefA unique identifier that points to an image asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
A video asset that fills a path's interior.
typestringThe type of fill.
The only valid value is "video".
refVideoRefA unique identifier that points to a video asset in Canva's backend.
altTextAltTextA description of the image content.
Use undefined for content with no description.
textstringThe text content.
decorativeboolean | undefinedIndicates where the alternative text should be displayed.
- If
true, the alternative text will only be displayed in the editor. - If
false, the alternative text will be displayed in the editor and in view-only mode.
titlestringA page title which must be no longer than 255 characters
Returns
Promise<void>