> ## 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.

# addElementAtCursor

API reference for the addElementAtCursor 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 responsive pages, which slot things into a text stream

## Usage

### Insert an image at cursor position

```typescript
import { addElementAtCursor } from "@canva/design";
import type { ImageElement } from "@canva/design";
import type { ImageRef } from "@canva/asset";

const exampleImageRef = "YOUR_IMAGE_REF" as ImageRef;

const imageElement: ImageElement = {
  type: 'image',
  ref: exampleImageRef,
  altText: { text: 'Product image', decorative: false }
};

await addElementAtCursor(imageElement);
```

### Insert a video at cursor position

```typescript
import { addElementAtCursor } from "@canva/design";
import type { VideoElement } from "@canva/design";
import type { VideoRef } from "@canva/asset";

const exampleVideoRef = "YOUR_VIDEO_REF" as VideoRef;

const videoElement: VideoElement = {
  type: 'video',
  ref: exampleVideoRef,
  altText: { text: 'Product demo', decorative: false }
};

await addElementAtCursor(videoElement);
```

### Insert embedded content at cursor position

```typescript
import { addElementAtCursor } from "@canva/design";
import type { EmbedElement } from "@canva/design";

const embedElement: EmbedElement = {
  type: 'embed',
  url: 'https://www.youtube.com/watch?v=...'
};

await addElementAtCursor(embedElement);
```

### Insert text at cursor position

```typescript
import { addElementAtCursor } from "@canva/design";
import type { TextElement } from "@canva/design";

const textElement: TextElement = {
  type: 'text',
  children: ['Hello World'],
  fontSize: 24,
  color: '#000000'
};

await addElementAtCursor(textElement);
```

### Insert formatted text at cursor position

```typescript
import { addElementAtCursor, createRichtextRange } from "@canva/design";
import type { RichtextElement } from "@canva/design";

const range = createRichtextRange();
range.appendText('Rich Text Content', { color: '#000000' });

const richtextElement: RichtextElement = {
  type: 'richtext',
  range
};

await addElementAtCursor(richtextElement);
```

### Insert a table at cursor position

```typescript
import { addElementAtCursor } from "@canva/design";
import type { TableElement } from "@canva/design";

const tableElement: TableElement = {
  type: 'table',
  rows: [
    {
      cells: [
        { type: 'string', value: 'Header 1' },
        { type: 'string', value: 'Header 2' }
      ]
    },
    {
      cells: [
        { type: 'string', value: 'Data 1' },
        { type: 'string', value: 'Data 2' }
      ]
    }
  ]
};

await addElementAtCursor(tableElement);
```

## Parameters

