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

# Open external link

Open external URLs safely from within Canva apps.

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

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, Link, Rows, Text, Title } from "@canva/app-ui-kit";
    import { requestOpenExternalUrl } from "@canva/platform";
    import * as styles from "styles/components.css";

    const DOCS_URL =
      "https://www.canva.dev/docs/apps/api/platform-request-open-external-url/";
    const GUIDELINES_URL =
      "https://www.canva.dev/docs/apps/design-guidelines/external-links/";
    const ACCEPTING_PAYMENTS_URL =
      "https://www.canva.dev/docs/apps/accepting-payments/";

    export const App = () => {
      const openExternalUrl = async (url: string) => {
        // requestOpenExternalUrl requires user consent before opening external URLs
        // This ensures users are aware they're leaving the Canva environment
        const response = await requestOpenExternalUrl({
          url,
        });

        // Handle user consent response - users can abort the navigation
        if (response.status === "aborted") {
          // User decided not to navigate to the external link
          // In production apps, you might want to show feedback or alternative actions
        }
      };

      return (
        <div className={styles.scrollContainer}>
          <Rows spacing="1u">
            <Text>
              To learn more about how to open external URLs in your app, head over
              to the{" "}
              {/* Link component with requestOpenExternalUrl prop handles external navigation */}
              <Link
                href={DOCS_URL}
                requestOpenExternalUrl={() => openExternalUrl(DOCS_URL)}
                ariaLabel="Canva Apps SDK docs"
              >
                docs
              </Link>
              .
            </Text>
            <Title>Guidelines</Title>
            <Text>Be sure to check out the guidelines below</Text>
            <Button
              variant="secondary"
              onClick={() => openExternalUrl(GUIDELINES_URL)}
            >
              Design Guidelines
            </Button>
            <Button
              variant="secondary"
              onClick={() => openExternalUrl(ACCEPTING_PAYMENTS_URL)}
            >
              Payment links
            </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 provides Canva's design system theming and accessibility features
        <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
    # Open external links

    Demonstrates how to handle external link navigation with proper user consent and security patterns. Shows the use of `requestOpenExternalUrl` API, user confirmation workflows, and compliance with external navigation guidelines.

    For API reference docs and instructions on running this example, see: <https://www.canva.dev/docs/apps/examples/open-external-link/>.

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

    - Error handling is simplified for demonstration purposes. Production apps must implement comprehensive error handling with clear user feedback and graceful failure modes when external URL requests fail
    - 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/)
* [`prepareDesignEditor`](https://www.canva.dev/docs/apps/api/latest/intents-design-prepare-design-editor/)
* [`requestOpenExternalUrl`](https://www.canva.dev/docs/apps/api/latest/platform-request-open-external-url/)

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