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

# Text replacement

Replace selected text elements with custom content.

## 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 text_replacement
   ```

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 { useSelection } from "@canva/app-hooks";
    import * as styles from "styles/components.css";

    export const App = () => {
      // Hook to track plaintext selection in the Canva editor
      const selection = useSelection("plaintext");

      const updateText = async () => {
        // Create a draft of the selected text elements to enable modification
        const draft = await selection.read();
        // Iterate through all selected text elements and append '!' to each
        draft.contents.forEach((s) => (s.text = `${s.text}!`));
        // Apply the changes to the design
        await draft.save();
      };

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="2u">
            <Text>
              This example demonstrates how apps can replace the selected text.
              Select text in the editor to begin.
            </Text>
            <Button
              variant="primary"
              onClick={updateText}
              disabled={selection.count === 0}
            >
              Append '!'
            </Button>
          </Rows>
        </div>
      );
    };
    ```
  </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
    # Text replacement

    Demonstrates how to replace selected plain text elements in a design with new text content. Shows simple text selection detection and text substitution patterns using the Canva Apps SDK selection API.

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

    Related examples: See content_replacement/richtext_replacement for formatted text replacement, or content_replacement/text_translation for advanced text transformation.

    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 capabilities
    - Text handling is simplified for demonstration. Production apps should handle various text formats, provide validation, and include undo functionality for better user experience
    - Error handling is minimal for demonstration. Production apps must implement comprehensive error handling with clear user feedback and graceful failure modes for network issues and API errors
    - 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
    - The app uses simplified selection logic. Production apps should handle edge cases like mixed content selection and provide clear feedback when no valid text is selected
    ```
  </Tab>
</Tabs>

## API reference

* [App UI Kit](https://www.canva.dev/docs/apps/app-ui-kit/)
* [`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)