> ## 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. # addElementAtPoint API reference for the addElementAtPoint method. NOTE: **This API is a preview**. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable. Add element to fixed designs, which use a coordinate-based positioning system. ## Usage ### Insert an image at specific coordinates ```typescript import { addElementAtPoint } from "@canva/design"; import type { ImageElementAtPoint } from "@canva/design"; import type { ImageRef } from "@canva/asset"; const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef; const imageElement: ImageElementAtPoint = { type: 'image', ref: exampleImageRef, altText: { text: 'Product image', decorative: false }, top: 100, left: 100, width: 300, height: 200 }; await addElementAtPoint(imageElement); ``` ### Insert a video at specific coordinates ```typescript import { addElementAtPoint } from "@canva/design"; import type { VideoElementAtPoint } from "@canva/design"; import type { VideoRef } from "@canva/asset"; const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef; const videoElement: VideoElementAtPoint = { type: 'video', ref: exampleVideoRef, altText: { text: 'Product demo', decorative: false }, top: 100, left: 100, width: 400, height: 300 }; await addElementAtPoint(videoElement); ``` ### Insert embedded content at specific coordinates ```typescript import { addElementAtPoint } from "@canva/design"; import type { EmbedElementAtPoint } from "@canva/design"; const embedElement: EmbedElementAtPoint = { type: 'embed', url: 'https://www.youtube.com/watch?v=...', top: 100, left: 100, width: 560, height: 315 }; await addElementAtPoint(embedElement); ``` ### Insert text at specific coordinates ```typescript import { addElementAtPoint } from "@canva/design"; import type { TextElementAtPoint } from "@canva/design"; const textElement: TextElementAtPoint = { type: 'text', children: ['Hello World'], top: 100, left: 100, width: 200, fontSize: 24, color: '#000000', textAlign: 'justify' }; await addElementAtPoint(textElement); ``` ## Parameters An element that's natively supported by the Canva editor. An element that renders image content. 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. 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. 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. Options for configuring the cropping of the video. Properties of imageBox}> The distance of the image box from the top edge of the video, in pixels. The distance of the image box from the left edge of the video, in pixels. The width of the image box, in pixels. The height of the image box, in pixels. Options for configuring the start, and end of the video. Properties of trim}> The start point of the video, in seconds relative to the start of the source video. The end point of the video, in seconds relative to the start of the source video. An element that renders rich media, such as a YouTube video. 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. An element that renders text content. The type of element. The only valid value is `"text"`. The text content. Only the first element in this array is used. 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"` An element that renders a vector shape. 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"`. An element that contains two or more elements. 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. An element that renders richtext content. 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 }; }); ``` An element that renders a table. The type of element. The only valid value is `"table"`. The rows of the table. Properties of rows}> The cells (columns) of the row. Each row must have the same number of cells. This should be either the following object, `null`, or `undefined`. The attributes of the cell. Properties of attributes}> The background color of the cell, as a hex code. 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"` The number of columns that the cell occupies. The number of rows that the cell occupies. **Available values**: * `"empty"` * `"string"` The plaintext content of the cell. If an empty string is provided, the `type` will change to `"empty"`. An element that's natively supported by the Canva editor and has positional properties. 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` Options for configuring the cropping of the video. Properties of imageBox}> The distance of the image box from the top edge of the video, in pixels. The distance of the image box from the left edge of the video, in pixels. The width of the image box, in pixels. The height of the image box, in pixels. Options for configuring the start, and end of the video. Properties of trim}> The start point of the video, in seconds relative to the start of the source video. The end point of the video, in seconds relative to the start of the source video. 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` ## Returns `Promise` ## 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 30 requests every 10 seconds. This limit is shared with the `addElementAtCursor` and `addNativeElement` methods.