<Prop.List>
  <Prop name="element" required type="ElementAtCursor" sourceLineNumbers={[159]}>
    Elements targeting a cursor are a subset of the base Element

    <Tabs>
      <Tab name="Images">
        An element that renders image content.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[4470]}>
            The type of element.

            The only valid value is `"image"`.
          </Prop>

          <Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[4477]}>
            A description of the image content.

            Use `undefined` for content with no description.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>altText</strong></>}>
              <Prop.List>
                <Prop name="text" required type="string" sourceLineNumbers={[478]}>
                  The text content.
                </Prop>

                <Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[486]}>
                  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.
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>

          <Prop name="dataUrl" type="string" sourceLineNumbers={[4482]}>
            A data URL that contains the image data.
          </Prop>

          <Prop name="ref" type="ImageRef" sourceLineNumbers={[4495]}>
            A unique identifier that points to an image asset in Canva's backend.
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="Videos">
        An element that renders video content.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[6730]}>
            The type of element.

            The only valid value is `"video"`.
          </Prop>

          <Prop name="ref" required type="VideoRef" sourceLineNumbers={[6734]}>
            A unique identifier that points to a video asset in Canva's backend.
          </Prop>

          <Prop name="altText" required type="AltText | undefined" sourceLineNumbers={[6741]}>
            A description of the video content.

            Use `undefined` for content with no description.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>altText</strong></>}>
              <Prop.List>
                <Prop name="text" required type="string" sourceLineNumbers={[478]}>
                  The text content.
                </Prop>

                <Prop name="decorative" required type="boolean | undefined" sourceLineNumbers={[486]}>
                  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.
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>

          <Prop name="imageBox" state="preview" type="VideoImageBox" sourceLineNumbers={[6746]}>
            Options for configuring the cropping of the video.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>imageBox</strong></>}>
              <Prop.List>
                <Prop name="top" required type="number" sourceLineNumbers={[6790]}>
                  The distance of the image box from the top edge of the video, in pixels.
                </Prop>

                <Prop name="left" required type="number" sourceLineNumbers={[6794]}>
                  The distance of the image box from the left edge of the video, in pixels.
                </Prop>

                <Prop name="width" required type="number" sourceLineNumbers={[6798]}>
                  The width of the image box, in pixels.
                </Prop>

                <Prop name="height" required type="number" sourceLineNumbers={[6802]}>
                  The height of the image box, in pixels.
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>

          <Prop name="trim" state="preview" type="VideoTrim" sourceLineNumbers={[6751]}>
            Options for configuring the start, and end of the video.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>trim</strong></>}>
              <Prop.List>
                <Prop name="startInSeconds" required type="number" sourceLineNumbers={[6839]}>
                  The start point of the video, in seconds relative to the start of the source video.
                </Prop>

                <Prop name="endInSeconds" required type="number" sourceLineNumbers={[6843]}>
                  The end point of the video, in seconds relative to the start of the source video.
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="Embeds">
        An element that renders rich media, such as a YouTube video.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[3917]}>
            The type of element.

            The only valid value is `"embed"`.
          </Prop>

          <Prop name="url" required type="string" sourceLineNumbers={[3924]}>
            The URL of the rich media.

            This URL must be supported by the Iframely API.
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="Text">
        An element that renders text content.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[6575]}>
            The type of element.

            The only valid value is `"text"`.
          </Prop>

          <Prop name="children" required type="string[]" sourceLineNumbers={[6582]}>
            The text content.

            Only the first element in this array is used.
          </Prop>

          <Prop name="fontSize" type="number" sourceLineNumbers={[6474]}>
            The size of the text.

            <Prop.Extras>
              **Minimum**: `1`

              **Maximum**: `1000`

              **Default value**: `16`
            </Prop.Extras>
          </Prop>

          <Prop name="textAlign" type="string" sourceLineNumbers={[6479]}>
            The alignment of the text.

            <Prop.Extras>
              **Default value**: `"start"`
            </Prop.Extras>

            <Prop.Extras>
              **Available values**:

              * `"start"`
              * `"center"`
              * `"end"`
              * `"justify"`
            </Prop.Extras>
          </Prop>

          <Prop name="color" type="string" sourceLineNumbers={[6489]}>
            The color of the text as a hex code.

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

            <Prop.Extras>
              **Example**

              ```ts
              "#ff0099"
              ```
            </Prop.Extras>
          </Prop>

          <Prop name="fontRef" type="FontRef" sourceLineNumbers={[6494]}>
            A unique identifier that points to a font asset in Canva's backend.
          </Prop>

          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[6499]}>
            The weight (thickness) of the font.

            <Prop.Extras>
              **Default value**: `"normal"`
            </Prop.Extras>

            <Prop.Extras>
              **Available values**:

              * `"normal"`
              * `"thin"`
              * `"extralight"`
              * `"light"`
              * `"medium"`
              * `"semibold"`
              * `"bold"`
              * `"ultrabold"`
              * `"heavy"`
            </Prop.Extras>
          </Prop>

          <Prop name="fontStyle" type="string" sourceLineNumbers={[6504]}>
            The style of the font.

            <Prop.Extras>
              **Default value**: `"normal"`
            </Prop.Extras>

            <Prop.Extras>
              **Available values**:

              * `"normal"`
              * `"italic"`
            </Prop.Extras>
          </Prop>

          <Prop name="decoration" type="string" sourceLineNumbers={[6509]}>
            The decoration of the font.

            <Prop.Extras>
              **Default value**: `"none"`
            </Prop.Extras>

            <Prop.Extras>
              **Available values**:

              * `"none"`
              * `"underline"`
            </Prop.Extras>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="Richtext">
        An element that renders richtext content.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[5703]}>
            The type of element.

            The only valid value is `"richtext"`.
          </Prop>

          <Prop name="range" required type="RichtextRange" sourceLineNumbers={[5707]}>
            The richtext content.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>range</strong></>}>
              <Prop.List>
                <Prop name="formatParagraph" required type="function" sourceLineNumbers={[5834]}>
                  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**

                  <Prop.List>
                    <Prop name="bounds" required type="Bounds" sourceLineNumbers={[5834]}>
                      The segment of the range on which to apply the formatting.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
                        <Prop.List>
                          <Prop name="index" required type="number" sourceLineNumbers={[1126]}>
                            The starting position of the segment.

                            This is zero-based, meaning the first character of the range is at index 0.
                          </Prop>

                          <Prop name="length" required type="number" sourceLineNumbers={[1130]}>
                            The number of characters in the segment, starting from the index.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="formatting" required type="RichtextFormatting" sourceLineNumbers={[5834]}>
                      The formatting to apply to the paragraph(s).

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
                        <Prop.List>
                          <Prop name="color" type="string" sourceLineNumbers={[4766]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4775]}>
                            The weight (thickness) of the font.

                            The available font weights depend on the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[4780]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[4785]}>
                            The decoration of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="strikethrough" type="string" sourceLineNumbers={[4790]}>
                            The strikethrough of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"strikethrough"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="link" type="string" sourceLineNumbers={[4794]}>
                            An external URL that the text links to.
                          </Prop>

                          <Prop name="fontRef" type="FontRef" sourceLineNumbers={[5731]}>
                            A unique identifier that points to a font asset in Canva's backend.
                          </Prop>

                          <Prop name="fontSize" type="number" sourceLineNumbers={[5740]}>
                            The size of the text, in pixels.

                            * In the Canva editor, this number is shown as points (pts), not pixels.

                            <Prop.Extras>
                              **Minimum**: `1`

                              **Maximum**: `1000`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="textAlign" type="string" sourceLineNumbers={[5745]}>
                            The alignment of the text.

                            <Prop.Extras>
                              **Default value**: `"start"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"start"`
                              * `"center"`
                              * `"end"`
                              * `"justify"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="listLevel" type="number" sourceLineNumbers={[5749]}>
                            The list indentation level of the paragraph.
                          </Prop>

                          <Prop name="listMarker" type="string" sourceLineNumbers={[5758]}>
                            The appearance of list item markers.

                            This property only has an effect if `listLevel` is greater than 0.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"disc"`
                              * `"circle"`
                              * `"square"`
                              * `"decimal"`
                              * `"lower-alpha"`
                              * `"lower-roman"`
                              * `"checked"`
                              * `"unchecked"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="lineHeightEm" type="number" sourceLineNumbers={[5768]}>
                            The line height of the paragraph, relative to the font size expressed in Em.

                            <Prop.Extras>
                              **Minimum**: `0.5`

                              **Maximum**: `2.5`

                              **Default value**: `1.4`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="letterSpacingEm" type="number" sourceLineNumbers={[5779]}>
                            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.

                            <Prop.Extras>
                              **Minimum**: `-0.2`

                              **Maximum**: `0.8`

                              **Default value**: `0`
                            </Prop.Extras>
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  **Returns**

                  `void`

                  <Prop.Extras>
                    **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'
                      }
                    );
                    ```
                  </Prop.Extras>
                </Prop>

                <Prop name="formatText" required type="function" sourceLineNumbers={[5876]}>
                  Formats a region of text with inline formatting properties.

                  **Parameters**

                  <Prop.List>
                    <Prop name="bounds" required type="Bounds" sourceLineNumbers={[5876]}>
                      The segment of the range on which to apply the formatting.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
                        <Prop.List>
                          <Prop name="index" required type="number" sourceLineNumbers={[1126]}>
                            The starting position of the segment.

                            This is zero-based, meaning the first character of the range is at index 0.
                          </Prop>

                          <Prop name="length" required type="number" sourceLineNumbers={[1130]}>
                            The number of characters in the segment, starting from the index.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="formatting" required type="InlineFormatting" sourceLineNumbers={[5876]}>
                      The formatting to apply to the text.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
                        <Prop.List>
                          <Prop name="color" type="string" sourceLineNumbers={[4766]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4775]}>
                            The weight (thickness) of the font.

                            The available font weights depend on the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[4780]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[4785]}>
                            The decoration of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="strikethrough" type="string" sourceLineNumbers={[4790]}>
                            The strikethrough of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"strikethrough"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="link" type="string" sourceLineNumbers={[4794]}>
                            An external URL that the text links to.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  **Returns**

                  `void`

                  <Prop.Extras>
                    **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'
                      }
                    );
                    ```
                  </Prop.Extras>
                </Prop>

                <Prop name="appendText" required type="function" sourceLineNumbers={[5914]}>
                  Appends the specified characters to the end of the range.

                  **Parameters**

                  <Prop.List>
                    <Prop name="characters" required type="string" sourceLineNumbers={[5914]}>
                      The characters to append to the richtext range.
                    </Prop>

                    <Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[5914]}>
                      Optional formatting to apply to the appended text.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
                        <Prop.List>
                          <Prop name="color" type="string" sourceLineNumbers={[4766]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4775]}>
                            The weight (thickness) of the font.

                            The available font weights depend on the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[4780]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[4785]}>
                            The decoration of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="strikethrough" type="string" sourceLineNumbers={[4790]}>
                            The strikethrough of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"strikethrough"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="link" type="string" sourceLineNumbers={[4794]}>
                            An external URL that the text links to.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  **Returns**

                  <Prop.List>
                    <Prop name="bounds" required type="Bounds" sourceLineNumbers={[5915]}>
                      A segment of a richtext range.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
                        <Prop.List>
                          <Prop name="index" required type="number" sourceLineNumbers={[1126]}>
                            The starting position of the segment.

                            This is zero-based, meaning the first character of the range is at index 0.
                          </Prop>

                          <Prop name="length" required type="number" sourceLineNumbers={[1130]}>
                            The number of characters in the segment, starting from the index.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  <Prop.Extras>
                    **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.");
                    ```
                  </Prop.Extras>
                </Prop>

                <Prop name="replaceText" required type="function" sourceLineNumbers={[5960]}>
                  Replaces a region of text with the specified characters.

                  **Parameters**

                  <Prop.List>
                    <Prop name="bounds" required type="Bounds" sourceLineNumbers={[5960]}>
                      The segment of the range to replace.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
                        <Prop.List>
                          <Prop name="index" required type="number" sourceLineNumbers={[1126]}>
                            The starting position of the segment.

                            This is zero-based, meaning the first character of the range is at index 0.
                          </Prop>

                          <Prop name="length" required type="number" sourceLineNumbers={[1130]}>
                            The number of characters in the segment, starting from the index.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="characters" required type="string" sourceLineNumbers={[5960]}>
                      The replacement characters.
                    </Prop>

                    <Prop name="formatting" type="InlineFormatting" sourceLineNumbers={[5960]}>
                      The formatting to apply to the replaced text.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
                        <Prop.List>
                          <Prop name="color" type="string" sourceLineNumbers={[4766]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4775]}>
                            The weight (thickness) of the font.

                            The available font weights depend on the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[4780]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[4785]}>
                            The decoration of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="strikethrough" type="string" sourceLineNumbers={[4790]}>
                            The strikethrough of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"strikethrough"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="link" type="string" sourceLineNumbers={[4794]}>
                            An external URL that the text links to.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  **Returns**

                  <Prop.List>
                    <Prop name="bounds" required type="Bounds" sourceLineNumbers={[5964]}>
                      The bounds of the replacement characters within the updated range.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>bounds</strong></>}>
                        <Prop.List>
                          <Prop name="index" required type="number" sourceLineNumbers={[1126]}>
                            The starting position of the segment.

                            This is zero-based, meaning the first character of the range is at index 0.
                          </Prop>

                          <Prop name="length" required type="number" sourceLineNumbers={[1130]}>
                            The number of characters in the segment, starting from the index.
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  <Prop.Extras>
                    **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'
                      }
                    );
                    ```
                  </Prop.Extras>
                </Prop>

                <Prop name="readPlaintext" required type="function" sourceLineNumbers={[6003]}>
                  Returns the current state of the richtext as plaintext.

                  **Returns**

                  `string`

                  <Prop.Extras>
                    **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' }
                      );
                    }
                    ```
                  </Prop.Extras>
                </Prop>

                <Prop name="readTextRegions" required type="function" sourceLineNumbers={[6050]}>
                  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**

                  <Prop.List>
                    <Prop name="text" required type="string" sourceLineNumbers={[6599]}>
                      The plaintext content of the region.
                    </Prop>

                    <Prop name="formatting" type="Partial<RichtextFormatting>" sourceLineNumbers={[6603]}>
                      The formatting of the region.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>formatting</strong></>}>
                        <Prop.List>
                          <Prop name="color" type="string" sourceLineNumbers={[4766]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[4775]}>
                            The weight (thickness) of the font.

                            The available font weights depend on the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[4780]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[4785]}>
                            The decoration of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="strikethrough" type="string" sourceLineNumbers={[4790]}>
                            The strikethrough of the text.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"strikethrough"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="link" type="string" sourceLineNumbers={[4794]}>
                            An external URL that the text links to.
                          </Prop>

                          <Prop name="fontRef" type="FontRef" sourceLineNumbers={[5731]}>
                            A unique identifier that points to a font asset in Canva's backend.
                          </Prop>

                          <Prop name="fontSize" type="number" sourceLineNumbers={[5740]}>
                            The size of the text, in pixels.

                            * In the Canva editor, this number is shown as points (pts), not pixels.

                            <Prop.Extras>
                              **Minimum**: `1`

                              **Maximum**: `1000`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="textAlign" type="string" sourceLineNumbers={[5745]}>
                            The alignment of the text.

                            <Prop.Extras>
                              **Default value**: `"start"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"start"`
                              * `"center"`
                              * `"end"`
                              * `"justify"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="listLevel" type="number" sourceLineNumbers={[5749]}>
                            The list indentation level of the paragraph.
                          </Prop>

                          <Prop name="listMarker" type="string" sourceLineNumbers={[5758]}>
                            The appearance of list item markers.

                            This property only has an effect if `listLevel` is greater than 0.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"disc"`
                              * `"circle"`
                              * `"square"`
                              * `"decimal"`
                              * `"lower-alpha"`
                              * `"lower-roman"`
                              * `"checked"`
                              * `"unchecked"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="lineHeightEm" type="number" sourceLineNumbers={[5768]}>
                            The line height of the paragraph, relative to the font size expressed in Em.

                            <Prop.Extras>
                              **Minimum**: `0.5`

                              **Maximum**: `2.5`

                              **Default value**: `1.4`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="letterSpacingEm" type="number" sourceLineNumbers={[5779]}>
                            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.

                            <Prop.Extras>
                              **Minimum**: `-0.2`

                              **Maximum**: `0.8`

                              **Default value**: `0`
                            </Prop.Extras>
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>
                  </Prop.List>

                  <Prop.Extras>
                    **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
                      };
                    });
                    ```
                  </Prop.Extras>
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="Tables">
        An element that renders a table.

        <Prop.List>
          <Prop name="type" required type="string" sourceLineNumbers={[6430]}>
            The type of element.

            The only valid value is `"table"`.
          </Prop>

          <Prop name="rows" required type="object[]" sourceLineNumbers={[6434]}>
            The rows of the table.

            <PillAccordion defaultExpanded={false} title={<>Properties of <strong>rows</strong></>}>
              <Prop.List>
                <Prop name="cells" required type="Array<Cell | null | undefined>" sourceLineNumbers={[6441]}>
                  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`.

                  <Prop.List>
                    <Prop name="attributes" type="CellAttributes" sourceLineNumbers={[1226]}>
                      The attributes of the cell.

                      <PillAccordion defaultExpanded={false} title={<>Properties of <strong>attributes</strong></>}>
                        <Prop.List>
                          <Prop name="backgroundColor" type="string" sourceLineNumbers={[1245]}>
                            The background color of the cell, as a hex code.
                          </Prop>

                          <Prop name="fontSize" type="number" sourceLineNumbers={[6474]}>
                            The size of the text.

                            <Prop.Extras>
                              **Minimum**: `1`

                              **Maximum**: `1000`

                              **Default value**: `16`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="textAlign" type="string" sourceLineNumbers={[6479]}>
                            The alignment of the text.

                            <Prop.Extras>
                              **Default value**: `"start"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"start"`
                              * `"center"`
                              * `"end"`
                              * `"justify"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="color" type="string" sourceLineNumbers={[6489]}>
                            The color of the text as a hex code.

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

                            <Prop.Extras>
                              **Example**

                              ```ts
                              "#ff0099"
                              ```
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontRef" type="FontRef" sourceLineNumbers={[6494]}>
                            A unique identifier that points to a font asset in Canva's backend.
                          </Prop>

                          <Prop name="fontWeight" type="FontWeight" sourceLineNumbers={[6499]}>
                            The weight (thickness) of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"thin"`
                              * `"extralight"`
                              * `"light"`
                              * `"medium"`
                              * `"semibold"`
                              * `"bold"`
                              * `"ultrabold"`
                              * `"heavy"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="fontStyle" type="string" sourceLineNumbers={[6504]}>
                            The style of the font.

                            <Prop.Extras>
                              **Default value**: `"normal"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"normal"`
                              * `"italic"`
                            </Prop.Extras>
                          </Prop>

                          <Prop name="decoration" type="string" sourceLineNumbers={[6509]}>
                            The decoration of the font.

                            <Prop.Extras>
                              **Default value**: `"none"`
                            </Prop.Extras>

                            <Prop.Extras>
                              **Available values**:

                              * `"none"`
                              * `"underline"`
                            </Prop.Extras>
                          </Prop>
                        </Prop.List>
                      </PillAccordion>
                    </Prop>

                    <Prop name="colSpan" type="number" sourceLineNumbers={[1230]}>
                      The number of columns that the cell occupies.
                    </Prop>

                    <Prop name="rowSpan" type="number" sourceLineNumbers={[1234]}>
                      The number of rows that the cell occupies.
                    </Prop>

                    <Prop name="type" required type="string" sourceLineNumbers={[1257]}>
                      <Prop.Extras>
                        **Available values**:

                        * `"empty"`
                        * `"string"`
                      </Prop.Extras>
                    </Prop>

                    <Prop name="value" required="Required if `type` is string" type="string" sourceLineNumbers={[1269]}>
                      The plaintext content of the cell.

                      If an empty string is provided, the `type` will change to `"empty"`.
                    </Prop>
                  </Prop.List>
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>
    </Tabs>
  </Prop>
</Prop.List>

## Returns

`Promise<void>`

## 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 `addElementAtPoint` and `addNativeElement` methods.