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

# Richtext elements

Add rich text elements with formatting to designs.

## Running this example

To run this example locally:

1. If you haven't already, create a new app in the [Developer Portal](https://www.canva.com/developers/apps). For more information, refer to our [Quickstart guide](https://www.canva.dev/docs/apps/quickstart/).

2. In your app's configuration on the [Developer Portal](https://www.canva.com/developers/apps), ensure the "Development URL" is set to `http://localhost:8080`.

3. Clone the starter kit:

   ```shell
   git clone https://github.com/canva-sdks/canva-apps-sdk-starter-kit.git
   cd canva-apps-sdk-starter-kit
   ```

4. Install dependencies:

   ```shell
   npm install
   ```

5. Run the example:
   ```shell
   npm run start:example richtext_elements
   ```

6. Click the **Preview URL** link shown in the terminal to open the example in the Canva editor.

## Example app source code

<Tabs>
  <Tab name="app.tsx">
    ```typescript
    // For usage information, see the README.md file.
    import { Button, Rows, Text } from "@canva/app-ui-kit";
    import {
      addElementAtCursor,
      addElementAtPoint,
      createRichtextRange,
    } from "@canva/design";
    import type {
      RichtextElement,
      RichtextElementAtPoint,
      TextRegion,
    } from "@canva/design";
    import * as styles from "styles/components.css";
    import { useEffect, useState } from "react";
    import { useFeatureSupport } from "@canva/app-hooks";

    // Create a global RichtextRange instance - this manages text content and formatting
    let richtext = createRichtextRange();

    export const App = () => {
      // Track text regions to display the richtext structure
      const [regions, setRegions] = useState<TextRegion[]>([]);
      // Hook to add elements to the Canva design
      const isSupported = useFeatureSupport();
      const addElement = [addElementAtPoint, addElementAtCursor].find((fn) =>
        isSupported(fn),
      );

      useEffect(() => {
        reset();
      }, []);

      const reset = () => {
        // Create a new RichtextRange instance and populate with initial text
        richtext = createRichtextRange();
        richtext.appendText(
          "This is an example richtext.\nUsing the RichtextRange API, individual parts of the text can be formatted.",
        );
        // Update the regions state to reflect the current richtext structure
        setRegions(richtext.readTextRegions());
      };

      const formatText = () => {
        // Apply text-level formatting (color and style) to the first word
        richtext.formatText(
          { index: 0, length: 4 },
          {
            color: "#ff0000",
            fontStyle: "italic",
          },
        );
        setRegions(richtext.readTextRegions());
      };

      const formatParagraph = () => {
        // Apply paragraph-level formatting (font size and alignment) to the second paragraph
        richtext.formatParagraph(
          {
            index: "This is an example richtext.\n".length,
            length: 1,
          },
          {
            fontSize: 40,
            textAlign: "end",
            lineHeightEm: 1,
            letterSpacingEm: 0.1,
          },
        );
        setRegions(richtext.readTextRegions());
      };

      const replaceText = () => {
        // Replace the first word with alternate text to demonstrate text replacement
        richtext.replaceText(
          {
            index: 0,
            length: 4,
          },
          richtext.readPlaintext().startsWith("This") ? "Here" : "This",
        );
        setRegions(richtext.readTextRegions());
      };

      const appendText = () => {
        // Add additional text to the end of the richtext content
        richtext.appendText(" This is appended text.");
        setRegions(richtext.readTextRegions());
      };

      const addToDesign = async () => {
        const elementInFixedDesigns: RichtextElementAtPoint = {
          type: "richtext",
          range: richtext,
          top: 100,
          left: 100,
          width: 200,
        };

        const elementInResponsiveDesigns: RichtextElement = {
          type: "richtext",
          range: richtext,
        };

        if (!addElement) {
          return;
        } else if (isSupported(addElementAtPoint)) {
          // Add RichtextElementAtPoint to fixed designs
          await addElement(elementInFixedDesigns);
        } else {
          // Add RichtextElement to responsive designs
          await addElement(elementInResponsiveDesigns);
        }
      };

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="2u">
            <Text>This example demonstrates how apps can add richtext.</Text>
            <Regions regions={regions} />
            <Button variant="secondary" onClick={formatText}>
              Format first word
            </Button>
            <Button variant="secondary" onClick={formatParagraph}>
              Format second paragraph
            </Button>
            <Button variant="secondary" onClick={appendText}>
              Append text
            </Button>
            <Button variant="secondary" onClick={replaceText}>
              Replace first word
            </Button>
            <Button variant="secondary" onClick={reset}>
              Reset
            </Button>
            <Button
              variant="primary"
              onClick={addToDesign}
              disabled={!addElement}
              tooltipLabel={
                !addElement
                  ? "This feature is not supported in the current page"
                  : undefined
              }
            >
              Add richtext to design
            </Button>
          </Rows>
        </div>
      );
    };

    // Display the TextRegion structure to show how richtext is internally represented
    const Regions = ({ regions }: { regions: TextRegion[] }) => {
      return (
        <pre style={{ textWrap: "wrap", fontSize: 14 }}>
          {JSON.stringify(regions, null, 2)}
        </pre>
      );
    };
    ```
  </Tab>

  <Tab name="index.tsx">
    ```typescript
    // For usage information, see the README.md file.
    import { createRoot } from "react-dom/client";
    import { App } from "./app";
    import "@canva/app-ui-kit/styles.css";
    import { AppUiProvider } from "@canva/app-ui-kit";
    import type { DesignEditorIntent } from "@canva/intents/design";
    import { prepareDesignEditor } from "@canva/intents/design";

    async function render() {
      const root = createRoot(document.getElementById("root") as Element);

      root.render(
        <AppUiProvider>
          <App />
        </AppUiProvider>,
      );
    }

    const designEditor: DesignEditorIntent = { render };
    prepareDesignEditor(designEditor);

    // Hot Module Replacement for development (automatically reloads the app when changes are made)
    if (module.hot) {
      module.hot.accept("./app", render);
    }
    ```
  </Tab>

  <Tab name="README.md">
    ```markdown
    # Rich text elements

    Demonstrates how to create and format rich text elements using RichtextRange API. Shows text formatting, paragraph styling, and rich text manipulation for creating styled text content.

    For API reference docs and instructions on running this example, see: https://www.canva.dev/docs/apps/examples/richtext-elements/.

    Related examples: See design_elements/text_elements for basic text insertion, or content_replacement/richtext_replacement for modifying existing rich text.

    NOTE: This example differs from what is expected for public apps to pass a Canva review:

    - Text content is hardcoded for demonstration purposes only. Production apps should provide user input interfaces or dynamic content loading
    - Text validation and formatting options are simplified for demonstration. Production apps should include proper text validation and comprehensive formatting options
    - Error handling is simplified for demonstration. Production apps must implement comprehensive error handling with clear user feedback and graceful failure modes
    - Internationalization is not implemented. Production apps must support multiple languages using the `@canva/app-i18n-kit` package to pass Canva review requirements
    - The code structure is simplified: Production apps using [intents](https://www.canva.dev/docs/apps/intents/) are recommended to call the prepareDesignEditor function from src/intents/design_editor/index.tsx
    ```
  </Tab>
</Tabs>

## API reference

* [App UI Kit](https://www.canva.dev/docs/apps/app-ui-kit/)
* [`addElementAtCursor`](https://www.canva.dev/docs/apps/api/latest/design-add-element-at-cursor/)
* [`addElementAtPoint`](https://www.canva.dev/docs/apps/api/latest/design-add-element-at-point/)
* [`createRichtextRange`](https://www.canva.dev/docs/apps/api/latest/design-create-richtext-range/)
* [`prepareDesignEditor`](https://www.canva.dev/docs/apps/api/latest/intents-design-prepare-design-editor/)

## Need help?

* Join our [Community Forum](https://community.canva.dev/)
* Report issues with this example on [GitHub](https://github.com/canva-sdks/canva-apps-sdk-starter-kit/issues)