> ## Documentation Index > Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt > Use this file to discover all available pages before exploring further. # addPage API reference for the addPage method. Adds a new page immediately after the currently selected page. By default, the new page is inserted immediately after the currently selected page. Pass `insertAt` to insert the page at a different position. ## Usage ### Create empty page and get the metadata ```typescript import { addPage } from "@canva/design"; const pageMetadata = await addPage(); const { id, title, dimensions, type } = pageMetadata; ``` ### Create page with title ```typescript import { addPage } from "@canva/design"; await addPage({ title: 'My New Page' }); ``` ### Create page with background color ```typescript import { addPage } from "@canva/design"; import type { PageBackgroundFill } from "@canva/design"; const background: PageBackgroundFill = { color: '#F5F5F5', }; await addPage({ background }); ``` ### Create page with background image ```typescript 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 ```typescript 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, ] }); ``` ### Create page with custom dimensions ```typescript import { addPage } from "@canva/design"; await addPage({ dimensions: { width: 300, height: 300, }, }); ``` ## Parameters Configuration for the new page to be added. Properties of opts}> Elements to be added to the page. An element that renders image content and has positional properties. The type of element. The only valid value is `"image"`. A description of the image content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` A data URL that contains the image data. A unique identifier that points to an image asset in Canva's backend. An element that renders video content and has positional properties. The type of element. The only valid value is `"video"`. A unique identifier that points to a video asset in Canva's backend. A description of the video content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` An element that renders rich media, such as a YouTube video, and has positional properties. The type of element. The only valid value is `"embed"`. The URL of the rich media. This URL must be supported by the Iframely API. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` An element that renders text content and has positional properties. The type of element. The only valid value is `"text"`. The text content. Only the first element in this array is used. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The size of the text. **Minimum**: `1` **Maximum**: `1000` **Default value**: `16` The alignment of the text. **Default value**: `"start"` **Available values**: * `"start"` * `"center"` * `"end"` * `"justify"` The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` A unique identifier that points to a font asset in Canva's backend. The weight (thickness) of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"thin"` * `"extralight"` * `"light"` * `"medium"` * `"semibold"` * `"bold"` * `"ultrabold"` * `"heavy"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the font. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` The width of the element, in pixels. **Minimum**: `0` **Maximum**: `32767` An element that renders a vector shape and has positional properties. The type of element. The only valid value is `"shape"`. Options for configuring the scale and cropping of the shape. Properties of viewBox}> The distance of the shape from the top edge of the element, in pixels. The distance of the shape from the left edge of the element, in pixels. The width of the view box, in pixels. The height of the view box, in pixels. 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}> 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 The appearance of the path's interior. Properties of fill}> If `true`, users can replace a fill by dropping an image or video onto it. The color of the fill as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` An image or video to use as the fill. An image asset that fills a path's interior. The type of fill. The only valid value is `"image"`. A unique identifier that points to an image asset in Canva's backend. A description of the image content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. A video asset that fills a path's interior. The type of fill. The only valid value is `"video"`. A unique identifier that points to a video asset in Canva's backend. A description of the image content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. The outline of the path. Properties of stroke}> The weight (thickness) of the stroke. **Minimum**: `0` **Maximum**: `100` The color of the stroke as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` The alignment of the stroke. The only valid value is `"inset"`. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` An element that contains two or more elements and has positional properties. The type of element. The only valid value is `"group"`. 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. The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A width, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` A height, in pixels. * The pixels are relative to their container. **Minimum**: `0` **Maximum**: `32767` 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. The type of element. The only valid value is `"richtext"`. The richtext content. Properties of range}> 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** The segment of the range on which to apply the formatting. Properties of bounds}> The starting position of the segment. This is zero-based, meaning the first character of the range is at index 0. The number of characters in the segment, starting from the index. The formatting to apply to the paragraph(s). Properties of formatting}> The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` 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"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` The strikethrough of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"strikethrough"` An external URL that the text links to. A unique identifier that points to a font asset in Canva's backend. The size of the text, in pixels. * In the Canva editor, this number is shown as points (pts), not pixels. **Minimum**: `1` **Maximum**: `1000` The alignment of the text. **Default value**: `"start"` **Available values**: * `"start"` * `"center"` * `"end"` * `"justify"` The list indentation level of the paragraph. 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"` The line height of the paragraph, relative to the font size expressed in Em. **Minimum**: `0.5` **Maximum**: `2.5` **Default value**: `1.4` The spacing between characters, relative to the font size expressed in Em. * In the Canva editor, this number is shown as a multiple of 1000. **Minimum**: `-0.2` **Maximum**: `0.8` **Default value**: `0` **Returns** `void` **Examples** **Format paragraph as a heading** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("Heading Text\nRegular paragraph text."); // Format just the first paragraph as a heading range.formatParagraph( { index: 0, length: 12 }, // Only need to include part of the paragraph { fontSize: 24, fontWeight: 'bold', textAlign: 'center' } ); ``` **Create a bulleted list** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); const text = "Item 1\nItem 2\nItem 3"; range.appendText(text); // Format all paragraphs as a bulleted list range.formatParagraph( { index: 0, length: text.length }, { listLevel: 1, listMarker: 'disc' } ); ``` Formats a region of text with inline formatting properties. **Parameters** The segment of the range on which to apply the formatting. Properties of bounds}> The starting position of the segment. This is zero-based, meaning the first character of the range is at index 0. The number of characters in the segment, starting from the index. The formatting to apply to the text. Properties of formatting}> The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` 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"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` The strikethrough of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"strikethrough"` An external URL that the text links to. **Returns** `void` **Examples** **Format specific words in a paragraph** ```typescript 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** ```typescript 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' } ); ``` Appends the specified characters to the end of the range. **Parameters** The characters to append to the richtext range. Optional formatting to apply to the appended text. Properties of formatting}> The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` 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"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` The strikethrough of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"strikethrough"` An external URL that the text links to. **Returns** A segment of a richtext range. Properties of bounds}> The starting position of the segment. This is zero-based, meaning the first character of the range is at index 0. The number of characters in the segment, starting from the index. **Examples** **Append plain text** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("First paragraph. "); // Append more text to the existing content const result = range.appendText("This is additional text."); // The bounds of the newly added text are returned // Do something with the bounds - result.bounds, e.g. { index: 17, length: 24 } ``` **Append formatted text** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("Normal text followed by "); // Append formatted text range.appendText("bold red text", { fontWeight: 'bold', color: '#FF0000' }); // Append a new paragraph range.appendText("\nThis is a new paragraph."); ``` Replaces a region of text with the specified characters. **Parameters** The segment of the range to replace. Properties of bounds}> The starting position of the segment. This is zero-based, meaning the first character of the range is at index 0. The number of characters in the segment, starting from the index. The replacement characters. The formatting to apply to the replaced text. Properties of formatting}> The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` 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"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` The strikethrough of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"strikethrough"` An external URL that the text links to. **Returns** The bounds of the replacement characters within the updated range. Properties of bounds}> The starting position of the segment. This is zero-based, meaning the first character of the range is at index 0. The number of characters in the segment, starting from the index. **Examples** **Replace text while maintaining some formatting** ```typescript 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** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("Regular text that needs emphasis."); // Replace "needs emphasis" with formatted text range.replaceText( { index: 17, length: 15 }, "is important", { fontWeight: 'bold', fontStyle: 'italic', color: '#0066CC' } ); ``` Returns the current state of the richtext as plaintext. **Returns** `string` **Examples** **Extract plain text content** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("First paragraph.\n", { fontWeight: 'bold' }); range.appendText("Second paragraph with formatting.", { color: '#FF0000' }); // Get plain text content without formatting const plainText = range.readPlaintext(); // Do something with the plain text - plainText, e.g. "First paragraph.\nSecond paragraph with formatting." ``` **Search within text content** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("This text contains a searchable term."); // Search for a specific word const plainText = range.readPlaintext(); const searchTerm = "searchable"; const index = plainText.indexOf(searchTerm); if (index !== -1) { // Format the found term range.formatText( { index, length: searchTerm.length }, { fontWeight: 'bold', decoration: 'underline' } ); } ``` 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** The plaintext content of the region. The formatting of the region. Properties of formatting}> The color of the text as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` 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"` The style of the font. **Default value**: `"normal"` **Available values**: * `"normal"` * `"italic"` The decoration of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"underline"` The strikethrough of the text. **Default value**: `"none"` **Available values**: * `"none"` * `"strikethrough"` An external URL that the text links to. A unique identifier that points to a font asset in Canva's backend. The size of the text, in pixels. * In the Canva editor, this number is shown as points (pts), not pixels. **Minimum**: `1` **Maximum**: `1000` The alignment of the text. **Default value**: `"start"` **Available values**: * `"start"` * `"center"` * `"end"` * `"justify"` The list indentation level of the paragraph. 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"` The line height of the paragraph, relative to the font size expressed in Em. **Minimum**: `0.5` **Maximum**: `2.5` **Default value**: `1.4` The spacing between characters, relative to the font size expressed in Em. * In the Canva editor, this number is shown as a multiple of 1000. **Minimum**: `-0.2` **Maximum**: `0.8` **Default value**: `0` **Examples** **Get text with formatting information** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("Normal text ", {}); range.appendText("bold text", { fontWeight: 'bold' }); range.appendText(" and ", {}); range.appendText("red text", { color: '#FF0000' }); // Get formatted regions const regions = range.readTextRegions(); // Do something with the regions, e.g. // [ // { text: "Normal text ", formatting: {} }, // { text: "bold text", formatting: { fontWeight: 'bold' } }, // { text: " and ", formatting: {} }, // { text: "red text", formatting: { color: '#FF0000' } } // ] ``` **Analyze formatting variations** ```typescript import { createRichtextRange } from "@canva/design"; const range = createRichtextRange(); range.appendText("Mixed ", {}); range.appendText("formatted ", { fontWeight: 'bold' }); range.appendText("text", { color: '#0066CC' }); // Analyze formatting variations const regions = range.readTextRegions(); const formattingTypes = regions.map(region => { const formatting = region.formatting || {}; return { text: region.text, hasWeight: !!formatting.fontWeight, hasColor: !!formatting.color }; }); ``` The distance from the top edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` The distance from the left edge of the container, in pixels. * The pixels are relative to their container. **Minimum**: `-32768` **Maximum**: `32767` A rotation, in degrees. **Minimum**: `-180` **Maximum**: `180` The width of the element, in pixels. **Minimum**: `0` **Maximum**: `32767` The page background. This can be a solid color, an image or a video. Properties of background}> The color of the fill as a hex code. The hex code must include all six characters and be prefixed with a `#` symbol. **Example** ```ts "#ff0099" ``` An image or video to use as the fill. An image asset that fills a path's interior. The type of fill. The only valid value is `"image"`. A unique identifier that points to an image asset in Canva's backend. A description of the image content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. A video asset that fills a path's interior. The type of fill. The only valid value is `"video"`. A unique identifier that points to a video asset in Canva's backend. A description of the image content. Use `undefined` for content with no description. Properties of altText}> The text content. 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. A page title which must be no longer than 255 characters The optional custom dimensions in pixels for the new page. The following constraints apply: * `width` and `height` cannot be lower than 40 or higher than 8000 * The total area of the new page cannot exceed 25\_000\_000 In case this is not specified, the default dimensions for the design type will be used. Properties of dimensions}> ## Returns The metadata of the added page. This is a `Promise` that resolves with the following object: Information about a page within a design with fixed or unbounded dimensions. The type of page. The only valid value is `"absolute"`. Stable identifier for this page within the design. The dimensions of the page, in pixels. This may be `undefined` because some types of pages don't have dimensions, such as whiteboards. Properties of dimensions}> The width of the page, in pixels. The height of the page, in pixels. The name of the page. This is optional and will be empty if the user hasn't set a title. Pages that do not have fixed or unbounded dimensions currently do not return metadata. The type of page. The only valid value is `"unsupported"`. ## Permissions To use this method, the `canva:design:content:write` permission must be enabled for the app. To learn more, see [Permissions](https://www.canva.dev/docs/apps/configuring-intents-permissions/). ## Rate limit This method has a rate limit of 10 requests every 10 seconds.