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

# selection.registerOnChange

API reference for the selection.registerOnChange method.

Registers a callback that runs when the specified type of content is selected.

* This callback fires immediately if content is already selected when the callback is registered.
* App elements are not supported by this API. For managing selection and updates to app elements, please refer to the `initAppElement` API call for details and examples.

## Usage

### Handling plaintext selection

```typescript
import { selection } from "@canva/design";

selection.registerOnChange({
  scope: 'plaintext',
  onChange: async (event) => {
    if (event.count > 0) {
      const draft = await event.read();
      // Do something with the selected text, e.g. `draft.contents[0].text`
    }
  }
});
```

### Handling image selection

```typescript
import { selection } from "@canva/design";

selection.registerOnChange({
  scope: 'image',
  onChange: async (event) => {
    if (event.count > 0) {
      const draft = await event.read();
      // Do something with the selected image ref, e.g. `draft.contents[0].ref`
    }
  }
});
```

### Edit selected image and upload with parentRef

```typescript
import { selection } from "@canva/design";
import { getTemporaryUrl, upload } from "@canva/asset";

selection.registerOnChange({
  scope: 'image',
  onChange: async (event) => {
    if (event.count > 0) {
      const draft = await event.read();

      for (const content of draft.contents) {
        // Fetch a temporary URL to the original image
        const { url } = await getTemporaryUrl({
          type: "image",
          ref: content.ref
        });

        // Apply any edits you want to the image
        const processedImageUrl = await applyImageEffect(url);

        // Upload the edited image with parentRef
        const asset = await upload({
          type: "image",
          parentRef: content.ref,
          url: processedImageUrl,
          mimeType: "image/jpeg",
          thumbnailUrl: processedImageUrl,
          aiDisclosure: "app_generated"
        });

        // Replace the image ref with the new image ref
        content.ref = asset.ref;
      }

      // Save the changes to the design
      await draft.save();
    }
  }
});
```

### Handling video selection

```typescript
import { selection } from "@canva/design";

selection.registerOnChange({
  scope: 'video',
  onChange: async (event) => {
    if (event.count > 0) {
      const draft = await event.read();
      // Do something with the selected video ref, e.g. `draft.contents[0].ref`
    }
  }
});
```

### Handling richtext selection

```typescript
import { selection } from "@canva/design";

selection.registerOnChange({
  scope: 'richtext',
  onChange: async (event) => {
    if (event.count > 0) {
      const draft = await event.read();
      const range = draft.contents[0];
      // Do something with the selected richtext, e.g. `range.readPlaintext()`
    }
  }
});
```

## Parameters

