> ## 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. # PageHelpers API reference for the PageHelpers type. 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. Helpers for use with supported pages. Not applicable to unsupported pages. ## Type declaration Group specified elements. **Parameters** Options for grouping elements. Properties of opts}> Elements to be grouped. An element that renders a rectangle. The rectangle can be filled with image content, video content, or a solid color. The element type The only valid value is `"rect"`. Describes how a fill is filled with color or media. If both `media` and `color` are defined, `media` takes precedence. For more information, see [Fill](/docs/apps/api/preview/design-types-fill/). The outline of the rectangle. For more information, see [Stroke](/docs/apps/api/preview/design-types-stroke/). A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` An element that renders a vector shape. The type of content. The only valid value is `"shape"`. 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. For more information, see [ReadableList](/docs/apps/api/preview/design-types-readable-list/) and [Path](/docs/apps/api/preview/design-types-path/). A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` An element that embeds rich media, such as a YouTube video. The type of content. The only valid value is `"embed"`. The URL of the rich media. This URL must be supported by the Iframely API. A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` An element that renders text content. The only valid value is `"text"`. Provides methods for interacting with a range of formatted text. Properties of text}> 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 }; }); ``` A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` **Returns** a new group element containing all the given elements. This is a `Promise` that resolves with the following object: The type of content. The only valid value is `"group"`. The elements that exist within the group. For more information, see [ReadableList](/docs/apps/api/preview/design-types-readable-list/) and [GroupContentElement](/docs/apps/api/preview/design-types-group-content-element/). A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` Ungroup a group element. **Parameters** Options for ungrouping a group element. Properties of opts}> Group element to be ungroup. Properties of element}> The type of content. The only valid value is `"group"`. The elements that exist within the group. For more information, see [ReadableList](/docs/apps/api/preview/design-types-readable-list/) and [GroupContentElement](/docs/apps/api/preview/design-types-group-content-element/). A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` **Returns** new elements that are ungrouped from the given group. This is a `Promise` that resolves with a `AbsoluteElement[]` object. For more information, see [AbsoluteElement](/docs/apps/api/preview/design-types-absolute-element/). Build an element state that can be used to create an element with the `insert` methods of the page's element list For more information, see [ElementStateBuilder](/docs/apps/api/preview/design-types-element-state-builder/). Returns a [DataFieldAccessor](/docs/apps/api/preview/design-types-data-field-accessor/) for reading or updating the data-field mapping of a target on the current page. **Parameters** Identifies the target (a text element, rect element, or editable shape-path fill) to read or update. Properties of opts}> The target to read or update the data-field mapping for. Must belong to the current page. * A DesignEditing.TextElement connects to a `text` field. * A DesignEditing.RectElement connects its fill to a `fill` field. * A DesignEditing.PathFillWithEditableMedia connects that shape-path fill to a `fill` field. Pass the specific fill to disambiguate a shape with multiple paths. An element that renders text content. The only valid value is `"text"`. Provides methods for interacting with a range of formatted text. Properties of text}> 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 }; }); ``` A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` An element that renders a rectangle. The rectangle can be filled with image content, video content, or a solid color. The element type The only valid value is `"rect"`. Describes how a fill is filled with color or media. If both `media` and `color` are defined, `media` takes precedence. For more information, see [Fill](/docs/apps/api/preview/design-types-fill/). The outline of the rectangle. For more information, see [Stroke](/docs/apps/api/preview/design-types-stroke/). A width, in pixels. A height, in pixels. If `true`, the element is locked and cannot be modified. 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` Transparency as a percentage. **Minimum**: `0` **Maximum**: `1` The only valid value is `true`. A media fill, if any. Properties of mediaContainer}> **Parameters** A state that creates an image fill. The type of media. The only valid value is `"image"`. A unique identifier that points to an image asset in Canva's backend. If `true`, the image is flipped horizontally. If `true`, the image is flipped vertically. A state that creates a video fill. The type of media. The only valid value is `"video"`. A unique identifier that points to a video asset in Canva's backend. If `true`, the video is flipped horizontally. If `true`, the video is flipped vertically. **Returns** `void` An image that fills the interior of a media. The type of media. The only valid value is `"image"`. A unique identifier that points to an image asset in Canva's backend. If `true`, the image is flipped horizontally. If `true`, the image is flipped vertically. A video that fills the interior of a media. The type of media. The only valid value is `"video"`. A unique identifier that points to a video asset in Canva's backend. If `true`, the video is flipped horizontally. If `true`, the video is flipped vertically. A color fill, if any. Properties of colorContainer}> **Parameters** Properties of state}> The type of color. The only valid value is `"solid"`. The color of the fill. This must be a valid, six-digit hex code, prefixed with a `#` symbol. * Must be six characters long. * Must start with a `#`. * Must use lowercase letters. **Example** ```ts "#ff0099" ``` **Returns** `void` A solid color that fills an interior. The type of color. The only valid value is `"solid"`. The color of the fill. This must be a valid, six-digit hex code, prefixed with a `#` symbol. * Must be six characters long. * Must start with a `#`. * Must use lowercase letters. **Example** ```ts "#ff0099" ``` Represents design content that the SDK doesn't support. The only valid value is `"unsupported"`. **Returns** Reads and updates the data-field mapping of a single target — obtained from [DesignEditing.PageHelpers.getDataFieldFor](/docs/apps/api/preview/design-types-page-helpers/). Updates the data-field mapping and the dataset definition. Supported targets are text (connected to a field of type `text`) and fills (connected to a field of type `fill`). When `label` is present: * If a field with the same label already exists in the dataset definition and its type is compatible with the target type, the target is connected to that existing field. * If a field with the same label exists but has a different type, `set` resolves to `{ status: "incompatible_data_field_type" }`. * If no compatible field exists and the dataset definition has reached the field limit, `set` resolves to `{ status: "data_field_limit_exceeded" }`. * Otherwise a new field is added to the dataset definition with a randomly generated id. The field type is inferred from the target type, and the target is connected to it. When `label` is Unset: * The data-field mapping is removed from the target. * The dataset definition is not cleaned up; unused fields are left in place. Unused fields continue to count toward the document's data-field limit and may be reused by later calls to `set`. Developer mistakes, such as unsupported targets or invalid fill/parent combinations, throw `CanvaError({ code: "bad_request" })`. `getDesignMetadata()` only returns committed data fields. Fields staged during the current `openDesign` transaction are not visible through `getDesignMetadata()` until `sync()` commits the changes. For more information, see [DataFieldAccessor](/docs/apps/api/preview/design-types-data-field-accessor/).