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

# Embed elements

Add interactive embed elements 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 embed_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 { useCallback, useState } from "react";
    import * as styles from "styles/components.css";
    import { Button, FormField, Rows, Text, TextInput } from "@canva/app-ui-kit";
    import { addElementAtCursor, addElementAtPoint } from "@canva/design";
    import { useFeatureSupport } from "@canva/app-hooks";

    export const App = () => {
      const [url, setUrl] = useState(
        "https://www.youtube.com/embed/L3MtFGWRXAA?si=duU555FqmToATe2j",
      );
      // Hook for adding design elements to the current Canva design
      const isSupported = useFeatureSupport();
      const addElement = [addElementAtPoint, addElementAtCursor].find((fn) =>
        isSupported(fn),
      );

      const disabled = url.trim().length < 1;

      const addEmbed = useCallback(() => {
        if (!addElement) {
          return;
        }

        // Add an embed element to the design using the embed element API
        // Supports URLs from platforms like YouTube, Vimeo, Spotify, etc.
        addElement({
          type: "embed",
          url,
        });
      }, [url, addElement]);

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="3u">
            <Text>
              This example demonstrates how apps can add embed elements to a design.
            </Text>
            <FormField
              label="URL"
              value={url}
              control={(props) => (
                <TextInput
                  {...props}
                  onChange={(value) => {
                    setUrl(value);
                  }}
                />
              )}
            />
            <Button
              variant="primary"
              onClick={addEmbed}
              disabled={disabled || !addElement}
              tooltipLabel={
                !addElement
                  ? "This feature is not supported in the current page"
                  : undefined
              }
              stretch
            >
              Add element
            </Button>
          </Rows>
        </div>
      );
    };
    ```
  </Tab>

  <Tab name="index.tsx">
    ```typescript
    // For usage information, see the README.md file.
    import { AppUiProvider } from "@canva/app-ui-kit";
    import { createRoot } from "react-dom/client";
    import { App } from "./app";
    import "@canva/app-ui-kit/styles.css";
    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
    # Embed elements

    Demonstrates how to add embed elements to designs using URLs from supported platforms. Shows embed creation, URL input handling, and embed insertion patterns.

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

    Related examples: See app_embed_elements for embeds within app elements, or drag_and_drop/drag_and_drop_embed for drag-and-drop embed insertion.

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

    - Content is hardcoded for demonstration purposes only. Production apps should provide user input interfaces for URL entry and dynamic content loading
    - URL validation and sanitization is simplified for demonstration. Production apps must implement comprehensive URL validation and support multiple embed platforms
    - 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/)
* [`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)