<Prop.List>
  <Prop name="opts" required type="object" sourceLineNumbers={[3650]}>
    Options for configuring the content selection callback.

    <PillAccordion defaultExpanded={true} title={<>Properties of <strong>opts</strong></>}>
      <Prop.List>
        <Prop name="scope" required type="Scope" sourceLineNumbers={[3654]}>
          The type of content that triggers a selection change event.

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

            * `"plaintext"`
            * `"image"`
            * `"video"`
            * `"richtext"`
          </Prop.Extras>
        </Prop>

        <Prop name="onChange" required type="function" sourceLineNumbers={[3659]}>
          The callback to run when the selected content changes.

          **Parameters**

          <Prop.List>
            <Prop name="event" required type="SelectionEvent<Scope>" sourceLineNumbers={[3659]}>
              Information about the selection change event.

              <PillAccordion defaultExpanded={false} title={<>Properties of <strong>event</strong></>}>
                <Prop.List>
                  <Prop name="scope" required readonly type="Scope" sourceLineNumbers={[6067]}>
                    The type of content that's selected.

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

                      * `"plaintext"`
                      * `"image"`
                      * `"video"`
                      * `"richtext"`
                    </Prop.Extras>
                  </Prop>

                  <Prop name="count" required readonly type="number" sourceLineNumbers={[6071]}>
                    The number of selected elements.
                  </Prop>

                  <Prop name="read" required type="function" sourceLineNumbers={[6142]}>
                    Creates a snapshot of the selected content and returns a *draft* object.
                    The draft has a mutable `contents` property for making changes to the selected content.
                    Any changes made to `contents` are not immediately persisted or reflected in the user's design.
                    To persist the changes, call the `save` method that's available via the draft.

                    **Returns**

                    A snapshot of content from a user's design. This is a `Promise` that resolves with the following object:

                    <Prop.List>
                      <Prop name="contents" required readonly type="SelectionValue<Scope>[]" sourceLineNumbers={[1317]}>
                        The individual content items that exist within the snapshot.

                        Any changes made to this array won't be reflected in the user's design until the `save` method is called.

                        <Tabs>
                          <Tab name="plaintext">
                            <Prop.List>
                              <Prop name="text" required type="string" sourceLineNumbers={[6166]}>
                                The text content.
                              </Prop>
                            </Prop.List>
                          </Tab>

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

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

                          <Tab name="richtext">
                            Provides methods for interacting with a range of formatted text.

                            <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>
                          </Tab>
                        </Tabs>
                      </Prop>

                      <Prop name="save" required type="function" sourceLineNumbers={[1377]}>
                        Saves changes made to the content items in the `contents` array.

                        Once this method is called:

                        * Any changes the app has made to to the content will be reflected in the user's design.
                        * Any changes the user has made to the content since the snapshot was created may be overwritten.
                        * Only properties that are different from the original state will be written to the design.

                        **Returns**

                        `Promise<void>`

                        <Prop.Extras>
                          **Examples**

                          **Save changes to selected text**

                          ```typescript
                          import { selection } from "@canva/design";

                          selection.registerOnChange({
                            scope: 'plaintext',
                            onChange: async (event) => {
                              if (event.count > 0) {
                                const draft = await event.read();

                                // Make changes to the content
                                for (const content of draft.contents) {
                                  content.text = content.text.toUpperCase();
                                }

                                // Save the changes to the design
                                await draft.save();
                              }
                            }
                          });
                          ```

                          **Modify then save rich text content**

                          ```typescript
                          import { selection } from "@canva/design";

                          selection.registerOnChange({
                            scope: 'richtext',
                            onChange: async (event) => {
                              if (event.count > 0) {
                                const draft = await event.read();
                                const range = draft.contents[0];

                                // Get the plain text
                                const text = range.readPlaintext();

                                // Apply formatting to the entire text
                                range.formatText(
                                  { index: 0, length: text.length },
                                  { fontWeight: 'bold', color: '#0066CC' }
                                );

                                // Save the formatted text back to the design
                                await draft.save();
                              }
                            }
                          });
                          ```
                        </Prop.Extras>
                      </Prop>
                    </Prop.List>

                    <Prop.Extras>
                      **Examples**

                      **Read and modify plaintext selection**

                      ```typescript
                      import { selection } from "@canva/design";

                      selection.registerOnChange({
                        scope: 'plaintext',
                        onChange: async (event) => {
                          if (event.count > 0) {
                            // Read the content
                            const draft = await event.read();

                            // Handle selected text `draft.contents[0].text`

                            // Modify the text if needed
                            // draft.contents[0].text = 'Modified text';
                            // await draft.save();
                          }
                        }
                      });
                      ```

                      **Read and analyze image selection**

                      ```typescript
                      import { selection } from "@canva/design";

                      selection.registerOnChange({
                        scope: 'image',
                        onChange: async (event) => {
                          // Check if any images are selected
                          if (event.count === 0) {
                            // Handle no images selected case
                            return;
                          }

                          // Read the content
                          const draft = await event.read();

                          // Get information about selected images
                          const imageRefs = draft.contents.map(content => content.ref);

                          // The ref can be used with other API methods
                        }
                      });
                      ```

                      **Process multiple selected items**

                      ```typescript
                      import { selection } from "@canva/design";

                      selection.registerOnChange({
                        scope: 'richtext',
                        onChange: async (event) => {
                          if (event.count > 0) {
                            const draft = await event.read();

                            // Process each selected range
                            draft.contents.forEach((range) => {
                              // Do something with the range content and formatted regions, with `range.readPlaintext()` and `range.readTextRegions()`
                            });
                          }
                        }
                      });
                      ```
                    </Prop.Extras>
                  </Prop>
                </Prop.List>
              </PillAccordion>
            </Prop>
          </Prop.List>

          **Returns**

          `void`
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Returns

() => `void`

## Permissions

To use this method, the following permissions must be enabled for the app:

* `canva:design:content:read`, to register the handler and call the `read` method
* `canva:design:content:write`, if the app calls the `save` method

To learn more, see [Permissions](https://www.canva.dev/docs/apps/configuring-intents-permissions/).

## Rate limit

This method has the following rate limits:

* `read`: 100 requests every 10 seconds
* `save`: 30 requests every 10 seconds